For the complete DHIS2 documentation index, see llms.txt.

数据存储¶

使用 dataStore 资源，开发人员可以存储任意数据他们的应用程序。对数据存储密钥的访问基于其共享设置。默认情况下，所有创建的密钥都可以公开访问（读取和写入）。此外，对数据存储命名空间的访问仅限于用户的访问相应的应用程序，如果应用程序保留了命名空间。例如，有权访问“sampleApp”应用程序的用户也将能够使用数据存储中的 sampleApp 命名空间。如果一个命名空间没有保留，使用它不需要特定的访问权限。

/ api / 33 / dataStore

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

数据存储结构¶

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

表：数据存储结构

项目	描述	数据类型
命名空间	用于组织条目的命名空间。	串
键	识别值的关键。	串
值	保存条目信息的值。	JSON格式
加密的	指示给定密钥的值是否应该加密	Boolean

获取键和名称空间¶

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

GET /api/33/dataStore

清单示例curl请求：

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

响应示例：

[
  "foo",
  "bar"
]

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

GET /api/33/dataStore/<namespace>

清单示例curl请求：

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

响应示例：

[
  "key_1",
  "key_2"
]

要从名称空间检索现有键的值：

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

卷曲请求检索示例：

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

响应示例：

{
  "foo":"bar"
}

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

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

卷曲请求检索示例：

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

响应示例：

响应示例:

查询 API¶

通过查询 API，可以对命名空间中的所有键值进行查询和过滤。参数 fields 用于指定查询。这对于在单个请求中检索整个命名空间中键的特定值非常有用。

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

清单示例curl请求:

空：仅返回输入键
.：返回存储的根值
以逗号分隔的路径列表： <path>[,<path>]; 每个 <path> 可以是一个简单的属性名（如 年龄）或一个嵌套路径（如 person.age）。

此外，还可以使用一个或多个 filter 参数过滤条目，并使用 order 参数排序。参数对条目排序。

可使用 rootJunction=OR（默认）或 rootJunction=AND组合多个过滤器。

卷曲请求检索示例:

分页¶

默认情况下，结果使用分页。使用 pageSize 和 page 调整大小和偏移量。可以使用参数 paging=false 选择不使用分页，并始终返回所有匹配结果。由于名称空间中可能有很多条目，因此应谨慎使用。默认页面大小为 50。

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

关闭分页后，条目将以纯结果数组的形式返回，作为根 JSON 结构。通过使用 headless=true，可以在分页结果中实现相同的效果。

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

与 bash curl "play.dhis2.org/demo/api/33/dataStore/foo/key_1/metaData" -u admin:district

