元数据要点 API¶

元数据 Gist API 是一个用于获取和浏览的 RESTful 只读 JSON API 元数据。此 API 中的项目包含元数据 API 中相同项目的要点。

API 专门设计用于避免：

• 由于包含部分嵌套对象，响应负载较大 图表。
• 请求的内存处理需要大量资源 （例如，在内存过滤或对象图遍历中）。
• n + 1 次数据库查询是渲染时对象图遍历的结果 响应。

与元数据 API 的比较¶

标准元数据 API 是一个灵活而强大的 API，旨在为任何和 每个用例。 这样做的缺点是并非所有功能和组合都可以扩展 在存在大量项目的情况下保持良好的性能。 特别是包含项目的列表，其中每个项目本身都有一个属性，该属性是 大量复杂对象的集合已被证明是有问题的，因为它们很快 引用整个对象图的很大一部分。

添加 /gist API 是为了提供元数据 API，其中良好的扩展性是我们的目标 首要任务。这样做的缺点是有更多明显的限制 哪些功能在技术上是合理的，这意味着并非所有功能 Gist API 存在标准元数据 API。

groups

/gist API 使用 URI 而不是包含嵌套数据。 这意味着，如果客户端对嵌套信息感兴趣，则需要更多请求 需要更多请求，但每个请求都保持在合理的小范围内，在潜在项目数量巨大的情况下可以很好地扩展。 这意味着如果客户端对这些嵌套信息感兴趣，则需要更多请求，但每个请求的数量都保持在合理的范围内，而且在潜在项目数量巨大的情况下也能很好地扩展。

已知差异：

• items 仅包含引用的可识别对象的字段（如果这些字段不包含） 有自己的端点
• 它从不直接包含可识别的对象集合
• 默认情况下，项目不包括所有可用字段，而是取决于的子集 关于上下文和参数
• 列表不能在没有 pager 的情况下使用（因此没有 pager 参数）
• Large response payloads because of the inclusion of partial nested object 特定集合属性的分页 API 端点
• 列表中的项目、集合属性大小或布尔转换器结果 始终考虑对象共享（所考虑的项目的集合始终是集合 用户可见）
• Gist 提供 member(<id>) 和 not-member(<id>) 集合字段转换器

