项目¶

项目规则变量

项目

应用项目接口是专门为避免以下情况而设计的：

• 项目 ProgramStageSection
• 项目阶段 ProgramStageSectionDataElement
• 项目阶段 注册

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

目的

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

添加/gist应用项目接口是为了提供一个元数据应用项目接口，其中良好的扩展性是我们的 的首要任务。这样做的弊端是对 技术上合理的功能，这意味着并非标准元数据 API 的所有功能都适用于 Gist API。 标准元数据 API 的所有功能都适用于 Gist API。

groups

ProgramStageSection

programIndicators

• 注册 events
• Metadata Gist API { #gist_api }
• The Metadata Gist API is a RESTful read-only JSON API to fetch and browse metadata. Items in this API contain the gist of the same item in the Metadata API.
• 应用项目接口是专门为避免以下情况而设计的:
• Large response payloads because of the inclusion of partial nested object graphs.
• Resource intensive in memory processing of requests (e.g. in memory filtering or object graph traversal). n + 1 database queries as a result of object graph traversal while rendering
• the response.

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

• 标准元数据应用项目接口是一个灵活而强大的应用项目接口,可为任何 用例。 但这样做的缺点是,并非所有功能和组合都能在扩展的同时 同时保持良好的性能。 特别是带有项目的列表,其中每个项目本身都有一个属性,而这个属性是一个复杂对象的大集合。 的大量复杂对象的集合,这已被证明是个问题,因为它们会很快 引用整个对象图的很大一部分。 添加/gist应用项目接口是为了提供一个元数据应用项目接口,其中良好的扩展性是我们的 的首要任务。这样做的弊端是对 技术上合理的功能,这意味着并非标准元数据 API 的所有功能都适用于 Gist API。 标准元数据 API 的所有功能都适用于 Gist API。

• The Gist API uses a divide and conquer strategy to avoid responses with large partial object graphs. Instead of including nested objects or lists it provides a /gist endpoint URI where this object or list can be viewed in isolation.
• The /gist API refers to nested data using URIs rather than including it. This means if a client is interested in this nested information more requests are required but each of them is kept reasonable small and will scale well in context of huge number of potential items.
• Known Differences:

items only includes fields of referenced identifiable objects if these do not

• have an endpoint on their own it never includes identifiable collections of objects directly items by default do not include all available fields, but a subset that depends
• on context and parameters
• lists cannot be used without pager (therefore there is no pager parameter)
• fields with collections are not paged using the pager-transformer but through
• a paged API endpoint for the particular collection property
• items in a list, a collection property size or boolean transformer result
• always considers object sharing (the set of considered items is always the set visible to the user)

Gist offers member(<id>) and not-member(<id>) collection field transformers

Gist offers canRead and canWrite access check filter instead of filtering¶

on the access property

Gist offers using attribute UIDs as field and filter property names to allow

• /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)
• Gist offers renaming the enrty list in a paged response using pageListName

Gist offers to pluck multiple simple properties

Known Limitations:¶

by default only persisted are included; a handful of special

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

non-persistent fields might be possible to extract using from transformation

filters can only be applied to persisted fields¶

orders can only be applied to persisted fields

token filters are not available

总览¶

pluck transformer limited to text properties (or simple properties for multi-pluck)

pageSize¶

1-1000

number of items on a page

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

<text>

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

overrides the property name of the result entry list

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

与或或

AND¶

logical combination of filters, AND= all must match, OR= at least one must match

• total/totalPages
• true or false
• false

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 }

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

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

For example, /api/users/rWLrZL8rP3K/gist?fields=id,href returns:

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

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

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

As the example shows the absoluteUrls parameter is also forwarded or carried over to the included URLs so allowing to browse the responses by following the provided URLs.

The auto Parameter { #the-auto-parameter }

Each endpoint implicitly sets a default for the extent of fields matched by the * / :all fields selector:

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

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

/api/<object-type>/<object-id>/<field-name>/gist: implies auto=M

The auto parameter is used to manually override the default to make list items include more or less fields. This setting again acts as a default which can be further overridden on a per field basis using an explicit transformation.

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

XS: includes only IDs and textual properties

例如，通过以下方式包含用户的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"
    ]
  }
}