值提取{ #value-extraction }¶

数据存储允许提取整个简单或复杂值以及复杂 JSON 值的部分提取。

注

为了使示例更清晰，示例中显示的响应大多省略了包含 pager 信息的最外层对象和 entries 数组。

要过滤特定字段集，请在命名空间中添加一个 fields 参数查询：

GET /api/dataStore/<namespace>?fields=名称,描述

The list of fields can be:

empty: returns just the entry keys

如果由于某种原因我们甚至想要没有提取字段的条目如果结果列表中包含非空，则 includeAll 参数可以是添加：

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

现在的响应可能如下所示：

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

提取不限于简单的根级别成员，而是可以挑选也可以在成员名称后使用方括号或圆括号来嵌套成员：

GET /api/dataStore/<namespace>?fields=name,root[child1,child2]
GET /api/dataStore/<namespace>?fields=name,root(child1,child2)

示例响应可能如下所示：

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

相同的语法适用于嵌套成员：

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

此处的响应示例：

[...]

当提取如此深度嵌套的值时，我们可能不想保留结构，但将叶成员提取到响应中的顶级成员。可以使用别名来实现这一点。别名可以放在任何地方在成员名称之后使用 ~hoist 后跟圆括号中的别名，如下所示：

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

现在的响应将如下所示：

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

如果在为嵌套成员提供别名时应保留完整路径父路径需要使用点语法重复以指示嵌套。这也可以用于以新的不同结构重组响应像这样：

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

新构造的响应现在如下所示：

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:

OBS！别名不能用于重命名中间层。但是，别名可用于解决与 key 成员的名称冲突。

GET /api/dataStore/<namespace>?fields=id,key~hoist(value-key)

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

对结果进行排序{ #sorting-results }¶

可使用 order=<path>[:direction] 参数按单一属性对结果进行分类。这可以是任何有效值 <path> 或条目关键字（使用 _ 作为路径）。

默认情况下，假设路径中的值是混合类型的字符串，则按字母数字排序。

例如，要提取名称属性并按其对结果进行排序，请使用：

GET /api/dataStore/<namespace>?fields=name&order=name

要切换到降序，请使用:desc：

GET /api/dataStore/<namespace>?fields=name&order=name:desc

有时排序依据的属性是数字，因此字母数字解释会令人困惑。在这种情况下，可以使用特殊的排序类型 :nasc 和 :ndesc。

总之，顺序可以是以下之一：

asc：字母数字升序
desc:：字母数字降序排列
nasc：数字升序
ndesc：数字降序

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

过滤条目{ #filtering-entries }¶

要在查询 API 上下文中过滤条目，请添加一个或多个 filter 参数，同时也使用 fields 参数。参数。

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.

一元运算符：<path>:<operator>
二元运算符：<path>:<operator>:<value>
设置运算符：<path>:<operator>:[<value>,<value>,...]

一元运算符是：

操作员	描述
`空`	值为 JSON `null`
`!null`	value 已定义，但与 JSON `null` 不同
In summary, order can be one of the following:	value 是一个空对象、空数组或长度为零的 JSON 字符串
`！空`	值不同于空对象、空数组或零长度字符串

二元运算符是：

操作员	描述
`eq`	值等于给定的布尔值、数字或字符串
`!eq`、`ne`、`neq`	值不等于给定的布尔值、数字或字符串
`lt`	值按数字或字母顺序小于给定的数字或字符串
`le`	值按数字或字母顺序小于或等于给定的数字或字符串
`gt`	值按数字或字母顺序大于给定的数字或字符串
`ge`	值按数字或字母顺序大于或等于给定的数字或字符串

文本模式匹配二元运算符有：

操作员	不区分大小写	描述
Binary operators are:	`喜欢`	值与给定的文本模式匹配
`！喜欢`	`！喜欢`	值与给定的文本模式不匹配
`$喜欢`	`$ilike`, `开始于`	值以给定的文本模式开始
`!$like`	`!$ilike`、`!startswith`	值不以给定的文本模式开头
`喜欢$`	`ge`	值以给定的文本模式结尾
`！像$`	`!ilike$`、`!endswith`	值不以给定的文本模式结尾

描述

提示

要强制对数值进行文本比较，请在数值前加上单引号。例如，值 '13' 是文本 13，而 13 是数字 13。

集合运算符有：

操作员	描述
`在`	条目值在文本上等于给定值之一（在集合中）
`!in`	条目值在文本上不等于任何给定值（不在集合中）

<path> 可以是：

_：输入键是
.：条目根值为
<member>：根值的成员是
<member>.<member>：路径中的成员为（最多 5 层）

ilike$, endswith

下面是一些示例查询。

（根对象的）名称是“Luke”：

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

（根对象的）年龄大于 42（数字）：

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

根值是大于 42 的数字（从该值推断出的数字匹配）：

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

（根对象的）Enabled 为 true（从值推断出布尔匹配）：

GET /api/dataStore/<namespace>?fields=.&filter=enabled:eq:true

根对象的名称包含“Pet”并且年龄大于 20：

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

根对象被标记为次要对象或年龄小于 18：

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

创造价值¶

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

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

假设有效的JSON有效负载，创建示例的curl请求：

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

响应示例：

{
  "httpStatus": "OK",
  "httpStatusCode": 201,
  "status": "OK",
  "message": "Key 'key_1' created."
}

如果您需要加密存储的数据（例如用户凭据或类似的），您可以像这样将查询附加到 url：

GET /api/33/dataStore/<namespace>/<key>?encrypt=true

更新值¶

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

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

响应示例：

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Key 'key_1' updated."
}

删除键¶

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

删除/ 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 / <namespace>

删除示例curl请求：

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

响应示例：

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Namespace 'foo' deleted."
}

共享数据存储密钥{ #webapi_data_store_sharing }¶

数据存储密钥的共享遵循与其他元数据共享相同的原则（请参阅分享)。

要获取特定数据存储密钥的共享设置：

GET /api/33/sharing?type=dataStore&id=<uid>

其中数据存储键的 id 来自该键的 /metaData 端点：

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

删除键 { #webapi_data_store_delete_keys }

要修改特定数据存储密钥的共享设置：

POST / api / 33 / sharing？type = dataStore＆id = <uid>

具有以下要求：

{
  "object": {
    "publicAccess": "rw------",
    "externalAccess": false,
    "user": {},
    "userAccesses": [],
    "userGroupAccesses": [
      {
        "id": "hj0nnsVsPLU",
        "access": "rw------"
      },
      {
        "id": "qMjBflJMOfB",
        "access": "r-------"
      }
    ]
  }
}

用户数据存储¶

除了在所有用户之间共享的 dataStore 系统，还可以使用基于用户的数据存储。数据存储到 userDataStore 与单个用户相关联，以便每个用户在相同的命名空间和组合键上可以有不同的数据。全部对 userDataStore 的调用将与登录的用户。这意味着只能查看、更改、删除和添加值与当前登录的用户相关联。

/ api / 33 / userDataStore

用户数据存储结构¶

userDataStore 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。

表：用户数据存储结构

项目	描述	数据类型
用户	该数据关联的用户	串
命名空间	键所属的命名空间	串
键	存储值的键	串
值	存储的值	JSON格式
加密的	指示该值是否应该加密	Boolean

获取名称空间¶

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

GET /api/33/userDataStore

请求示例：

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

[
  "foo",
  "bar"
]

取得金钥¶

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

GET /api/userDataStore/<namespace>

请求示例：

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

[
  "key_1",
  "key_2"
]

获取价值¶

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

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

请求示例：

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

{
  "some": "value"
}

创造价值¶

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

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/<namespace>/<key>?encrypt=true

更新值¶

更新现有值

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."
}

删除键¶

删除金钥

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

请求示例：

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."
}