• 与元数据应用项目接口{ #gist_vs_metadata_api } 的比较

• Gist 提供使用属性 UID 作为字段和过滤器属性名称，以允许 根据自定义属性值列出或过滤

• Gist 提供过滤器分组
• Gist 提供了使用 pageListName 重命名分页响应中的 enrty 列表的方法
• Gist 提供拔取多个简单属性的功能

已知限制

• 默认情况下只包括持久性；少数几个特殊的 可以明确添加非持久字段（合成字段）；其他 非持久字段也许可以使用 from 转换来提取
• 筛选器只能应用于持久化字段
• 排序仅适用于持久化字段（44+ 版本还支持已翻译的属性）
• 令牌过滤器不可用
• 顺序总是区分大小写
• items in a list, a collection property size or boolean transformer result
• 保存简单（不可识别）项目集合的字段不能总是 视其存储方式而定

在可能的情况下，应将使用 /gist API 视为获取元数据信息的首选方式。 获取元数据信息。

元数据 API 与 Gist 后端之间的桥接{ #metadata_api_gist_bridge }¶

针对元数据 API 的查询可能会由 Gist 后端在内部处理，以获得更好的性能和可扩展性。

系统会采用启发式方法来判断 Gist 后端是否能为该查询提供等效的响应。

具体条件如下（略作概括）：

• 所有存在的 URL 参数在 Gist API 的上下文中都必须有意义
• fields、filter 和 order 参数的任何属性均不得包含嵌入对象
• fields、filter 和 order 参数的所有属性必须是持久化属性，或持久化属性的转换形式
• fields 必须在 URL 中显式指定，或内部具有显式的默认值
• 仅当根级别为 IdentifiableObject 或其集合时，fields 的属性才允许嵌套两层（超过两层则不符合条件）
• 所有 filter 属性必须是非嵌套的且已持久化
• 所有 order 属性不得采用不区分大小写的排序方式
• 必须使用分页

由 gist 后端生成的响应会在根响应对象中 通过 "gist":true 进行标识，如下例所示：

{
  "pager": {},
  "gist": true,
  "dataElements": []
}

若要禁用此启发式算法，请在 URL 中添加 ?gist=false（例如，当启发式算法失效时）。 若要强制使用 gist 后端（无论启发式算法结果如何），请在 URL 中添加 ?gist=false（例如用于测试）。 此时生成的响应与在路径中添加 /gist 几乎完全相同。

端点{ #gist_endpoints }¶

/gist API 有 3 种端点：

• /api/<object-type>/gist: paged list of all known and visible objects of the type (implicit auto=S)
• /api/<object-type>/<object-id>/gist: view single object by ID (implicit auto=L)
• /api/<object-type>/<object-id>/<field-name> /gist : 物件所有者字段集合中所有已知和可见项目的分页列表（隐式 auto=M；如果是简单字段，则只显示字段值）。

Gist offers to pluck multiple simple properties

浏览数据{ #gist_browse }¶

由于 /gist 应用程序接口避免在响应中使用深嵌套数据结构，因此会提供被引用的复杂对象或对象列表的详细信息。 引用的复杂对象或对象列表的详细信息会以 gist 端点的 URI 形式提供，该端点只返回复合对象或对象列表。 对象列表。这些 URI 由项目的 apiEndpoints 字段提供。 字段提供，当存在此类引用时，它会自动添加到项目中。 项属性本身可能包含对象或集合的转换结果 或集合的转换结果，例如其大小、空性、非空性、id 或摘取的 属性（如名称）。

要手动浏览数据，使用 absoluteUrls=true 参数会很方便。 现在，在可渲染 JSON 响应的浏览器中，可直接跟踪要旨各部分之间的链接。 呈现 JSON 响应。

参数{ #gist_parameters }¶

token filters are not available

总览¶

参数按字母顺序排列：

pageSize¶

number of items on a page

可以使用 absoluteUrls 参数将 URI 更改为绝对 URL。

例如，/api/users/rWLrZL8rP3K/gist?fields=id,href 返回：

{
  "id": "rWLrZL8rP3K",
  "href": "/users/rWLrZL8rP3K/gist"
}

其中 /api/users/rWLrZL8rP3K/gist?fields=id,href&absoluteUrls=true 返回 返回：

{
  "id": "rWLrZL8rP3K",
  "href": "http://localhost:8080/api/users/rWLrZL8rP3K/gist?absoluteUrls=true"
}

与或或

AND¶

每个端点都隐式地设置了由 * / :all 字段选择器匹配的字段范围的默认值：

• /api/<object-type>/gist：意味着auto=S。
• /api/<object-type>/<object-id>/gist：意味着auto=L。
• /api/<object-type>/<object-id>/<field-name>/gist：意味着 auto=M。

true add total number of matches to the pager, false skip counting total number of matches

translate

• true or false
• true
• true translate all translatable properties, false skip translation of translatable properties (no effect on synthetic display names)
• The absoluteUrls Parameter { #gist_parameters_absoluteUrls }
• XL: 与 L 类似，但引用和集合作为 ID 对象包含在内：{ "id"： <id> }

By default, URIs in apiEndpoints, href and the pager prev and next members are relative, starting with /<object-type>/ path.

可以使用 absoluteUrls 参数将 URI 更改为绝对 URL。¶

指定每个列表项目要包含的字段列表。

whereas /api/users/rWLrZL8rP3K/gist?fields=id,href&absoluteUrls=true returns:

如果没有提供 fields 参数，则假定fields=*。 请注意，* 预置的字段也取决于 auto 参数

要删除字段，请使用字段列表中的 !<name> 或 -<name>。 例如，要删除用户的 userGroups，请使用

/api/users/gist?fields=*,!userGroups

同样的原理也可用于指定一个字段使用的变压器。 字段的转换器。例如，要包含用户的用户组 ID，请使用

/api/users/gist?fields=*,userGroups::ids

/api/<object-type>/<object-id>/gist: implies auto=L

/api/users/gist?fields=*,userCredentials[id,username] /api/users/gist?

这样就创建了格式为

{
  ...
  "userCredentials": {
    "id": "Z9oOHPi3FHB",
    "username": "guest"
  }
}

当包含集合的嵌套字段时，嵌套字段必须是文本属性。 属性。

例如，通过以下方式包含用户的userGroups的所有名称：

M: complex included as reference URL, references and collections as count and reference URL

L: like M but references and collections included as IDs (OBS! unbound in size)

{
  "userGroups": {
    "name": [
      "_PROGRAM_Inpatient program",
      "_PROGRAM_TB program",
      "_DATASET_Superuser",
      "_PROGRAM_Superuser",
      "_DATASET_Data entry clerk",
      "_DATASET_M and E Officer"
    ]
  }
}

/api/users/gist?fields=*,userGroups::pluck(name)~rename(userGroups.name)

当请求单个字段（如 /api/users/gist?fields=surname）时，响应是一个简单值的列表（仍然是分页的）。 响应是一个（仍然分页的）简单值列表：

{
  "pager": {
    "page": 1,
    "pageSize": 50
  },
  "users": [
    "Kamara",
    "Wakiki",
    "Nana",
    "Malai",
    ...
  ]
}

Fields are included in the result JSON objects for an item in the provided order. A preset in the list of fields is expanded to the fields it contains at the position in the fields list it appears. Fields within the preset are ordered from simple to complex.

"Wakiki"

有关字段预设的更多详情，请参阅 字段 部分。

/api/users/gist?fields=*,!userGroups¶

要过滤返回的项目列表，请添加一个或多个过滤器参数。

The fields parameter does allow listing fields of nested objects. For example to add userCredentials with id and name of a user use:

过滤器有两种类型：

• 一元： <field>:<operator>
• 二进制： <field>:<operator>:<value>

一个字段可以是

• 所列项目类型的持久字段
• 直接引用对象的持久字段（1:1 关系）
• 一个属性的 UID

可用的一元运算符有

可用的二进制运算符有

描述

eq

field equals value

可用的二进制模式匹配运算符有

field is a collection and value is an item not contained in the collection

所有名为 like 的模式匹配运算符都区分大小写。所有其他 不区分大小写。

请注意，属性值筛选器使用基于文本的比较，这意味着 支持所有文本筛选器。

例如，要只列出二级机构，请使用

/api/organisationUnits/gist?filter=level:eq:2

Binary Operator

/api/organisationUnits/rZxk3S0qN63/children/gist?filter=programs:gt:0

基于访问（共享）过滤的二进制运算符：

当省略用户 ID <value> 时，将对当前登录的用户进行检查。 登录用户进行检查。同样，如果在 canAccess 过滤器中省略了 <value0>，则会对当前登录的用户进行检查。 则会对当前登录的用户进行检查。

Note that filters on attribute values use text based comparison which means all text filters are supported.

/api/dataElements/gist?filter=code:canWrite:OYLGMiazHtW

/api/organisationUnits/gist?filter=level:eq:2

/api/dataElements/gist?filter=categoryCombo:canWrite:OYLGMiazHtW

当应用到引用集合属性（此处为 dataElementGroups ）时，过滤器会将响应限制为数据元素组在引用集合中存在的数据元素。 过滤器会将响应限制在数据元素组存在于 集合属性中存在数据元素组且用户可以读/写的数据元素：

/api/dataElements/gist?filter=dataElementGroups:canWrite:OYLGMiazHtW

Binary Operator

/api/dataElements/gist?filter=code:canAccess:[OYLGMiazHtW,rw%]。

此外，还可以对筛选器进行分组，以便在一般筛选器组合器为逻辑 AND 时，用逻辑 OR 组合所选筛选器，反之亦然。 逻辑 OR 组合选定的筛选器，反之亦然 当一般组合器为逻辑 OR 时，则使用逻辑 AND。

对于组，过滤模式扩展如下：

• 一元： <group>:<field>:<operator>
• 二进制： <group>:<field>:<operator>:<value>

组是介于 0 和 9 之间的任意数字（省略时假定为 0）。 则假定为 0）。

Has user <value> data read permission to the object

filter=1:age:eq:50&filter=2:name:eq:foo&filter=2:name:eq:bar

上述过滤器有两个组1和2，2组有 2 个成员。 这等同于 SQL 语句（注意其中的 and 和 or 以及 分组大括号）：

e.age = 50 且（e.name = 'foo' 或 e.name = 'bar')

现在，如果将相同的过滤器与rootJunction=OR结合使用

filter=1:age:eq:50&filter=2:name:eq:foo&filter=2:name:eq:bar&rootJunction=OR

的效果将等同于下面的 SQL 语句：

e.age = 50 或 (e.name = 'foo' and e.name = 'bar')

When applied to a reference property, here categoryCombo, the filter restricts the response¶

to those data elements having a category combo that the user can read/write:

When applied to a reference collection property, here dataElementGroups, the filter restricts the response to those data elements where a data element group exists in the collection property and which the user can read/write:

例如 /api/organisationUnits/gist 返回：

{
  "pager": {
    "page": 1,
    "pageSize": 50,
    "nextPage": "/organisationUnits/gist?page=2"
  },
  "organisationUnits": [
    ...
  ]
}

/api/dataElements/gist?filter=code:canAccess:[OYLGMiazHtW,rw%]

In addition, filter can be grouped to allow combining selected filters with¶

logical OR when the general filter combinator is logical AND, or vice-versa with logical AND when the general combinator is logical OR. For groups the filter pattern is extended as following:

例如，当

/api/organisationUnits/rZxk3S0qN63/children/gist

将列出作为rZxk3S0qN63子级的所有组织单位

/api/organisationUnits/rZxk3S0qN63/children/gist?inverse=true

将列出所有不是 rZxk3S0qN63 子单元的组织单元。 例如，这可用于列出所有可成为某一特定单元子单元的单元。 的所有单位的列表。

过滤和排序通常会应用，这意味着它们会过滤或排序 不包含在成员集合中。

e.age = 50 and (e.name = 'foo' or e.name = 'bar')¶

现在,如果将相同的过滤器与rootJunction=OR结合使用

要对项目列表进行排序，可以给出一个或多个顺序表达式。

顺序表达式既可以是一个持久化字段的字段名，也可以是一个字段名后跟有 字段名后的 :asc（升序，默认值）或 :desc（降序，默认值）。 (降序）。

例如，要按名称的字母顺序对组织单位进行排序，请使用

/api/organisationUnits/gist?order=name

按字母顺序倒序排列：

/api/organisationUnits/gist?order=name:desc

要先按级别，然后按名称对组织单位进行排序，请使用

/api/organisationUnits/gist?order=level,name

这将从第 1 级的根单元开始。要从叶单元开始，请使用

/api/organisationUnits/gist?order=level:desc,name

如果没有指定顺序，结果列表将根据 内部数据组织的稳定顺序。

For example, while¶

指在分页列表中查看的页面，以1开头的第一页。

如果不存在page参数，则等于page=1。

would list all organisation units that are not children of rZxk3S0qN63. This would e.g. be used to compose a list of all units that can be made a child of a particular unit.

Filters and orders do apply normally, meaning they filter or order the items¶

not contained in the member collection.

指的是页面上的项目数。最多 1000 个项目。

如果没有pageSize参数，则等于pageSize=50。

An order expression is either just a field name of a persisted field, or a field¶

name followed by :asc (ascending order - the default) or :desc (descending order).

/api/organisationUnits/gist?order=name

• Reverse alphabetical order would use:
• /api/organisationUnits/gist?order=name:desc

默认为与。

/api/organisationUnits/gist?order=level,name¶

This would start with root(s) at level 1. To start with the leaf units use:

/api/organisationUnits/gist?order=level:desc,name

If no order is specified the result list will have a stable order based on internal data organisation.

例如，/api/organisationUnits/gist 返回一个pager：

{
  "pager": {
    "page": 1,
    "pageSize": 50,
    "nextPage": "/organisationUnits/gist?page=2"
  }
}

指在分页列表中查看的页面,以1开头的第一页。

对 /api/organisationUnits/gist?total=true的响应现在会返回这个 pager：

{
  "pager": {
    "page": 1,
    "pageSize": 50,
    "total": 1332,
    "nextPage": "/organisationUnits/gist?total=true&page=2",
    "pageCount": 27
  }
}

The pageSize Parameter¶

像name或shortName这样的字段可以被翻译（国际化）。

默认情况下，任何有翻译的可翻译字段都会翻译后返回。 的翻译字段。

要返回普通的非翻译字段，请使用 translate=false。

例如，/api/organisationUnits/gist 会返回如下项目：

{
  "name": "A translated name",
  ...
}

而 /api/organisationUnits/gist?translate=false会返回类似的项目：

{
  "name"
  "Plain field name",
  ...
}

默认为与。

字段{ #gist_fields }¶

By default, a gist query will not count the total number of matches should those exceed the pageSize limit. Instead, we opt-in to the additional costs the total count implicates.

When not counting the total matches (total=false) the response pager will assume that there is a next page in case pageSize items were found. This could however turn out to be false when browsing to the page. Also, the total field stating the number of total matches is not included in the pager.

如果未在字段参数中明确提供字段名称，则字段列表将从预设值中计算得出。 字段列表是通过预设计算得出的。 预设可以像字段名一样用于字段列表。 根据对象类型、使用的 端点和选择器。

现场预设{ #field-presets }¶

• * / :all：默认字段取决于上下文和 auto 参数
• The response to /api/organisationUnits/gist?total=true now returns this pager:
• ```json { "pager": { "page": 1, "pageSize": 50, "total": 1332, "nextPage": "/organisationUnits/gist?total=true&page=2", "pageCount": 27 } }

  * The `translate` Parameter { #gist_parameters_translate } 
  * `:持久化`：字面意义上的所有持久化字段
  
  
  ### 现场变压器{ #field-transformers } 
  转换器或转换可以通过在转换器表达式后添加 
  指示符 `::`、`~` 或 `@`，并在变换表达式后添加这些指示符。
  
  可用的变压器表达式有
  
  | 变压器          | JSON 结果类型       | 描述                                                                                           |
  |----------------------|------------------------|-------------------------------------------------------------------------------------------------------|
  | ```json
  {
    "name"
    "Plain field name",
    ...
  }
  ```     | --                      | 将响应中的字段重命名为 `<name>`                                                         |
  | <!--DHIS2-SECTION-ID:gist_fields-->               | The fields included by default (without `fields` parameter) correspond to 
  `fields=*`. 
  This means the list of fields shown depends on object type, endpoint context as 
  well as the `auto` parameter.               | 藏品字段中的数量                                                               |
  | When not explicitly provided by name in the `fields` parameters the list of 
  fields is computed from a preset.
  A preset can be used in the list of fields like a field name. 
  It expands to zero, one or many fields depending on the object type, used 
  endpoint and selector.            | `boolean`              | 收集领域的空虚                                                                       |
  | `:identifiable`: all persisted fields of the `IdentifiableObject` interface         | `boolean`              | 集合字段不完整                                                                   |
  | `ids`                | `isEmpty` | 对象的 ID 或集合项的 ID                                                            |
  | Available transformer expressions are:         | `[{"id":<id> }]`     | 作为对象的集合项目 ID                                                                     |
  | 描述       | `boolean`              | 具有`<id>`的成员用于集合字段                                                           |
  | renames the field in the response to `<name>`   | `boolean`              | 集合字段中没有具有`<id>`的成员                                                       |
  | `pluck(<field>,...)` | `isEmpty` | 从对象或每个集合项中提取单个文本属性或多个简单属性 |
  | emptiness of a collection field  | 取决于豆类类型   | 从一个或多个持久字段中提取一个非持久字段                                      |
  
  non-emptiness of a collection field
  
      /api/organisationUnits/gist?fields=*,children::size~rename(child-count)
  
  返回的项目现在不再有 `children` 成员，而是有一个 `child-count` 成员。
  成员。请注意，`rename` 也会影响在 `apiEndpoints` 中给出的 URI
  引用的成员名称。
  
  ID of an object or IDs of collection items
  
  `id-objects`
  
      /api/users/gist?fields=id,name~from(firstName,surname)
  
  由于用户名是很常见的情况，因此添加了自动检测功能，这样在这种特殊情况下，`from` 转换会自动添加到`name`中。
  在这种特殊情况下，"from "转换会自动添加到 "name "中。
  我们可以使用以下内部添加 `from` 变量的方法 
  转换：
  
      /api/users/gist?fields=id,name
  
  `boolean`
  
      /api/users/gist?fields=*,name
  
  
  ## 合成球场{ #gist_syntheticFields } 
  <!--DHIS2-SECTION-ID:gist_syntheticFields-->
  
  集合字段中没有具有`<id>`的成员
  
  合成属性适用于存在计算合成属性所需的持久化属性的所有端点。 
  属性的所有端点都可使用合成属性。
  
  `string` or `[string]`
  
  
  ### 总览 { #overview } 
  合成字段按字母顺序排列：
  
  | 领域              | 描述                                             |
  | ------------------ | ------------------------------------------------------- |
  | A field can receive both the `rename` transformer and one of the other 
  transformers, for example:     | 包含浏览嵌套复杂对象或集合的链接 |
  | `href`             | 链接到列表项目本身（单个项目视图）         |
  | For example, a user's (non-persistent property) `name` is composed of the 
  persistent property `firstName` and `surname`. It can be fetched like this:      | 已翻译的`名称`（始终已翻译）                   |
  | Since a user's name is such a common case an auto-detection was added so that in
  this special case the `from` transformation is added automatically to `name`.
  We are allowed to just use the following which internally adds the `from` 
  transformation: | 翻译的`shortName`（始终翻译）              |
  | While this makes non-persistent properties accessible in general these always 
  have to be included in the `fields` explicitly. For a user this could be 
  done using the following:           | 当前用户读/写/修改条目的能力摘要 |
  
  
  ### Synthetic Fields { #gist_syntheticFields } 
  <!--DHIS2-SECTION-ID:gist_syntheticFields_href-->
  
  The `/gist` API is tightly coupled to properties that exist the database.
  This means properties that aren't stored in the database usually aren't 
  available.
  The exception to this are the "synthetic" properties which are dynamically 
  computed on the basis of one or more database stored properties.
  
  要添加 `href` 字段，请使用（例如）：
  
      /api/<object-type>/gist?fields=*,href
  
  ### 总览 { #overview } 
  <!--DHIS2-SECTION-ID:gist_syntheticFields_displayName-->
  
  领域
  
  要将 `displayName` 或 `displayShortName` 添加到列表中，请使用（例如）：
  
      /api/<object-type>/gist?fields=*,displayName
      /api/<object-type>/gist?fields=*,displayShortName
  
  contains links to browse nested complex objects or collections
  
  
  ### `href`
  <!--DHIS2-SECTION-ID:gist_syntheticFields_apiEndpoints-->
  
  `displayName`
  
  已翻译的`名称`(始终已翻译)
  
  例如 
  
      /api/users/gist?fields=id,userGroups::size,organisationUnits::size 
  
  返回表格中的项目：
  
  ```json
  {
    "id": "rWLrZL8rP3K",
    "userGroups": 0,
    "organisationUnits": 1,
    "apiEndpoints": {
      "organisationUnits": "/users/rWLrZL8rP3K/organisationUnits/gist",
      "userGroups": "/users/rWLrZL8rP3K/userGroups/gist"
    }
  }
  

The href Field { #gist_syntheticFields_href }

可以使用 absoluteUrls 参数将路径更改为 URL。

/api/users/gist?fields=id,userGroups::size,organisationUnits::size&absoluteUrls=true

返回表格中的项目：

{
  "id": "rWLrZL8rP3K",
  "userGroups": 0,
  "organisationUnits": 1,
  "apiEndpoints": {
    "organisationUnits": "http://{host}/api/users/rWLrZL8rP3K/organisationUnits/gist?absoluteUrls=true",
    "userGroups": "http://{host}/api/users/rWLrZL8rP3K/userGroups/gist?absoluteUrls=true"
  }
}

The displayName and displayShortName Field¶

By definition the displayName is the translated name and the displayShortName is the translated shortName.

/api/dataElements/gist?fields=*,access

返回的数据元素项包含一个访问成员，如下所示：

"access": {
  "manage": false,
  "externalize": false,
  "write": false,
  "read": true,
  "update": false,
  "delete": false
}

属性作为字段{ #gist_attributeFields }¶

DHIS2 允许为元数据对象创建和添加自定义属性。 它们的值包含在元数据对象的 attributeValues 属性中。 对象的 "attributeValues "属性中。

要直接列出该映射表中的一个或多个特定属性值，就好像它们是元数据对象的常规字段一样 元数据对象的常规字段一样，直接列出该映射表中的一个或多个特定属性值。 作为普通字段的名称。

例如，要将 UID Y1LUDU8sWBR 属性的值作为 属性 unit-of-measure"的值，请使用

/api/dataElements/gist?fields=id,name,Y1LUDU8sWBR::rename(unit-of-measure)

这样，列表项的形式就变成了 returns items in the form:

默认情况下，属性值以 JSON 格式获取，并从 属性值的映射中提取。这意味着列表中将包含适合于 属性值类型。这样做的代价是获取所有 属性值的开销。要在数据库中单独找出值，可以使用 PLUCK 转换。 转换。

/api/dataElements/gist?fields=id,name,Y1LUDU8sWBR::rename(unit-of-measure)~pluck

结果看起来是一样的，但现在值会以文本形式提取到 在属性输出中，数据库会将任何 JSON 值转换为字符串。

例子¶

从简单的列表到非常具体的使用案例，举几个例子。

{
  "id": "rWLrZL8rP3K",
  "userGroups": 0,
  "organisationUnits": 1,
  "apiEndpoints": {
    "organisationUnits": "http://{host}/api/users/rWLrZL8rP3K/organisationUnits/gist?absoluteUrls=true",
    "userGroups": "http://{host}/api/users/rWLrZL8rP3K/userGroups/gist?absoluteUrls=true"
  }
}

列出带有 ID 和名称的组织单位：

/api/organisationUnits/gist?fields=id,name

列出组织单位的 ID、名称和总数：

/api/organisationUnits/gist?fields=id,name&total=true

用 ID 和用户名列出用户：

/api/users/gist?fields=id,userCredentials.username

根据 ID、用户名和最后登录日期列出用户：

/api/users/gist?fields=id,userCredentials[username,lastLogin] /api/users/gist?

仅列出第二层的组织单位，并注明 ID、名称和层级：

/api/organisationUnits/gist?fields=id,name,level&filter=level:eq:2

仅列出有 1 个以上子机构的组织单位，并注明 id、名称和 子女数量：

/api/organisationUnits/gist?fields=id,name,children::size&filter=children:gt:1

仅列出尚未成为另一个单元的子单元的组织单元 zFDYIgyGmXG：

/api/organisationUnits/zFDYIgyGmXG/children/gist?fields=id,name&inverse=true

/api/dataElements/gist?fields=id,name,Y1LUDU8sWBR::rename(unit-of-measure)~pluck

/api/users/gist?fields=id,userCredentials.username,userGroups::member(NTC8GjJ7p8P)~rename(is-member)

列出所有用户的链接，每页 10 个项目：

/api/users/gist?fields=href&absoluteUrls&pageSize=10