数据存储¶

数据存储¶

使用 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。

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

获取键和名称空间¶

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

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

响应示例：

响应示例:

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

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

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

响应示例:

```json
{
  "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).
  
  | 所需值 | 描述 |
  | -------- | ----------- |
  |     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
  
  | 所需值 | 描述 |
  | -------- | ----------- |
  | 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` |  描述 |
  | -------- | ---------------- | ----------- |
  | 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`
  
  | 所需值 | 描述 |
  | -------- | ----------- |
  | `!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)
  
  ### 创造价值 { #webapi_data_store_create_values } 
  
  为命名空间创建新的键和值：
  
      POST / api / 33 / dataStore / <namespace> / <key>
  
  假设有效的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
  

响应示例：

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

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

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

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

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

响应示例:

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 由用户、命名空间、键和关联的 值。用户、命名空间和密钥的组合是唯一的。

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

获取名称空间¶

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

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

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

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

更新现有值

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.