The fields Parameter { #gist_parameters_fields }

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

To remove a field use either !<name> or -<name> in the list of fields. For example to remove the userGroups from a user, use:

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

The same principle can also be used to specify the transformer to use for a field. For example, to include the IDs of the user's user groups use:

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

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

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

• This creates items of the form:
• ```json { ... "userCredentials": { "id": "Z9oOHPi3FHB", "username": "guest" } }

  When including nested fields of collections the nested field must be a text
  property. 
  
  * 例如,通过以下方式包含用户的`userGroups`的所有`名称`:
  *     /api/users/gist?fields=*,userGroups[name]
  * This lists the `userGroups` as:
  
  ```json
  {
    "userGroups": {
      "name": [
        "_PROGRAM_Inpatient program",
        "_PROGRAM_TB program",
        "_DATASET_Superuser",
        "_PROGRAM_Superuser",
        "_DATASET_Data entry clerk",
        "_DATASET_M and E Officer"
      ]
    }
  }
  

Multiple filters can either be specified as comma-separated list of a single filter parameter or as multiple filter parameters each with a single filter.

描述

eq

field equals value

ieq

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

If the <value> of an in or !in filter is a list it is given in the form [value1,value2,...], for example: userGroups:in:[fbfJHSPpUQD,cYeuwXTCPkU].

Any >, >=, < <=, == or != comparison applied to a collection field with a numeric value will compare the size of the collection to the value, for example: userGroups:gt:0.

Any >, >=, < <=, == or != comparison applied to a text field with a integer number value will compare the text length to the value, for example: name:eq:4 (name has length 4).

Available binary pattern matching operators are:

Binary Operator

/api/organizationUnits/rZxk3S0qN63/children/gist?filter=项目:gt:0

like, ilike

All pattern matching operators named like are case-sensitive. All others are case-insensitive.

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

For example, to only list organisations on second level use

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

Similarly, when listing the children of a particular organisation unit the collection can be filtered. To only list those children that are connected to a program one would use:

/api/organizationUnits/rZxk3S0qN63/children/gist?filter=项目:gt:0

Binary operators for access (sharing) based filtering:

Binary Operator

描述

canRead

Has user <value> metadata read permission to the object

• canWrite
• Has user <value> metadata write permission to the object

canDataRead

Has user <value> data read permission to the object

canDataWrite

Has user <value> data write permission to the object

canAccess

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

When the user ID <value> is omitted the check is performed for the currently logged-in user. Similarly, if <value0> is ommitted for canAccess filter the check is performed for the currently logged-in user.

When applied to a simple value property, here code, the filter restricts the response to those data elements (owner object) the user can read/write:

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

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: /api/dataElements/gist?filter=categoryCombo:canWrite:OYLGMiazHtW

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/dataElements/gist?filter=dataElementGroups:canWrite:OYLGMiazHtW

{
  "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:

unary: <group>:<field>:<operator>

binary: <group>:<field>:<operator>:<value>

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

The behaviour is best explained with a small example for an imaginary object type with an age and name property.

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

The above filter has two groups 1 and 2, and the 2 group has 2 members. This is equivalent to the SQL (note the and and or as well as the grouping braces):

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

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

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

the effect would be equivalent to the following SQL instead:

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

The headless Parameter { #gist_parameters_headless }

Endpoints returning a list by default wrap the items with an envelope containing the pager and the list, which is named according to the type of object listed.

For example /api/organisationUnits/gist returns:

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

With headless=true the response to /api/organisationUnits/gist?headless=true is just the [...] list part in above example.

The inverse Parameter { #the-inverse-parameter }

The inverse can be used in context of a collection field gist of the form /api/<object-type>/<object-id>/<field-name>/gist to not list all items that are contained in the member collection but all items that are not contained in the member collection.

For example, while¶

/api/organisationUnits/rZxk3S0qN63/children/gist

指在分页列表中查看的页面，以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. The locale Parameter { #gist_parameters_locale }

指的是页面上的项目数。最多 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). For example, to sort organisation units alphabetically by name use:

/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.

The page Parameter { #gist_parameters_page }

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

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

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

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

The pageSize Parameter¶

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

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

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

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

AND: all filters have to match an entry for it to be included in the results

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

默认为与。

The pageListName Parameter¶

The array property in a paged response that contains the matching entry list is named after the object type contained in the list. For /api/organisationUnits/gist it would be named organisationUnits.

This default naming can be customized using the pageListName parameter. For example, /api/organisationUnits/gist?pageListName=matches returns a response root object with the format:

{
  "pager": {},
  "matches": []
}

The total or totalPages Parameter¶

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.

For example, /api/organisationUnits/gist returns a pager:

```json¶

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

* When counting the total matches (`total=true`) the response `pager` will 
contain the `total` field with the actual number of total matches at the cost
of an additional database operation.
* 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
  }
}

像name或shortName这样的字段可以被翻译(国际化)。¶

By default, any translatable field that has a translation is returned translated given that the user requesting the gist has an interface language configured.

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

| For example, /api/organisationUnits/gist returns items like this: | json { "name": "A translated name", ... } | 描述 | |----------------------|------------------------|-------------------------------------------------------------------------------------------------------| | json { "name" "Plain field name", ... } | -- | Fields { #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. | Note that the /gist API always excludes certain fields that usually are of no interest to clients, like for example the translations or sharing fields. These can be added explicitly. | | 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 | * / :all: default fields depend on the context and auto parameter | | :identifiable: all persisted fields of the IdentifiableObject interface | boolean | :nameable: all persisted fields of the NameableObject interface | | :persisted: literally all persisted fields | isEmpty | A transformer or transformation can be applied to a field by appending any of the indicators ::, ~ or @ followed by the transformer expression. | | Available transformer expressions are: | Transformer | JSON Result Type | | 描述 | boolean | 具有<id>的成员用于集合字段 | | renames the field in the response to <name> | boolean | 集合字段中没有具有<id>的成员 | | number of items in the collection field | isEmpty | boolean | | emptiness of a collection field | isNotEmpty | boolean |

non-emptiness of a collection field

ids

string or [string]

ID of an object or IDs of collection items

id-objects

[{ "id": <id> }]

IDs of collection items as object

member(<id>)

boolean

具有<id>的成员用于集合字段

not-member(<id>)¶

boolean

集合字段中没有具有<id>的成员

pluck(<field>,...)

string or [string]

总览¶

from(<field>,...)

Synthetic Fields¶

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.

Synthetic properties are available for all endpoints where the persisted properties needed to compute the synthetic property exist.

Except for the apiEndpoints property which is automatically added when needed all other synthetic properties are not included by default and have to be requested explicitly in the list of fields.

总览¶

Synthetic fields in alphabetical order:

领域

描述

apiEndpoints

contains links to browse nested complex objects or collections

href¶

link to the list item itself (single item view)

displayName

已翻译的名称(始终已翻译)

displayShortName

translated shortName (always translated)

access

{
  "id": "rWLrZL8rP3K",
  "userGroups": 0,
  "organisationUnits": 1,
  "apiEndpoints": {
    "organisationUnits": "/users/rWLrZL8rP3K/organisationUnits/gist",
    "userGroups": "/users/rWLrZL8rP3K/userGroups/gist"
  }
}

The href Field { #gist_syntheticFields_href }

Each item in a /gist response can link to itself. This link is given in the href property.

access

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

To add displayName or displayShortName add it to the list use (for example):

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

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

The apiEndpoints Field¶

This property provides the links to further browse complex objects or list of items that are included in the /gist response in form of a transformed simple value like an item count.

The apiEndpoints object will have a member of the same name for every member in the item that was transformed to a simple value.

For example,

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

returns items in the form:

{
  "id": "rWLrZL8rP3K",
  "userGroups": 0,
  "organisationUnits": 1,
  "apiEndpoints": {
    "organisationUnits": "/users/rWLrZL8rP3K/organisationUnits/gist",
    "userGroups": "/users/rWLrZL8rP3K/userGroups/gist"
  }
}

The list of userGroups and organisationUnits are included as their size. Each has a corresponding member in apiEndpoints with the path to browse the list.

The paths can be changed to URLs by using the absoluteUrls parameter.

例子¶

returns items in the form:

{
  "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 access Field { #the-access-field }

The access summary is based on the sharing and the current user. This means it is only applicable for objects that have a sharing property.

For example, when listing data elements with access field

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

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

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

Attributes as Fields { #gist_attributeFields }

DHIS2 allows creating and adding custom attributes to metadata objects. Their values are contained in the attributeValues property of a metadata object in form of a map with the attribute UID as the map's key.

To directly list one or more specific attribute values from this map as if they were usual fields of the metadata object the attribute UID can be used as if it was a name of a usual field.

For example, to include the value of the attribute with UID Y1LUDU8sWBR as the property unit-of-measure in the list use:

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

This results in list items of the form:

{
  "id": "qrur9Dvnyt5",
  "name": "Age in years",
  "unit-of-measure": "years"
}

By default, the values are fetched as JSON and extracted from the map of attribute values. This means the listing will contain the proper JSON type for the type of attribute value. This comes at the overhead of fetching all attribute values. To single out the value within the database the PLUCK transformation can be used.

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

The result will look the same but now the value is extracted as text in the database turning any JSON value to a string in the property output.

例子 { #gist_examples }

A few examples starting from simple listings moving on to very specific use cases.