对其他用户数据存储区的管理员访问权限¶

管理员可以通过添加 username 参数来操作其他用户的数据存储。参数来操作其他用户的数据存储，这样就不会影响用户的数据存储。参数给出的用户的数据存储。

例如，要在 Peter 的数据存储中添加一个值，管理员需要使用

POST /api/userDataStore/<namespace>/<key>?username=Peter

部分更新（试验性）{ #partial-update-experimental }¶

数据存储和用户数据存储都允许部分更新条目值。

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

删除键 { #webapi_user_data_store_delete_key }

我们可以对该条目执行许多更新操作。以下示例在 API 调用中使用了 {store}，请根据具体情况用 dataStore 或 userDataStore 代替。

更新根目录（整个条目）{ #update-root-entire-entry }¶

我们可以通过不提供 path 请求参数或留空 path= 来更新根目录下的条目。

PUT /api/{store}/pets/whiskers 加上 body "whiskers"，将条目更新为所提供的 body。因此，对 /api/{store}/pets/whiskers 的 GET 请求现在会显示：

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

在特定路径上更新{ #update-at-specific-path }¶

我们可以通过提供 path 请求参数和要更新的属性来更新特定路径上的条目。

PUT /api/{store}/pets/whiskers?path=name 与 body "whiskers"仅更新了name属性的条目。因此，向 /api/{store}/pets/whiskers 提出的 GET 请求现在将显示更新后的 name：

请求示例:

我们可以更新特定路径上的数组元素。

PUT /api/{store}/pets/whiskers?path=favFood.[0] 带有 body "carrot"，只更新 favFood 数组中的第一个元素。因此，向 /api/{store}/pets/whiskers 提出的 GET 请求将显示更新后的 favFood：

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

福利{ #benefits }¶

小变化所需的较小有效载荷
不易出错（无需为更改一个属性而复制粘贴大量条目）

滚动（实验）{ #roll-experimental }¶

通过 roll 请求参数，用户可以在数组中 "滚动 "元素的数量。在我们的示例中，我们有一个 favFood 数组。如果我们想更新这个数组，就必须像这样提供整个有效载荷：
PUT /api/{store}/pets/whiskers 带正文

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.

现在，我们可以使用 roll 请求参数（与 path 功能一起使用）来说明我们需要_n_个元素的滚动功能。在本例中，我们说明希望数组的滚动值为 3，并在调用中传递了一个额外的元素。
PUT /api/{store}/pets/whiskers?roll=3&path=favFood 加上 body "carrot" 会产生以下状态。

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.

由于我们传递的滚动值是 3，这表明我们只希望将最后 3 个元素传递到数组中。因此，如果我们现在再次调用并向数组中添加一个新元素，我们希望第一个元素（fish）从数组中删除。 PUT /api/{store}/pets/whiskers?roll=3&path=favFood 加上 body "bird" 会产生以下状态：

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

注

一旦设置了滚动值（例如 role=3），就只能增加（例如 roll=5）而不能减少（例如 roll=2)

圆点符号允许嵌套调用。比方说，我们有这样一个当前条目值：

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

如果我们想使用滚动数组添加另一个品种，我们可以进行调用： PUT /api/{store}/pets/whiskers?roll=3&path=type.breed 加上 body "small"，会产生以下状态：

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:

福利{ #benefits }¶

只想跟踪 n 个可能随时间变化的值