跳转至
For the complete DHIS2 documentation index, see llms.txt.
使用API

/api/messages?ou=Sllsjdhoe3

processedDate

/api/messages?processedDate=2016-02-01

Program Notification Instance

/api/programNotificationInstances exposes program notification instances, i.e. concrete scheduled or sent notifications created from program notification templates.

Returns program notification instances, optionally filtered and paginated.

GET /api/programNotificationInstances

Table: Query program notification instance API

| Name         | Type              | Required | Description                                                                                                                   |
|-------------|-------------------|----------|-------------------------------------------------------------------------------------------------------------------------------|
| `scheduledAt` | `date` (ISO-8601) | no       | Returns notification instances scheduled to be sent on the given date. Example: `scheduledAt=2025-01-01`.                    |
| `paging`      | `boolean`         | no       | Enables or disables pagination. Default is `true`. Use `paging=false` to return all matching instances without pagination.   |
| `page`        | `integer`         | no       | Page number to return when pagination is enabled.                                                                            |
| `pageSize`    | `integer`         | no       | Number of items per page when pagination is enabled.                                                                         |
| `event`       | `UID`             | no       | Program notification instances attached to this enrollment.                                                                   |
| `enrollment`  | `UID`             | no       | Program notification instances attached to this event.                                                                   |



# Email { #email } 

## Email { #webapi_email } 

The Web API features a resource for sending emails. For emails to be
sent it is required that the SMTP configuration has been properly set up
and that a system notification email address for the DHIS2 instance has
been defined. You can set SMTP settings from the email settings screen
and system notification email address from the general settings screen
in DHIS2.

    /api/33/email

### System notification { #webapi_email_system_notification } 

The *notification* resource lets you send system email notifications
with a given subject and text in JSON or XML. The email will be sent to
the notification email address as defined in the DHIS2 general system
settings:

```json
{
  "subject": "Integrity check summary",
  "text": "All checks ran successfully"
}

您可以通过发布到通知来发送系统电子邮件通知 像这样的资源:

| 响应示例: | Parameter name | 您还可以通过发布到 通知资源如下所述。 F_SEND_EMAIL 或 ALL 权限必须在系统中才能使用这个 api。主题 参数是可选的。 “DHIS 2”字符串将作为默认主题发送 如果 url 中没有提供。应该对 URL 进行编码才能使用它 应用项目接口。 | |---|---|---| | bash curl "localhost/api/33/email/notification?recipients=xyz%40abc.com&message=sample%20email&subject=Test%20Email" -X POST -u admin:district | The previous example is convenient for short messages. However, since the message is passed as a query string, it can quickly hit the URL length limit of the server. For longer messages, it is better to send the data in the POST request body. The following example shows how to send an email with a longer message in the request body: | 具有以下要求: | | To send an email with an HTML body, you can simply provide the HTML content in the message parameter. The email client should interpret the HTML and render it accordingly. Note that the Content-Type header in the curl command should be application/x-www-form-urlencoded, as the data is sent as URL-encoded form data. The following example shows how to send an email with a simple HTML table: | bash curl -u admin:district -X POST 'localhost/api/33/email/notification' \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'recipients=recipient1@example.com,recipient2@example.com' \ --data-urlencode 'subject=System Maintenance Schedule' \ --data-urlencode 'message=<html><body><h2>System Maintenance</h2><p>Dear user,</p><p>We are writing to inform you about scheduled system maintenance. The following table shows the maintenance schedule for the upcoming week:</p><table border="1"><tr><th>Day</th><th>Time</th></tr><tr><td>Monday</td><td>10 PM - 11 PM</td></tr><tr><td>Wednesday</td><td>10 PM - 11 PM</td></tr></table><p>We apologize for any inconvenience this may cause. Please plan your work accordingly.</p><p>Best regards,<br>The DHIS2 Team</p></body></html>' | 具有以下要求: | | json { "object": { "publicAccess": "rw------", "externalAccess": false, "user": {}, "userAccesses": [], "userGroupAccesses": [ { "id": "hj0nnsVsPLU", "access": "rw------" }, { "id": "qMjBflJMOfB", "access": "r-------" } ] } } | bash curl "localhost/api/33/email/test" -X POST -H "Content-Type:application/json" -u admin:district | 数据存储 { #data-store } | | / api / 33 / userDataStore | 使用 dataStore 资源,开发人员可以存储任意数据 他们的应用项目。对数据存储密钥的访问基于其共享设置。 默认情况下,所有创建的密钥都可以公开访问(读取和写入)。 此外,对数据存储命名空间的访问仅限于用户的 访问相应的应用项目,如果应用项目保留了命名空间。 例如,有权访问“sampleApp”应用项目的用户也将 能够使用数据存储中的 sampleApp 命名空间。如果一个命名空间 没有保留,使用它不需要特定的访问权限。 | userDataStore 由用户、命名空间、键和关联的 值。用户、命名空间和密钥的组合是唯一的。 |

Note that there are reserved namespaces used by the system that require

special authority to be able to read or write entries. For example the namespace for the android settings app ANDROID_SETTINGS_APP will require the M_androidsettingsapp authority.

数据存储结构 { #webapi_data_store_structure }

数据存储条目由命名空间、键和值组成。这 命名空间和键的组合是唯一的。值数据类型为 JSON。

Table: Data store structure

项目

Indicates whether the value of the given key should be encrypted

数据类型

命名空间

Namespace for organization of entries.

Table: Data store structure

键

Indicates whether the value of the given key should be encrypted

串

值

Value holding the information for the entry.

JSON格式

Encrypted

Indicates whether the value of the given key should be encrypted

Boolean

获取键和名称空间 { #webapi_data_store_get_keys_and_namespaces }

有关所有现有名称空间的列表:

JSON格式

清单示例curl请求:

Indicates whether the value of the given key should be encrypted

响应示例:

```json

[ "foo", "bar" ] 

有关命名空间中所有键的列表:

    GET /api/33/dataStore/<namespace>

清单示例curl请求:

* ```bash
curl "play.dhis2.org/demo/api/33/dataStore/foo" -u admin:district
* 响应示例: * ```json [ "key_1", "key_2" ] 
要从名称空间检索现有键的值:

    GET /api/33/dataStore/<namespace>/<key>

卷曲请求检索示例:

#### ```bash
curl "play.dhis2.org/demo/api/33/dataStore/foo/key_1"-u admin:district
响应示例: 
{
  "foo":"bar"
}

要从名称空间检索现有键的元数据:

GET /api/33/dataStore/<namespace>/<key>/metaData

卷曲请求检索示例: bash curl "play.dhis2.org/demo/api/33/dataStore/foo/key_1/metaData" -u admin:district

响应示例:

{
  "id": "dsKeyUid001", 
  "created": "...",
  "user": {...},
  "namespace": "foo",
  "key": "key_1"
}

查询应用项目接口{ #query-api }

The query API is allows you to query and filter values over all keys in a namespace. The fields parameter is used to specify the query. This is useful for retrieving specific values of keys across a namespace in a single request. 

GET /api/dataStore/<namespace>?fields=

The list of fields can be:

empty: returns just the entry keys

.: return the root value as stored

comma separated list of paths: <path>[,<path>]; each <path> can be a simple property name (like age) or a nested path (like person.age)

Furthermore, entries can be filtered using one or more filter parameters and sorted using the order parameter.

Multiple filters can be combined using rootJunction=OR (default) or rootJunction=AND.

All details on the fields, filter and order parameters are given in the following sections.

Paging { #paging }

By default, results use paging. Use pageSize and page to adjust size and offset. The parameter paging=false can be used to opt-out and always return all matches. This should be used with caution as there could be many entries in a namespace. The default page size is 50.

GET /api/dataStore/<namespace>?fields=.&page=2&pageSize=10

When paging is turned off, entries are returned as plain result array as the root JSON structure. The same effect can be achieved while having paged results by using headless=true.

{
  "pager": { ... },
  "entries": [...]
}

vs.

[...]

Value extraction { #value-extraction }

The data store allows extracting entire simple or complex values as well as the extraction of parts of complex JSON values.

Note

For clarity of the examples the responses shown mostly omit the outermost object with the pager information and the entries array that the examples show.

To filter a certain set of fields add a fields parameter to the namespace query:

GET /api/dataStore/<namespace>?fields=name,description

This returns a list of all entries having a non-null name and/or a description field like in the following example:

[
  {"key": "key1", "name": "name1", "description": "description1"},
  {"key": "key2", "name": "name2", "description": "description2"}
]

If for some reason we even want entries where none of the extracted fields is non-null contained in the result list the includeAll parameter can be added:

GET /api/dataStore/<namespace>?fields=name,description&includeAll=true

The response now might look like this:

[
  {"key": "key1", "name": "name1", "description": "description1"},
  {"key": "key2", "name": "name2", "description": "description2"},
  {"key": "key3", "name": null, "description": null},
  {"key": "key4", "name": null, "description": null}
]

The extraction is not limited to simple root level members but can pick

nested members as well by using square or round brackets after a members name: GET /api/dataStore/?fields=name,root[child1,child2] GET /api/dataStore/?fields=name,root(child1,child2)

The example response could look like this:

[
  { "key": "key1", "name": "name1", "root": {"child1": 1, "child2": []}},
  { "key": "key2", "name": "name2", "root": {"child1": 2, "child2": []}}
]

The same syntax works for nested members:

GET /api/dataStore/<namespace>?fields=root[level1[level2[level3]]]
GET /api/dataStore/<namespace>?fields=root(level1(level2(level3)))

Example response here:

[
  { "key": "key1", "root": {"level1": {"level2": {"level3": 42}}}},
  { "key": "key1", "root": {"level1": {"level2": {"level3": 13}}}}
]

When such deeply nested values are extracted we might not want to keep the structure but extract the leaf member to a top level member in the response. Aliases can be used to make this happen. An alias can be placed anywhere after a member name using ~hoist followed by the alias in round brackets like so:

  • GET /api/dataStore/?fields=root[level1[level2[level3~hoist(my-prop)]]]
  • The response now would look like this:
  • ```json [ { "key": "key1", "my-prop": 42}, { "key": "key2", "my-prop": 13} ] 
    * If the full path should be kept while giving an alias to a nested member the 
parent path needs to be repeated using dot-syntax to indicate the nesting.
This can also be used to restructure a response in a new different structure 
like so:

    GET /api/dataStore/<namespace>?fields=root[level1[level2[level3~hoist(my-root.my-prop)]]]

### The newly structured response now looks like this:
```json
[
  { "key": "key1", "my-root": {"my-prop": 42}},
  { "key": "key2", "my-root": {"my-prop": 13}}
]

OBS! An alias cannot be used to rename an intermediate level. However, an alias could be used to resolve a name collision with the key member.

  • GET /api/dataStore/?fields=id,key~hoist(value-key)
  • ```json [ { "key": "key1", "id": 1, "value-key": "my-key1"}, { "key": "key2", "id": 2, "value-key": "my-key2"} ] 
    * Sorting results { #sorting-results } 

Results can be sored by a single property using the `order=<path>[:direction]` parameter.
This can be any valid value `<path>` or the entry key (use `_` as path).

| 所需值 | Parameter name |
| -------- | ----------- |
|     GET /api/dataStore/<namespace>?fields=name&order=name   | To switch to descending order use `:desc`: |
|     GET /api/dataStore/<namespace>?fields=name&order=name:desc  | Sometimes the property sorted by is numeric so alphanumeric interpretation would be confusing.
In such cases special ordering types `:nasc` and `:ndesc` can be used. |
| In summary, order can be one of the following:  | `asc`: alphanumeric ascending order |
| `desc:`: alphanumeric descending order | `nasc`: numeric ascending order |

`ndesc`: numeric descending order

| 所需值 | Parameter name |
| -------- | ----------- |
| To filter entries within the query API context add one or more `filter` parameters
while also using the `fields` parameter.     | Each `filter` parameter has the following form: |
| unary operators: `<path>:<operator>` | binary operators: `<path>:<operator>:<value>` |
| set operators: `<path>:<operator>:[<value>,<value>,...]`     | Unary operators are: |
| Operator     | 描述 |
| `null`     | value is JSON `null` |
| `!null`     | value is defined but different to JSON `null` |

`empty`

| 所需值 | `!empty` |  Parameter name |
| -------- | ---------------- | ----------- |
| Binary operators are:   | Operator          | 描述 |
| `eq`  | value is equal to the given boolean, number or string         | `!eq`, `ne`, `neq` |
| value is not equal to the given boolean, number or string  | `lt`   | value is numerically or alphabetically less than the given number or string |
| `le` | value is numerically or alphabetically less than or equal to the given number or string | `gt` |
| value is numerically or alphabetically greater than the given number or string  | `ge`     | value is numerically or alphabetically greater than or equal to the given number or string |
| Text pattern matching binary operators are: | Operator   | Case Insensitive |

描述

`like`

`ilike`

| 所需值 | Parameter name |
| -------- | ----------- |
| `!ilike`     | value does not match the text pattern given |
| `$like`    | `$ilike`, `startswith` |

value starts with the text pattern given

* `!$like`
* `!$ilike`, `!startswith`
* value does not start with the text pattern given
* `like$`

`ilike$`, `endswith`

value ends with the text pattern given

`!like$`

`!ilike$`, `!endswith`

value does not end with the text pattern given

For operators that work for multiple JSON node types the semantic is determined from the provided value.
If the value is `true` or `false` the filter matches boolean JSON values.
If the value is a number the filter matches number JSON values.
Otherwise, the value matches string JSON values or mixed types of values.

> **Tip**
>
> To force text comparison for a value that is numeric quote the value in single quotes.
> For example, the value `'13'` is the text 13 while `13` is the number 13.  

Set operators are:

Operator

描述

`in`

entry value is textually equal to one of the given values (is in set)

`!in`

entry value is not textually equal to any of the given values (is not in set)

### The `<path>` can be:

`_`: the entry key is

`.`: the entry root value is

`<member>`: the member of the root value is

`<member>.<member>`: the member at the path is (up to 5 levels deep)

Indicates whether the value of the given key should be encrypted

Some example queries are found below.

Name (of root object) is "Luke":

    GET /api/dataStore/<namespace>?fields=.&filter=name:eq:Luke

### Age (of root object) is greater than 42 (numeric):

    GET /api/dataStore/<namespace>?fields=.&filter=age:gt:42

Root value is a number greater than 42 (numeric matching inferred from the value):

    GET /api/dataStore/<namespace>?fields=.&filter=.:gt:42

Enabled (of root object) is true (boolean matching inferred from the value):

Indicates whether the value of the given key should be encrypted

Root object has name containing "Pet" and has an age greater than 20:

###     GET /api/dataStore/<namespace>?fields=.&filter=name:like:Pet&filter=age:gt:20

Root object is either flagged as minor or has an age less than 18:

    GET /api/dataStore/<namespace>?fields=.&filter=minor:eq:true&filter=age:lt:18&rootJunction=or

创造价值 { #webapi_data_store_create_values } 

为命名空间创建新的键和值:

Indicates whether the value of the given key should be encrypted

假设有效的JSON有效负载,创建示例的curl请求:

```bash
curl "https://play.dhis2.org/demo/api/33/dataStore/foo/key_1" -X POST
  -H "Content-Type: application/json" -d "{\"foo\":\"bar\"}" -u admin:district

响应示例:

创造价值 { #webapi_data_store_create_values }

如果您需要加密存储的数据(例如用户 凭据或类似的),您可以像这样将查询附加到 url:

Indicates whether the value of the given key should be encrypted

更新值 { #webapi_data_store_update_values }

更新命名空间中存在的密钥:

PUT /api/33/dataStore/<namespace>/<key>

假设有效的JSON有效负载,示例curl请求更新:

curl "https://play.dhis2.org/demo/api/33/dataStore/foo/key_1" -X PUT -d "[1, 2, 3]"
  -H "Content-Type: application/json" -u admin:district

响应示例:

有关所有现有名称空间的列表:

删除键 { #webapi_data_store_delete_keys }

要从名称空间中删除现有键:

删除/ api / 33 / dataStore / <namespace> / <key>

删除示例curl请求:

curl "play.dhis2.org/demo/api/33/dataStore/foo/key_1" -X DELETE -u admin:district

响应示例:

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Key 'key_1' deleted from namespace 'foo'."
}

要删除名称空间中的所有键:

删除/ api / 33 / dataStore /

删除示例curl请求:

curl "play.dhis2.org/demo/api/33/dataStore/foo" -X DELETE -u admin:district
响应示例: Parameter name Sharing data store keys { #webapi_data_store_sharing }
Sharing of data store keys follows the same principle as for other metadata sharing (see
Sharing). To get sharing settings for a specific data store key: 具有以下要求:
```bash
curl "localhost/api/33/email/notification?recipients=xyz%40abc.com&message=sample%20email&subject=Test%20Email"
-X POST -u admin:district
``` GET /api/33/dataStore///metaData 具有以下要求:
To send an email with an HTML body, you can simply provide the HTML content
in the message parameter. The email client should interpret the
HTML and render it accordingly. Note that the Content-Type header in
the curl command should be application/x-www-form-urlencoded, as the
data is sent as URL-encoded form data. The following example shows how
to send an email with a simple HTML table: POST / api / 33 / sharing?type = dataStore&id = 具有以下要求:
```json
{
"object": {
"publicAccess": "rw------",
"externalAccess": false,
"user": {},
"userAccesses": [],
"userGroupAccesses": [
{
"id": "hj0nnsVsPLU",
"access": "rw------"
},
{
"id": "qMjBflJMOfB",
"access": "r-------"
}
]
}
}
``` 用户数据存储 { #webapi_user_data_store } 数据存储 { #data-store }
/ api / 33 / userDataStore 用户数据存储结构 { #webapi_user_data_store_structure } userDataStore 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。

Table: User data store structure

项目

描述

Data Type

用户

数据类型

串

命名空间

The namespace the key belongs to

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

键

串

串

值

The value stored

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

Encrypted

Indicates whether the value should be encrypted

Boolean

获取名称空间 { #webapi_user_data_store_get_namespaces }

返回所有现有名称空间的数组

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

请求示例:

curl -H "Content-Type: application/json" -u admin:district "play.dhis2.org/api/33/userDataStore"

[
  "foo",
  "bar"
]

取得金钥 { #webapi_user_data_store_get_keys }

返回给定名称空间中所有现有键的数组

GET /api/userDataStore/<namespace>

请求示例:

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

[
  "key_1",
  "key_2"
]

获取价值 { #webapi_user_data_store_get_values }

返回给定名称空间和键的值

GET /api/33/userDataStore/<namespace>/<key>

请求示例:

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

{
  "some": "value"
}

创造价值 { #webapi_user_data_store_create_values }

向给定名称空间中的给定键添加新值。

POST / api / 33 / userDataStore / <namespace> / <key>

请求示例:

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

{
  "httpStatus": "Created",
  "httpStatusCode": 201,
  "status": "OK",
  "message": "Key 'bar' in namespace 'foo' created."
}

如果您需要加密该值(例如用户凭据 等等)您可以像这样将查询附加到网址:

GET /api/33/userDataStore//?encrypt=true

更新值 { #webapi_user_data_store_update_values }

更新现有值

PUT /api/33/userDataStore/<namespace>/<key>

请求示例:

curl -X PUT -H "Content-Type: application/json" -u admin:district -d "['new value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

{
  "httpStatus":"Created",
  "httpStatusCode":201,
  "status":"OK",
  "message":"Key 'bar' in namespace 'foo' updated."
}

删除键 { #webapi_user_data_store_delete_key }

删除金钥

删除/ api / 33 / userDataStore / /

请求示例:

curl -X DELETE -u admin:district "play.dhis2.org/api/33/userDataStore/foo/bar"

{
  "httpStatus":"OK",
  "httpStatusCode":200,
  "status":"OK",
  "message":"Key 'bar' deleted from the namespace 'foo."
}

删除名称空间

删除给定名称空间中的所有键

删除/ api / 33 / userDataStore / <namespace>

请求示例:

curl -X DELETE -u admin:district "play.dhis2.org/api/33/userDataStore/foo"

{
  "httpStatus":"OK",
  "httpStatusCode":200,
  "status":"OK",
  "message":"All keys from namespace 'foo' deleted."
}

Admin Access to another User's Datastore { #admin-access-to-another-users-datastore }

```json

{ "name": "whiskers", "favFood": [ "fish", "rabbit" ] } 

- For example, to add a value to `Peter`'s datastore an admin uses:
-     POST /api/userDataStore/<namespace>/<key>?username=Peter

## Partial Update (Experimental) { #partial-update-experimental } 
Both the datastore and user datastore allow partial updating of entry values.  

We can perform many update operations on this entry. The following examples use `{store}` in the API calls, please substitute with `dataStore` or `userDataStore` for your use case.

```json
{
  "name": "wisker",
  "favFood": [
    "fish", "rabbit"
  ]
}

We can perform many update operations on this entry. The following examples use {store} in the API calls, please substitute with dataStore or userDataStore for your use case.

Update root (entire entry) { #update-root-entire-entry }

We can update the entry at the root by not supplying the path request param or leaving it empty path=.

PUT /api/{store}/pets/whiskers with body "whiskers" updates the entry to be the supplied body. So a GET request to /api/{store}/pets/whiskers would now show: 

"whiskers"

Update at specific path { #update-at-specific-path }

We can update the entry at a specific path by supplying the path request param and the property to update.

PUT /api/{store}/pets/whiskers?path=name with body "whiskers" updates the entry at the name property only. So a GET request to /api/{store}/pets/whiskers would now show the updated name:

```json

{ "name": "whiskers", "favFood": [ "fish", "rabbit" ] } ``` - We can update an array element at a specific path.