元数据 ¶

标识符方案 ¶

本节提供标识符方案概念的解释。 标识符方案用于将元数据对象映射到其他元数据 在导入期间，并将元数据呈现为导出的一部分。请注意 并不是所有的方案都适用于所有的 API 调用，也不是所有的 方案可用于输入和输出。这在 部分解释了各种 Web API。

列出了可用的全套标识符方案对象类型 下面，使用在查询中使用的属性名称：

• 方案

• 数据元素标识方案

• categoryOptionComboIdScheme

• orgUnitIdScheme

• 程序标识方案

• 程序阶段标识方案

• 跟踪实体 ID 方案

• trackedEntityAttributeIdScheme

通用 idScheme 适用于所有类型的对象。有可能 被特定的对象类型覆盖。

所有参数的默认方案是 UID（稳定的 DHIS2 身份标识）。支持的标识符方案在 下表。

请注意，标识符方案不是一个独立的功能，但需要 与数据值导入、元数据导入等资源结合使用。

例如，指定 CODE 作为通用 id 方案并覆盖 使用 UID 作为组织单位 ID 方案，您可以使用这些查询 参数：

？idScheme = CODE＆orgUnitIdScheme = UID

再举一个例子，为组织单位 id 指定一个属性 方案，数据元素 id 方案的代码并使用默认 UID id 您可以使用这些参数的所有其他对象的方案：

？orgUnitIdScheme =属性：j38fk2dKFsG＆dataElementIdScheme = CODE

浏览Web API ¶

浏览 Web API 的入口点是 /api 。这个资源 提供所有可用资源的链接。四种资源表示 格式始终适用于所有资源：HTML、XML、JSON、 和 JSONP。某些资源将具有其他可用格式，例如 MS Excel、PDF、CSV 和 PNG。要从 Web 浏览器探索 API，请导航 到 /api 入口点并按照链接到您想要的 资源，例如 /api/dataElements 。对于所有资源 返回元素列表，某些查询参数可用于修改 响应：

如何使用这些参数获取完整列表的示例 XML 响应格式的数据元素组是：

/api/dataElementGroups.xml?links=false&paging=false

您可以在 name 属性上查询元素而不是返回 使用 query 查询变量的完整元素列表。在这个例子中 我们查询名称中带有“贫血”一词的所有数据元素：

/ api / dataElements？query =贫血

您可以像这样获取特定页面和对象的页面大小：

/api/dataElements.json?page=2&pageSize=20

您可以像这样完全禁用分页：

/api/indicatorGroups.json?paging=false

要基于特定属性对结果进行排序：

/api/indicators.json?order=shortName:desc

您可以通过以下方式在所有对象类型中根据对象的 ID 查找对象 identifiableObjects 资源：

/ api / identifiableObjects / <id>

翻译 ¶

DHIS2 supports translations of database content, such as data elements, indicators, and programs. All metadata objects in the Web API have properties meant to be used for display / UI purposes, which include displayName , displayShortName , displayDescription and displayFormName (for data elements and tracked entity attributes).

翻译API ¶

对象的翻译呈现为对象本身的一部分 在* translation *数组中。请注意， JSON / XML有效负载的*翻译*数组通常为您预先过滤，这意味着它们不能直接用于导入/导出翻译（因为那样会 通常会覆盖当前用户以外的语言环境）。

在用户语言环境中过滤了转换数组的数据元素示例：

{
  "id": "FTRrcoaog83",
  "displayName": "Accute French",
  "translations": [
      "property": "SHORT_NAME",
      "locale": "fr",
      "value": "Accute French"
      "property": "NAME",
      "locale": "fr",
      "value": "Accute French"

转换关闭的数据元素示例：

{
  "id": "FTRrcoaog83",
  "displayName": "Accute Flaccid Paralysis (Deaths < 5 yrs)",
  "translations": [
      "property": "FORM_NAME",
      "locale": "en_FK",
      "value": "aa"
      "property": "SHORT_NAME",
      "locale": "en_GB",
      "value": "Accute Flaccid Paral"
      "property": "SHORT_NAME",
      "locale": "fr",
      "value": "Accute French"
      "property": "NAME",
      "locale": "fr",
      "value": "Accute French"
      "property": "NAME",
      "locale": "en_FK",
      "value": "aa"
      "property": "DESCRIPTION",
      "locale": "en_FK",
      "value": "aa"

请注意，即使您得到未过滤的结果，并且正在使用 适当的类型端点，即我们不允许的 /api/dataElements 更新，因为这样做很容易犯错误并覆盖 其他可用的语言环境。

要阅读和更新翻译，您可以使用特殊翻译 每个对象资源的端点。可以通过*GET*或访问 在适当的 / api / <object-type> / <object-id> / translations 端点上* PUT *。

As an example, for a data element with identifier FTRrcoaog83 , you could use /api/dataElements/FTRrcoaog83/translations to get and update translations. The fields available are property with options NAME , SHORT_NAME , FORM_NAME , DESCRIPTION , locale which supports any valid locale ID and the translated property value .

法语语言环境的NAME属性示例：

{
  "property": "NAME",
  "locale": "fr",
  "value": "Paralysie Flasque Aiguë (Décès <5 ans)"

然后将此有效负载添加到翻译数组中，并发回 到适当的端点：

{
  "translations": [
      "property": "NAME",
      "locale": "fr",
      "value": "Paralysie Flasque Aiguë (Décès <5 ans)"

对于ID为* FTRrcoaog83 的数据元素，您可以 PUT *此代码为 / api / dataElements / FTRrcoaog83 / translations 。确保发送全部 特定对象的翻译，而不仅仅是单个语言环境的翻译 （否则，您可能会覆盖其他区域的现有语言环境 语言环境）。

Web API版本 ¶

Web API的版本从DHIS 2.25开始。 API版本 遵循DHIS2主版本号。例如，API DHIS 2.33的版本是 33 。

您可以通过包含版本号来访问特定的 API 版本 在 /api 组件之后，作为这样的例子：

/ api / 33 / dataElements

如果省略 URL 的 version 部分，系统将使用当前的 API 版本。例如，对于 DHIS 2.25，在省略 API 部分时， 系统将使用 API 版本 25。在开发 API 客户端时，它是 建议使用显式 API 版本（而不是省略 API 版本），因为这将保护客户端免受不可预见的 API 更改。

将支持最后三个 API 版本。例如，DHIS 2.27 版本将支持 API 版本 27、26 和 25。

请注意，元数据模型没有版本控制，您可能 体验变化，例如在对象之间的关联中。这些变化 将记录在 DHIS2 主要版本发行说明中。

元数据对象过滤器 ¶

要过滤元数据，可以使用多种过滤操作 应用于返回的元数据列表。过滤器的格式 本身是直截了当的并遵循模式 property:operator:value ，其中 property 是 要过滤的元数据， operator 是比较运算符 您想要执行并且 value 是要检查的值（不是全部 运算符需要值）。请参阅 schema 部分以发现 哪些属性可用。递归过滤，即。过滤 也支持关联对象或对象集合。

运算符将作为逻辑 and 查询应用，如果您需要 or 查询，您可以查看我们的 in 过滤器（也可以查看 以下部分）。过滤机制允许递归。见下文 对于一些例子。

获取ID属性为ID1或ID2的数据元素：

/ api / dataElements？filter = id：eq：ID1＆filter = id：eq：ID2

获取具有ID为ID1的dataSet的所有数据元素：

/api/dataElements?filter=dataSetElements.dataSet.id:eq:ID1

使用聚合运算符“sum”和值类型获取所有数据元素 “内部”：

/api/dataElements.json?filter=aggregationOperator:eq:sum&filter=type:eq:int

您可以在集合中进行过滤，例如获取数据元素 是“ANC”数据元素组的成员，您可以使用以下内容 使用关联数据元素组的 id 属性查询：

/api/dataElements.json?filter=dataElementGroups.id:eq:qfxEYY9xAl6

由于默认情况下所有运算符都是 and ，因此您无法找到数据 匹配多个 id 的元素，为此您可以使用 in 操作员。

/api/dataElements.json?filter=id:in:[fbfJHSPpUQD,cYeuwXTCPkU]

逻辑运算符 ¶

如前一节所述，应用了默认逻辑运算符 过滤器是 AND 这意味着所有对象过滤器必须是 匹配。但是，在某些情况下，您希望匹配其中之一 几个过滤器（可能是 id 和 code 字段），在这些情况下，它是 可以将根逻辑运算符从 AND 切换为 OR 使用 rootJunction 参数。

示例：正常过滤，其中 id 和 code 必须匹配才能具有 结果返回

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1

示例：过滤逻辑运算符已切换为 OR 的位置 现在只有一个过滤器必须匹配才能产生结果 回

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1&rootJunction=OR

可识别的令牌过滤器 ¶

除了上述基于特定属性的过滤之外， 我们还通过* token 基于 AND 过滤了一组 属性：ID，代码和名称（如果可用，还包括shortName）。这些 属性通常称为*可识别 。这个想法是为了 过滤ID，名称，代码或简称中包含某些内容的元数据。

示例：过滤所有包含 2 ^nd 的数据元素 如下： id,name,code,shortName

/api/dataElements.json?filter=identifiable:token:2nd

也可以指定多个过滤值。

示例：获取在任何 identifiable 属性中找到 ANC visit 的所有数据元素。系统返回所有数据元素，其中在可识别属性中的任何地方都可以找到令牌（ANC 和访问）。

/api/dataElements.json?filter=identifiable:token:ANC访问

也可以将可识别过滤器与基于属性的过滤器结合起来，并期望应用 rootJunction 。

/api/dataElements.json?filter=identifiable:token:ANC visit＆filter = displayName：ilike：tt1
/api/dataElements.json?filter=identifiable:token:ANC访问
  ＆filter = displayName：ilike：tt1＆rootJunction = OR

元数据字段过滤器 ¶

在许多情况下，元数据的默认视图可能太 冗长。客户可能只需要每个对象的几个字段，并且想要 从响应中删除不必要的字段。发现哪些字段 可用于每个对象，请参阅 schema 部分。

包含/排除的格式允许无限递归。过滤 在“根”级别，您可以只使用字段的名称， 即 ?fields=id,name 它只会显示 id 和 每个对象的 name 字段。对于集合或 具有自身属性的复杂对象，您可以使用格式 ?fields=id,name,dataSets[id,name] 将返回的 id 、 name 根，以及该对象上每个数据集的 id 和 name 。 否定可以用感叹号来完成，我们有一组 字段选择的预设。支持 XML 和 JSON。

示例 ：在指标资源上获取 id 和 name ：

/ api / indicators？fields = id，名称

示例 ：从dataElements中获取 id 和 name ，以及 id 和 name 。 从dataElements上的dataSets中：

/ api / dataElements？fields = id，name，dataSets [id，name]

要从输出中排除字段，可以使用感叹号 ! 。 操作符。这是在查询中的任何地方都允许的，而根本不会 包括该属性，因为它可能已经插入了某些 预设。

一些预设（选定的字段组）可用并且可以应用 使用 : 运算符。

示例 ：包括dataSet中的所有字段（organizationunits除外）：

/ api / dataSets？fields =：all，！organizationUnits

示例 ：仅包含ID，名称和数据集中的组织单位集合，但不包含组织单位中的ID：

/ api / dataSets / BfMAe6Itzgt？fields = id，name，organisationUnits [：all，！id]

示例 ：包括所有指标的可命名属性：

/api/indicators.json?fields=:nameable

现场变压器 ¶

在 DHIS2.17 中我们引入了场变压器，其想法是允许 进一步定制服务器端的属性。

/api/dataElements/ID?fields=id~rename(i),name~rename(n)

这会将 id 属性重命名为 i ，将 name 属性重命名为 n 。

可以通过重复变压器语法来使用多个变压器：

/api/dataElementGroups.json?fields=id,displayName,dataElements~isNotEmpty~rename(haveDataElements）

例子 ¶

变压器用法示例。

/api/dataElements?fields=dataSets~size
/api/dataElements?fields=dataSets~isEmpty
/api/dataElements?fields=dataSets~isNotEmpty
/api/dataElements/ID?fields=id~rename(i),name~rename(n)
/api/dataElementGroups?fields=id,displayName,dataElements~paging(1;20)
# Include array with IDs of organisation units:
/api/categoryOptions.json?fields=id,organisationUnits~pluck
# Include array with names of organisation units (collection only returns field name):
/api/categoryOptions.json?fields=id,organisationUnits~pluck[name]

元数据创建，读取，更新，删除，验证 ¶

DHIS2 中的所有元数据实体都有自己的 API 端点，支持 CRUD 操作（创建、读取、更新和删除）。端点 URL 遵循以下格式：

/ api / <entityName>

entityName 使用驼峰命名法。例如，端点 对于_数据元素_是：

/ api / dataElements

创建/更新参数 ¶

以下请求查询参数可用于所有元数据端点。

创建和更新对象 ¶

要创建新对象，您需要知道端点、类型 格式，并确保您拥有所需的权限。作为 例如，我们将创建和更新一个*常量*。为了弄清楚 格式，我们可以使用新的 schema 端点来获取格式 描述。因此，我们将从获取该信息开始：

http：// <server> /api/schemas/constant.json

从输出中，您可以看到创建所需的权限 是 F_CONSTANT_ADD ，重要的属性是： name 和 价值 。由此，我们可以创建一个 JSON 负载并将其保存为文件 称为constant.json：

{
  "name": "PI",
  "value": "3.14159265359"

与XML有效内容相同的内容：

<constant name="PI" xmlns="http://dhis2.org/schema/dxf/2.0">
  <value>3.14159265359</value>
</constant>

我们现在准备通过发送 POST 请求来创建新的*常量* 使用curl 的带有JSON 有效负载的 constants 端点：

curl -d @constant.json "http://server/api/constants" -X POST
  -H "Content-Type: application/json" -u user:password

将常量发布到演示中的具体示例 服务器：

curl -d @constant.json "https://play.dhis2.org/api/constants" -X POST
  -H "Content-Type: application/json" -u admin:district

如果一切顺利，您应该看到类似以下的输出：

{
  "status": "SUCCESS",
  "importCount": {
    "imported": 1,
    "updated": 0,
    "ignored": 0,
    "deleted": 0
  "type": "Constant"

更新过程将完全相同，您进行更改 到 JSON/XML 负载，找出常量的 ID ，然后 向端点发送包含 ID 的 PUT 请求：

curl -X PUT -d @pi.json -H "Content-Type: application/json"
  -u user:password "http://server/api/constants/ID"

删除物件 ¶

删除对象非常简单，您需要知道 ID 和你要删除的类型的端点，让我们继续我们的 上一节中的示例并使用*常量*。让我们假设 id 是 abc123 ，那么你需要做的就是发送 DELETE 对端点的请求 + id：

curl -X DELETE -u user:password "http://server/api/constants/ID"

成功删除应返回HTTP状态204（无内容）。

在集合中添加和删除对象 ¶

集合资源允许您修改集合 对象。

添加或删除单个对象 ¶

为了在对象集合中添加或删除对象，您 可以使用以下 图案：

/ api / {collection-object} / {collection-object-id} / {collection-name} / {object-id}

应该使用POST方法添加，使用DELETE方法删除 一个东西。当对象之间存在多对多关系时， 您必须首先确定哪个对象拥有该关系。如果不是 清除这是哪个对象，尝试两种方式调用以查看哪个有效。

模式的组成部分是：

• 集合对象：拥有您的集合的对象类型 想修改。

• 集合对象 id：拥有该对象的对象的标识符 要修改的集合。

• 集合名称：您要修改的集合的名称。

• object id：要添加或删除的对象的标识符 从集合。

例如，为了删除标识符为 IDB 的数据元素 从具有标识符 IDA 的数据元素组中，您可以执行 DELETE 要求：

删除/ api / dataElementGroups / IDA / dataElements / IDB

将带有标识符 IDB 的类别选项添加到带有 标识符 IDA 你可以做一个 POST 要求：

POST / api / categories / IDA / categoryOptions / IDB

添加或删除多个对象 ¶

您可以在一个请求中从集合中添加或删除多个对象 具有这样的有效载荷：

{
  "identifiableObjects": [{
      "id": "IDA"
    }, {
      "id": "IDB"
    }, {
      "id": "IDC"

使用此有效负载，您可以添加，替换或删除项目：

添加项目：

POST / api / categories / IDA / categoryOptions

更换物品：

PUT /api/categories/IDA/categoryOptions

删除 项目：

删除/ api / categories / IDA / categoryOptions

在单个请求中添加和删除对象 ¶

您可以在单个 POST 中从集合中添加和删除对象 请求到以下 URL：

POST / api / categories / IDA / categoryOptions

有效负载格式为：

{
  "additions": [{
      "id": "IDA"
    }, {
      "id": "IDB"
    }, {
      "id": "IDC"
  "deletions": [{
      "id": "IDD"
    }, {
      "id": "IDE"
    }, {
      "id": "IDF"

验证有效载荷 ¶

DHIS 2 支持元数据有效载荷的系统范围验证，这意味着 将检查 API 端点上的创建和更新操作 允许进行更改之前的有效负载。找出哪些验证 为特定端点准备好了，看看 /api/schemas 端点，即要找出数据元素具有哪些约束，您 会去 /api/schemas/dataElement 。

您还可以手动验证您的有效负载，方法是将其发送到适当的 架构端点。如果您想从创建中验证常量 之前的部分，您可以这样发送：

POST / api / schemas / constant

一个简单的（非验证）示例为：

curl -X POST -d "{\"name\": \"some name\"}" -H "Content-Type: application/json"
  -u admin:district "https://play.dhis2.org/dev/api/schemas/dataElement"

Which will yield the result:

[
      "message" : "Required property missing.",
      "property" : "type"
      "property" : "aggregationOperator",
      "message" : "Required property missing."
      "property" : "domainType",
      "message" : "Required property missing."
      "property" : "shortName",
      "message" : "Required property missing."

部分更新 ¶

For our web api endpoints that deal with metadata, we support partial updates (PATCH) using the JSON Patch standard . The payload basically outlines a set of operation you want applied to a existing metadata object. For examples of JSON patch please see jsonpatch.com , we support 3 operators: add , remove and replace .

Below is a few examples relevant to dhis2, please note that any update to a payload should be thought of as a HTTP PUT (i.e. any mutation must result in a valid PUT metadata payload).

The default importReportMode for JSON Patch is ERRORS_NOT_OWNER which means that if you try and update any property that is not owned by that particular object (for example trying to add a indicator group directly to an indicator) you will get an error.

As per the JSON Patch specification you must always use the mimetype application/json-patch+json when sending patches.

例子 ¶

Update name and value type of data element ¶

PATCH /api/dataElements/{id}
  {"op": "add", "path": "/name", "value": "New Name"},
  {"op": "add", "path": "/valueType", "value": "INTEGER"}

Add new data element to a data element group ¶

PATCH /api/dataElementGroups/{id}
  {"op": "add", "path": "/dataElements/-", "value": {"id": "data-element-id"}}




    

Remove all data element associations from a data element group ¶

PATCH /api/dataElementGroups/{id}
  {"op": "remove", "path": "/dataElements"}

Change domain and value type of a data element ¶

PATCH /api/dataElements/{id}
    {"op": "add", "path": "/domainType", "value": "TRACKER"},
    {"op": "add", "path": "/valueType", "value": "INTEGER"}

Remove a specific orgUnit from an orgUnit group ¶

PATCH /api/organisationUnitGroups/{id}
  {"op": "remove", "path": "/organisationUnits/1"}

元数据导出 ¶

本节介绍了可在以下位置获得的元数据 API /api/元数据 。支持 XML 和 JSON 资源表示。

/ api /元数据

最常用的参数在下面的“导出参数”中描述 桌子。您还可以使用以下方法将其应用于所有可用类型 type:fields=<filter> 和 type:filter=<filter> 。你也可以 通过设置 type=true|false 启用/禁用某些类型的导出。

元数据导出示例 ¶

导出所有元数据。小心，因为响应可能非常大，具体取决于 关于您的元数据配置：

/ api /元数据

导出由lastUpdated降序排列的所有元数据：

/ api / metadata？defaultOrder = lastUpdated：desc

导出仅包括指标和指标组的元数据：

/ api / metadata？indicators = true＆indicatorGroups = true

导出所有数据元素的id和displayName，按displayName排序：

/ api / metadata？dataElements：fields = id，name＆dataElements：order = displayName：desc

导出名称以“ ANC”开头的数据元素和指示符：

/ api / metadata？filter = name：^ like：ANC＆dataElements = true＆indicators = true

具有依赖项的元数据导出 ¶

When you want to exchange metadata for a data set, program, category combo, dashboard, option set or data element group from one DHIS2 instance to another instance there are six dedicated endpoints available:

/api/dataSets/{id}/metadata.json
/api/programs/{id}/metadata.json
/api/categoryCombos/{id}/metadata.json
/api/dashboards/{id}/metadata.json
/api/optionSets/{id}/metadata.json
/api/dataElementGroups/{id}/metadata.json

然后可以使用 / api / metadata 导入这些导出。

这些端点还支持以下参数：

元数据导入 ¶

本节介绍元数据导入 API。 XML 和 JSON 资源 支持表示。可以使用 POST 请求导入元数据。

/ api /元数据

导入器允许您导入元数据有效负载，其中可能包括许多 不同的实体和每个实体的任意数量的对象。元数据导出 元数据导出API生成的可以直接导入。

元数据导入端点支持多种参数，分别是 下面列出。

(*) Currently the mergeMode=MERGE option of the import service has limitations and doesn't support all objects. It doesn't work with some object types such as Embedded objects, or objects which are saved as JSONB format in database ( sharing, attributeValues, etc...). Fixing those issues are complicated and would just cause new issues. Therefore, this mergedMode=MERGE is deprecated and currently is not recommended to use. The update mode should always be mergedMode=REPLACE. We have developed a new JSON Patch API which can be used as an alternative approach. This feature is introduced in 2.37 release.

要导入的元数据负载的示例如下所示。注意如何 每个实体类型都有自己的属性和一个对象数组：

{
  "dataElements": [
      "name": "EPI - IPV 3 doses given",
      "shortName": "EPI - IPV 3 doses given",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "valueType": "INTEGER_ZERO_OR_POSITIVE"
      "name": "EPI - IPV 4 doses given",
      "shortName": "EPI - IPV 4 doses given",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "valueType": "INTEGER_ZERO_OR_POSITIVE"
  "indicators": [
      "name": "EPI - ADS stock used",
      "shortName": "ADS stock used",
      "numerator": "#{LTb8XeeqeqI}+#{Fs28ZQJET6V}-#{A3mHIZd2tPg}",
      "numeratorDescription": "ADS 0.05 ml used",
      "denominator": "1",
      "denominatorDescription": "1",
      "annualized": false,
      "indicatorType": {
        "id": "kHy61PbChXr"

将此有效负载发布到元数据端点时，响应将包含 有关导入过程中使用的参数的信息和每个摘要 实体类型，包括创建、更新、删除和 忽略：

{
  "importParams": {
    "userOverrideMode": "NONE",
    "importMode": "COMMIT",
    "identifier": "UID",
    "preheatMode": "REFERENCE",
    "importStrategy": "CREATE_AND_UPDATE",
    "atomicMode": "ALL",
    "mergeMode": "REPLACE",
    "flushMode": "AUTO",
    "skipSharing": false,
    "skipTranslation": false,
    "skipValidation": false,
    "metadataSyncImport": false,
    "firstRowIsHeader": true,
    "username": "UNICEF_admin"
  "status": "OK",
  "typeReports": [
      "klass": "org.hisp.dhis.dataelement.DataElement",
      "stats": {
        "created": 2,
        "updated": 0,
        "deleted": 0,
        "ignored": 0,
        "total": 2
      "klass": "org.hisp.dhis.indicator.Indicator",
      "stats": {
        "created": 1,
        "updated": 0,
        "deleted": 0,
        "ignored": 0,
        "total": 1
  "stats": {
    "created": 3,
    "updated": 0,
    "deleted": 0,
    "ignored": 0,
    "total": 3

架构图 ¶

可用于内省所有可用 DXF 2 对象的资源 可以在 /api/schemas 上找到。对于特定资源，您可以拥有 查看 /api/schemas/<type> 。

要获取XML中所有可用的模式：

GET /api/schemas.xml

要获取JSON中所有可用的模式，请执行以下操作：

GET /api/schemas.json

要获取特定类的JSON模式：

GET /api/schemas/dataElement.json

图示 ¶

DHIS2 包括一组可用于提供视觉效果的图标 元数据的上下文。这些图标可以通过图标访问 资源。

GET /api/icons

此端点返回有关可用图标的信息列表。 每个条目都包含有关图标的信息，以及对图标的引用 实际图标。

{
  key: "mosquito_outline",
  description: "Mosquito outline",
  keywords: [
    "malaria",
    "mosquito",
    "dengue"
  href: "<dhis server>/api/icons/mosquito_outline/icon.svg"

关键字可用于过滤要返回的图标。传递一个列表 带有请求的关键字将只返回与所有匹配的图标 关键词：

GET /api/icons?keywords=shape,small

可以在关键字资源中找到所有唯一关键字的列表：

GET /api/icons/keywords

渲染类型 ¶

某些元数据类型具有名为 renderType 的属性。渲染类型 属性是 device 和 renderingType 之间的映射。应用 可以使用此信息作为有关如何呈现对象的提示 在特定设备上。例如，移动设备可能想要渲染 与台式计算机不同的数据元素。

当前有两种不同的renderingTypes可用：

1. 值类型渲染

2. 程序阶段部分渲染

还提供2种设备类型：

1. 移动

2. 桌面

下表列出了可用的元数据和呈现类型。 值类型呈现具有基于元数据的附加约束 配置，这将显示在第二个表中。

由于处理数据元素和跟踪实体的默认呈现 属性取决于对象的值类型，还有 一个 DEFAULT 类型告诉客户端它应该被正常处理。 程序阶段部分默认为“列表”。

上表的完整参考也可以使用 以下端点：

GET /api/staticConfiguration/renderingOptions

值类型渲染也有一些额外的属性，可以 设置，通常在渲染某些特定类型时需要：

renderingType 可以在创建或更新第一个表中列出的元数据时设置。程序阶段部分的渲染类型的示例负载如下所示：

{
  "renderingType": {
    "type": "MATRIX"

对于数据元素和跟踪的实体属性：

{
  "renderingType": {
    "type": "SLIDER",
    "min": 0,
    "max": 1000,
    "step": 50,
    "decimalPoints": 0

对象样式 ¶

大多数元数据都有一个属性名称“样式”。可以使用此属性 由客户以某种方式表示对象。属性 目前支持的样式如下：

目前，没有官方列表或对图标库的支持，所以 这目前由客户提供。下面的列表显示 所有支持样式的对象：

• 数据元素

• 数据元素类别选项

• 资料集

• 指示符

• 选项

• 程序

• 计划指标

• 计划科

• 程序阶段

• 程序阶段部分

• 关系（跟踪器）

• 跟踪实体属性

• 追踪实体类型

在创建或更新任何这些对象时，您可以包括 以下有效负载更改样式：

{
  "style": {
    "color": "#ffffff",
    "icon": "my-beautiful-icon"

指标 ¶

本节介绍指标和指标表达式。

综合指标 ¶

要检索指标，您可以向指标发出 GET 请求 像这样的资源：

/ api /指标

指标表示可以计算和呈现的表达式 因此。指标表达式分为分子和 分母。分子和分母是数学的 可以包含对数据元素、其他指标、常量和 组织单位组。变量将替换为数据 使用时的值，例如在报告中。允许的变量 表达式在下表中描述。

Within a Data element operand or an Aggregate data element, the following substitutions may be made:

语法看起来像 这：

＃

相应的示例如下所示：

＃

请注意，对于数据元素变量，类别选项组合 标识符可以省略。该变量将代表总数 对于数据元素，例如在所有类别选项组合中。例子：

＃

数据元素操作数可以包括任何类别选项组合和 属性选项组合，并使用通配符表示任何 价值：

＃

An example using a data element group:

#{deGroup:oDkJh5Ddh7d} + #{deGroup:GBHN1a1Jddh.j8vBiBqGf6O}

An example using a category option, data element group, and a category option group:

#{P3jJH5Tu5VC.co:FbLZS3ueWbQ} + #{deGroup:GBHN1a1Jddh.coGroup:OK2Nr4wdfrZ.j8vBiBqGf6O}

An example using multiple category option groups:

#{P3jJH5Tu5VC.coGroup:OK2Nr4wdfrZ&j3C417uW6J7&ddAo6zmIHOk}

An example using a program data element and a program attribute:

（D {eBAyeGv0exc.vV9UWAZohSf} * A {IpHINAT79UW.cejWyOfXge6}）/ D {eBAyeGv0exc.GieVkTxp4HH}

An example combining program indicators and aggregate indicators:

I {EMOt6Fwhs1n} * 1000 /＃{WUg3MYWQ7pt}

An example using a reporting rate:

R {BfMAe6Itzgt.REPORTING_RATE} *＃{P3jJH5Tu5VC.S34ULMcHMca}

Another reporting rate example using actual data set reports and expected reports:

R {BfMAe6Itzgt.ACTUAL_REPORTS} / R {BfMAe6Itzgt.EXPECTED_REPORTS}

An example using an existing indicator:

N {Rigf2d2Zbjp} *＃{P3jJH5Tu5VC.S34ULMcHMca}

表达式可以是任何类型的有效数学表达式，作为 例子：

（2 *＃{P3jJH5Tu5VC.S34ULMcHMca}）/（＃{FQ2o8UBlcrS.S34ULMcHMca}-200）* 25

计划指标 ¶

要检索程序指标，您可以向程序发出 GET 请求 像这样的指标资源：

/ api / programIndicators

程序指示器可以包含在程序中收集的信息。 指标有一个表达式，可以包含对数据的引用 元素、属性、常量和程序变量。变量 下表中描述了允许在表达式中使用。

语法看起来像 这：

＃

一个相应的例子看起来像 这：

＃

表达方式 ¶

表达式是数学公式，可以包含对 数据元素、常量和组织单元组。验证和 获取表达式的文本描述，您可以发出 GET 请求 到表达式资源：

/ api / expressions / description？expression = <expression-string>

响应遵循标准的 JSON Web 消息格式。 状态 属性表示验证的结果，如果 成功和“错误”如果失败。 message 属性将为“有效” 如果成功并提供原因的文字描述 如果不是，则验证失败。 *描述*提供了文字说明 表达式的描述。

{
  "httpStatus": "OK",
  "httpStatusCode":




    
 200,
  "status": "OK",
  "message": "Valid",
  "description": "Acute Flaccid Paralysis"

组织单位 ¶

organisationUnits 资源遵循标准约定，如 DHIS2 中的其他元数据资源。该资源支持一些 附加查询参数。

获取组织单位列表 ¶

要获取组织单位的列表，可以使用以下资源。

/ api / 33 / organisationUnits

Get organisation unit with sub-hierarchy ¶

To get an organisation unit including organisation units in its sub-hierarchy you can use the following resource.

/ api / 33 / organisationUnits / {id}

Get organisation units by category option ¶

Purpose-built endpoint to retrieve associations between category options and organisation units. This endpoint is the preferred way to retrieve program organisation unit associations.

/api/33/categoryOptions/orgUnits?categoryOptions={categoryOptionIdA},{categoryOptionIdB}

responses will have the following format:

{
  "<categoryOptionIdA>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  "<categoryOptionIdB>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  "<categoryOptionIdC>": []

Category options that are accessible by all organisation units are returned with an empty array ( [] ) of organisation units.

Get organisation units by programs ¶

Purpose-built endpoint to retrieve associations between programs and organisation units. This endpoint is the preferred way to retrieve program organisation unit associations.

/api/33/programs/orgUnits?programs={programIdA},{programIdB}

responses will have the following format:

{
  "<programIdA>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  "<programIdB>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  "<programIdC>": []

Programs which are accessible by all organisation units are returned with an empty array ( [] ) of organisation units.

Split organisation unit ¶

The organisation unit split endpoint allows you to split organisation units into a number of target organisation units.

Request ¶

Split organisation units with a POST request:

POST /api/organisationUnits/split

The payload in JSON format looks like the following:

{
  "source": "rspjJHg4WY1",
  "targets": [
    "HT0w9YLMLyn",
    "rEpnzuNpRKM"
  "primaryTarget": "HT0w9YLMLyn",
  "deleteSource": true

The JSON properties are described in the following table.

The split operation will split the source org unit into the target org units. It is recommended to first create new target org units before performing the split, and at a minimum ensure that no aggregate data exists for the target org units. Any number of target org units can be specified.

The split operation will transfer all of the metadata associations of the source org unit over to the target org units. This includes data sets, programs, org unit groups, category options, users, visualizations, maps and event reports.

The operation will transfer all data records of the source org unit over to the org unit specified as the primary target, or if not specified, the first specified target org unit. This includes aggregate data values, data approval records, events, tracked entities and more.

Validation ¶

The following constraints and error codes apply.

Merge organisation units ¶

The organisation unit merge endpoint allows you to merge a number of organisation units into a target organisation unit.

Request ¶

Merge organisation units with a POST request:

POST /api/organisationUnits/merge

The payload in JSON format looks like the following:

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  "target": "V9rfpjwHbYg",
  "dataValueMergeStrategy": "LAST_UPDATED",
  "dataApprovalMergeStrategy": "LAST_UPDATED",
  "deleteSources": true

The JSON properties are described in the following table.

The merge operation will merge the source org units into the target org unit. It is recommended to first create a new target org unit before performing the merge, and at a minimum ensure that no aggregate data exists for the target org unit. Any number of source org units can be specified.

The merge operation will transfer all of the metadata associations of the source org units over to the target org unit. This includes data sets, programs, org unit groups, category options, users, visualizations, maps and event reports. The operation will also transfer all event and tracker data, such as events, enrollments, ownership history, program ownership and tracked entities, over to the target org unit.

指定的数据值合并策略定义了如何处理数据值。对于 LAST_UPDATED 策略，所有源组织单位的数据值都将转移到目标组织单位，并且在相同参数存在数据值的情况下，将使用最后更新或创建的数据值。这样做是为了避免数据重复。对于 DISCARD 策略，数据值不会转移到目标组织单位，而是简单地删除。指定的数据审批合并策略定义了数据审批记录的处理方式，并遵循与数据值相同的逻辑。

Validation ¶

The following constraints and error codes apply.

数据集 ¶

dataSets 资源遵循标准约定作为其他 DHIS2 中的元数据资源。此资源支持一些额外的 查询参数。

/ api / 33 / dataSets

要检索数据集的版本，您可以发出GET请求：

GET /api/33/dataSets/<uid>/version

要提高（增加一个）数据集的版本，您可以发出 POST 要求：

POST / api / 33 / dataSets / <uid> / version

Data set notification template ¶

*数据集通知模板*资源遵循标准 DHIS2 中其他元数据资源的约定。

GET /api/33/dataSetNotficationTemplates

要检索数据集通知模板，您可以发出GET请求：

GET /api/33/dataSetNotficationTemplates/<uid>

要添加数据集通知模板，您可以发出POST请求：

POST / api / 33 / dataSetNotficationTemplates

要删除数据集通知模板，您可以发出DELETE请求：

删除/ api / 33 / dataSetNotficationTemplates / <uid>

JSON有效负载示例如下：

{
  "name": "dataSetNotificationTemplate1",
  "notificationTrigger": "COMPLETION",
  "relativeScheduledDays": 0,
  "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
  "dataSets": [{
    "id": "eZDhcZi6FLP"
  "deliveryChannels": ["SMS"],
  "subjectTemplate": "V{data_name}",
  "messageTemplate": "V{data_name}V{complete_registration_period}",
  "sendStrategy": "SINGLE_NOTIFICATION"

填充的组织单位级别 ¶

fillOrganisationUnitLevels 资源提供了一个有序的列表 组织单元级别，其中生成的级别被注入到 列表以填充不存在持久级别的位置。

GET /api/33/filledOrganisationUnitLevels

To set the organisation unit levels you can issue a POST request with a JSON payload and content type application/json looking like this:

{
  "organisationUnitLevels": [{
    "name": "National",
    "level": 1,
    "offlineLevels": 3
  }, {
    "name": "District",
    "level": 2
  }, {
    "name": "Chiefdom",
    "level": 3
  }, {
    "name": "Facility",
    "level": 4

预测变量 ¶

预测器允许您根据表达式生成数据值。 这可以用于例如生成目标、阈值、 或估计值。

要检索预测器，您可以向预测器发出 GET 请求 像这样的资源：

/ api / predictors

创建预测变量 ¶

您可以使用对预测器的 POST 请求创建预测器 资源：

POST / api / predictors

有效负载样本如下所示：

{
  "id": "AG10KUJCrRk",
  "name": "Malaria Outbreak Threshold Predictor",
  "shortName": "Malaria Outbreak Predictor",
  "description": "Computes the threshold for potential malaria outbreaks based on the mean plus 1.5x the std dev",
  "output": {
    "id": "nXJJZNVAy0Y"
  "generator": {
    "expression": "AVG(#{r6nrJANOqMw})+1.5*STDDEV(#{r6nrJANOqMw})",
    "description": "Maximum normal malaria case count",
    "missingValueStrategy": "NEVER_SKIP",
    "slidingWindow": false
  "periodType": "Monthly",
  "sequentialSampleCount": 4,
  "sequentialSkipCount": 1,
  "annualSampleCount": 3,
  "organisationUnitLevels": [4]

输出元素是指数据元素的标识符 其中保存预测数据值。生成器元素是指 计算预测值时使用的表达式。

预测表达式 ¶

预测器总是有一个生成器表达式来描述 计算出预测值。预测器也可能有跳过测试 表达式返回一个布尔值。当跳过测试表达式为 目前，在每个采样周期中对其进行评估，以判断是否 应该跳过那个时期的值。

以下变量可用于生成器表达式 或跳过测试表达式：

生成预测值 ¶

要运行所有预测器（生成预测值），您可以进行 POST 请求运行资源：

POST / api / predictors / run

要运行单个预测器，您可以向运行发出 POST 请求 预测器的资源：

POST / api / predictors / AG10KUJCrRk / run

计划规则 ¶

本节是关于发送和读取程序规则，并解释 程序规则数据模型。程序规则赋予功能 在 DHIS2 程序中配置动态行为。

程序规则模型 ¶

程序规则数据模型由 programRuleVariables、 程序规则和程序规则操作。 programRule 包含一个 表达式 - 当这个表达式为真时，子程序RuleActions 被触发。 programRuleVariables 用于寻址数据元素， 跟踪实体数据值和运行所需的其他数据值 表达式。一个程序中的所有程序规则共享同一个程序库 programRuleVariables，一个 programRuleVariable 可以用于多个 程序规则的表达式。

程序规则模型详细信息 ¶

下表给出了程序规则的详细概述 模型。

计划规则操作模型详细信息 ¶

下表给出了对 programRuleAction 的详细概述 模型。

ProgramRuleAction Validation ¶

There are certain validations added to ProgramRuleAction model in 2.37. Main purpose was to keep user from creating erroneous ProgramRules in order to keep the database consistent. These validations depends on program rule action type. Each action type has its own respective validation.

Apart from above validations, data field in program rule action which normally contains expression can also be evaluated using below api endpoint.

POST /api/programRuleActions/data/expression/description?programId=<uid>
  "condition": "1 + 1"

程序规则变量模型的详细信息 ¶

下表详细概述了 程序规则变量模型。

创建程序规则 ¶

• To perform crud operations, programRules resource is available in API.

要检索programRules的列表，您可以执行GET请求，如下所示：

/ api / programRules

要检索单个programRule，您可以执行GET请求，如下所示：

/ api / programRules / <program_rule_uid>

要保存/添加单个programRule，您可以执行POST请求，如下所示：

/ api / programRules / <program_rule_uid>

要更新单个programRule，您可以执行如下PUT请求：

/ api / programRules / <program_rule_uid>

要删除单个programRule，您可以执行以下DELETE请求：

/ api / programRules / <program_rule_uid>

要检索programRule条件的描述，可以使用POST并在POST正文中提供条件字符串。

/ api / programRules / condition / description？ <program_rule_uid>

形式 ¶

To retrieve information about a form (which corresponds to a data set and its sections) you can interact with the form resource. The form response is accessible as XML and JSON and will provide information about each section (group) in the form as well as each field in the sections, including labels and identifiers. By supplying period and organisation unit identifiers the form response will be populated with data values.

要检索数据集的表单，您可以执行GET请求，如下所示：

/ api / dataSets / <dataset-id> /form.json

检索具有标识符“BfMAe6Itzgt”的数据集的表单 XML：

/ api / dataSets / BfMAe6Itzgt / form

要检索包含JSON中的元数据的表单，请执行以下操作：

/api/dataSets/BfMAe6Itzgt/form.json?metaData=true

检索填充了特定时期数据值的表单，并 XML 中的组织单位：

/api/dataSets/BfMAe6Itzgt/form.xml?ou=DiszpKrYNg8&pe=201401

当涉及自定义数据输入表单时，此资源还允许 直接为数据集创建此类表单。这可以通过一个 内容类型为 text/html 的 POST 或 PUT 请求，其中有效负载是 自定义表单标记，例如：

curl -d @form.html "localhost/api/dataSets/BfMAe6Itzgt/form"
  -H "Content-Type:text/html" -u admin:district -X PUT

文件资料 ¶

对文件的引用可以与文档资源一起存储。

对文档端点的GET请求将返回所有文档：

/ api / documents

对文档端点的POST请求将创建一个新文档：

curl -X POST -d @document.json -H "Content-type: application/json"
  "http://dhis.domain/api/documents"
  "name": "dhis home",
  "external": true,
  "url": "https://www.dhis2.org"

带有附加文档 ID 的 GET 请求将返回信息 关于文件。对同一端点的 PUT 请求将更新 文档的字段：

/ api / documents / <documentId>

将 /data 附加到 GET 请求将返回实际文件内容 文件的：

/ api / documents / <documentId> / data

CSV元数据导入 ¶

DHIS2支持以CSV格式导入元数据，例如数据元素，组织单位和验证规则。根据列顺序/列索引来标识各种元数据对象的属性（有关详细信息，请参见下文）。您可以省略不需要的对象属性/列，但是由于列顺序很重要，因此必须包括一个空列。换句话说，如果您要指定在列顺序中排在后面的属性/列，但不指定在列顺序中排在较早的位置的某些列，则可以为它们添加空白/空白列。

CSV文件的第一行被视为标题，在导入期间将被忽略。 _comma_字符应用作文本定界符。包含逗号的文本必须放在_双引号_中。

要上传CSV格式的元数据，您可以向元数据端点发出POST请求：

POST / api / metadata？classKey = CLASS-KEY

支持以下对象类型。 classKey 查询参数是强制性的，可以在下表中的每个对象类型旁边找到。

提示

如果使用 curl ，应该使用 --data-binary 选项，因为它保留了换行符和换行符，这对于 CSV 数据是必不可少的。

例如，要使用 curl 上传CSV格式的数据元素文件，可以使用以下命令：

curl --data-binary @data_elements.csv "http://localhost/api/metadata?classKey=DATA_ELEMENT"
  -H "Content-Type:application/csv" -u admin:district

以下各节列出了CSV导入当前支持的对象类型的格式。

资料元素 ¶

下面是数据元素的 CSV 文件示例。首先 行将始终被忽略。请注意如何跳过列并依赖 系统使用的默认值。您还可以跳过列 你不使用出现在右边的

名称，uid，代码，简称，描述
“妇女参加技能发展培训”，“ D0001”，“妇女参加培训”
“妇女参与社区组织”，“ D0002”，“妇女参与组织”

组织单位 ¶

使用父单位导入组织单位的最小示例 看起来像这样：

名称，uid，代码，父项
“西部省份”，“ WESTP”，“ ImspTQPwCqd”
“东部省”，“ EASTP”，“ ImspTQPwCqd”

验证规则 ¶

选项集 ¶

选项集的格式很特殊。前三个值代表 一个选项集。最后三个值代表一个选项。首先 代表选项集的三个值应该对每个值重复 选项。

optionsetname，optionsetuid，optionsetcode，optionname，optionuid，optioncode
“颜色”，“颜色”，“蓝色”，“蓝色”
“颜色”，“颜色”，“绿色”，“绿色”
“颜色”，“颜色”，“黄色”，“黄色”
“性别”，“男”，“男”
“性别”，“女性”，“女性”
“性别”，“未知”，“未知”
“结果”，“高”，“高”
“结果”，“中”，“中”
“结果”，“低”，“低”
“ Impact”，“ cJ82jd8sd32”，“ IMPACT”，“ Great”，“ GREAT”
“影响”，“ cJ82jd8sd32”，“影响”，“中等”，“中等”
“影响”，“ cJ82jd8sd32”，“影响”，“不良”，“不良”

选项组 ¶

OptionGroup CSV有效负载样本

optionGroupName，optionGroupUid，optionGroupCode，optionGroupShortName，optionSetUid，optionUid，optionCode
optionGroupA，groupA，xmRubJIhmaK，OptionA
optionGroupA，groupgroup，xmRubJIhmaK，OptionB
optionGroupB 、、 groupB，QYDAByFgTr1，OptionC

选项组集 ¶

OptionGroupSet CSV有效负载样本

名称，uid，代码，描述，数据维度，选项
optiongroupsetA，...，xmRubJIhmaK
optiongroupsetB 、、、、 false，QYDAByFgTr1

收藏会员 ¶

除了导入对象，您还可以选择只导入对象 对象和组之间的组成员关系。目前，该 支持以下组和对象对

• 组织单位组-组织单位

• 数据元素组-数据元素

• 指标组-指标

• 选项组集-选项组

这些导入的CSV格式相同

其他物件 ¶

类别选项的示例如下所示：

名称，uid，代码，简称
“男”，“男”
“女性”，“女性”

删除的对象 ¶

删除的对象资源提供了元数据对象的日志 删除。

/ api / deletedObjects

每当删除元数据类型的对象时，都会保留日志 uid、代码、类型和删除时间。这个 API 是 在 /api/deletedObjects 字段过滤和对象过滤中可用 与其他元数据资源类似。

获取类型为数据元素的已删除对象：

GET /api/deletedObjects.json?klass=DataElement

获取在 2015 年删除的指标类型的已删除对象和 向前：

GET /api/deletedObjects.json?klass=Indicator&deletedAt=2015-01-01

收藏夹 ¶

某些类型的元数据对象可以标记为收藏夹 当前登录的用户。这目前适用于仪表板。

/ api / dashboards / <uid> /收藏

要使仪表板成为收藏夹，您可以发出 POST 请求（无内容 type required) 到这样的 URL：

/ api /仪表板/ iMnYyBfSxmM /收藏

要将仪表板删除为收藏夹，您可以发出 DELETE 请求 使用与上面相同的 URL。

收藏夹状态将显示为布尔值 收藏夹 字段 元数据响应中的对象（例如仪表板）。

订阅内容 ¶

登录的用户可以订阅某些类型的对象。现在 可订阅对象是 Chart、EventChart、EventReport 类型的对象， 地图、报告表和可视化。

注意

不推荐使用Chart和ReportTable对象。改为使用可视化。

要获取对象的订阅者（返回用户 ID 数组），您 可以发出 GET 请求：

/ api / <object-type> / <object-id> /订阅者

请参见以下示例：

/ api / charts / DkPKc1EUmC2 / subscribers

检查当前用户是否订阅了一个对象（返回一个 boolean) 您可以执行 GET 调用：

/ api / <object-type> / <object-id> /已订阅

请参见以下示例：

/ api / charts / DkPKc1EUmC2 /已订阅

要订阅/取消订阅对象，请执行 POST/DELETE 请求（不需要内容类型）：

/ api / <object-type> / <object-id> / subscriber

文件资源 ¶

文件资源*是用于表示和存储二进制内容的对象。 *FileResource 对象本身包含文件元数据（名称、 内容类型、大小等）以及允许检索 来自数据库外部文件存储的内容。 FileResource 对象 与其他数据库一样存储在数据库中，但内容（文件）是 存储在别处并可使用包含的引用检索 （存储密钥） 。

/ api / fileResources

文件资源的内容不能直接访问，但可以 从其他对象（如数据值）引用来存储二进制 几乎无限大小的内容。

To create a file resource that does not require a corresponding data value, POST to the endpoint /api/fileResources with a multipart upload:

curl "https://server/api/fileResources" -X POST
  -F "file=@/path/to/file/name-of-file.png"

To create both a file resource and a data value that references the file, POST to the /api/dataValues/file endpoint in DHIS 2.36 or later:

curl "https://server/api/dataValues/file?de=xPTAT98T2Jd
  &pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s" -X POST
  -F "file=@/path/to/file/name-of-file.png"

For the api/fileResources endpoint, the only form parameter required is file , which is the file to upload. For the api/dataValues/file endpoint, the parameters required are the same as for a post to api/dataValues , with the addition of file .

The filename and content-type should also be included in the request but will be replaced with defaults when not supplied.

成功创建文件资源后，返回的数据将包含 一个 response 字段，它又包含这样的 fileResource ：

{
  "httpStatus": "Accepted",
  "httpStatusCode": 202,
  "status": "OK",
  "response": {
    "responseType": "FileResource",
    "fileResource": {
      "name": "name-of-file.png",
      "created": "2015-10-16T16:34:20.654+0000",
      "lastUpdated": "2015-10-16T16:34:20.667+0000",
      "externalAccess": false,
      "publicAccess": "--------",
      "user": { ... },
      "displayName": "name-of-file.png",
      "contentType": "image/png",
      "contentLength": 512571,
      "contentMd5": "4e1fc1c3f999e5aa3228d531e4adde58",
      "storageStatus": "PENDING",
      "id": "xm4JwRwke0i"

注意响应是*202 Accepted*，表示返回的 资源已提交后台处理（持续到 在这种情况下是外部文件存储）。另外，请注意 storageStatus 字段 指示内容是否已存储。在这 点，到外部存储的持久化还没有完成（它是 可能会上传到某个地方的基于云的商店） PENDING 状态。

即使内容尚未完全存储，文件资源 现在可以使用，例如作为数据值中的引用内容（参见 使用文件数据值 )。如果我们需要检查 更新的 storageStatus 或以其他方式检索 文件，可以查询 fileResources 端点。

curl "https://server/api/fileResources/xm4JwRwke0i" -H "Accept: application/json"

此请求将返回 FileResource 对象，如 上面例子的反应。

文件资源限制 ¶

• 文件资源*必须*从另一个对象引用（分配） 以便长期坚持。一个文件资源是 创建但未被其他对象（例如数据值）引用 被认为处于*分期*。此中的任何文件资源 状态并且超过*两个小时*将被标记为删除 并将最终从系统中清除。

• 文件资源初始创建返回的ID不是 可从任何其他位置检索，除非文件资源具有 已被引用（其中 ID 将被存储为引用）， 所以丢失它需要重复 POST 请求和一个新的 要创建的对象。 *孤立*文件资源将被清理 自动起来。

• 文件资源对象是*不可变的*，意味着修改不是 允许并需要创建一个全新的资源。

文件资源阻止列表 ¶

出于安全原因，某些类型的文件被阻止上传。

以下内容类型被阻止。

以下文件扩展名被阻止。

元数据版本控制 ¶

This section explains the metadata versioning APIs.

• /api/metadata/version ：这个端点将返回当前的元数据 调用它的系统的版本。

获取元数据版本示例 ¶

**示例：**获取此系统的当前元数据版本

请求：

/ api /元数据/版本

响应：

{
  "name": "Version_4",
  "created": "2016-06-30T06:01:28.684+0000",
  "lastUpdated": "2016-06-30T06:01:28.685+0000",
  "externalAccess": false,
  "displayName": "Version_4",
  "type": "BEST_EFFORT",
  "hashCode": "848bf6edbaf4faeb7d1a1169445357b0",
  "id": "Ayz2AEMB6ry"

**示例：**获取名称为“ Version_2”的版本的详细信息

请求：

/ api / metadata / version？versionName = Version_2

响应：

{
  "name": "Version_2",
  "created": "2016-06-30T05:59:33.238+0000",
  "lastUpdated": "2016-06-30T05:59:33.239+0000",
  "externalAccess": false,
  "displayName": "Version_2",
  "type": "BEST_EFFORT",
  "hashCode": "8050fb1a604e29d5566675c86d02d10b",
  "id": "SaNyhusVxBG"

• /api/metadata/version/history ：这个端点将返回所有 调用它的系统的元数据版本。

获取所有元数据版本的列表 ¶

**示例：**获取此系统中所有版本的列表

请求：

/ api /元数据/版本/历史记录

响应：

{
  "metadataversions": [{
    "name": "Version_1",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T05:54:41.139+0000",
    "id": "SjnhUp6r4hG",
    "hashCode": "fd1398ff7ec9fcfd5b59d523c8680798"
  }, {
    "name": "Version_2",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T05:59:33.238+0000",
    "id": "SaNyhusVxBG",
    "hashCode": "8050fb1a604e29d5566675c86d02d10b"
  }, {
    "name": "Version_3",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T06:01:23.680+0000",
    "id": "FVkGzSjAAYg",
    "hashCode": "70b779ea448b0da23d8ae0bd59af6333"

**示例：**获取此系统在“ Version_2”之后创建的所有版本的列表

请求：

/ api / metadata / version / history？baseline = Version_2

响应：

{
  "metadataversions": [{
    "name": "Version_3"




    
,
    "type": "BEST_EFFORT",
    "created": "2016-06-30T06:01:23.680+0000",
    "id": "FVkGzSjAAYg",
    "hashCode": "70b779ea448b0da23d8ae0bd59af6333"
  }, {
    "name": "Version_4",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T06:01:28.684+0000",
    "id": "Ayz2AEMB6ry",
    "hashCode": "848bf6edbaf4faeb7d1a1169445357b0"

• /api/metadata/version/create ：这个端点将创建元数据 version 参数中指定的版本类型。

用户可以选择需要创建的元数据类型。 元数据版本类型决定了进口商应该如何对待给定的 版本。导入元数据时将使用此类型。有 两种类型的元数据。

• BEST_EFFORT ：这种类型表明丢失的引用可以 忽略，导入器可以继续导入元数据（例如 数据元素组导入中缺少数据元素）。

• ATOMIC ：这种类型确保对元数据进行严格的类型检查 如果有任何引用，则引用和元数据导入将失败 不存在。

注意

建议有一个 ATOMIC 类型的版本，以确保所有 系统（中央和本地）具有相同的元数据。任何遗漏 引用在验证阶段本身被捕获。请参阅 进口商详细信息的完整解释。

创建元数据版本 ¶

示例： 创建类型为 BEST_EFFORT 的元数据版本

请求：

curl -X POST -u admin:district "https://play.dhis2.org/dev/api/metadata/version/create?type=BEST_EFFORT"

响应：

{
  "name": "Version_1",
  "created": "2016-06-30T05:54:41.139+0000",
  "lastUpdated": "2016-06-30T05:54:41.333+0000",
  "externalAccess": false,
  "publicAccess": "--------",
  "user": {
    "name": "John Traore",
    "created": "2013-04-18T17:15:08.407+0000",
    "lastUpdated": "2016-04-06T00:06:06.571+0000",
    "externalAccess": false,
    "displayName": "John Traore",
    "id": "xE7jOejl9FI"
  "displayName": "Version_1",
  "type": "BEST_EFFORT",
  "hashCode": "fd1398ff7ec9fcfd5b59d523c8680798",
  "id": "SjnhUp6r4hG"

• /api/metadata/version/{versionName}/data ：这个端点将下载 特定于作为路径传递的版本名称的实际元数据 范围。

• /api/metadata/version/{versionName}/data.gz ：这个端点将下载 特定于作为路径传递的版本名称的实际元数据 压缩格式（gzipped）的参数。

下载版本元数据 ¶

**示例：**获取“版本5”的实际元数据

请求：

curl -u admin:district "https://play.dhis2.org/dev/api/metadata/version/Version_5/data"

响应：

{
  "date": "2016-06-30T06:10:23.120+0000",
  "dataElements": [
      "code": "ANC 5th Visit",
      "created": "2016-06-30T06:10:09.870+0000",
      "lastUpdated": "2016-06-30T06:10:09.870+0000",
      "name": "ANC 5th Visit",
      "id": "sCuZKDsix7Y",
      "shortName": "ANC 5th Visit ",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "zeroIsSignificant": false,
      "valueType": "NUMBER",
      "categoryCombo": {
        "id": "p0KPaWEg3cf"
      "user": {
        "id": "xE7jOejl9FI"

元数据同步 ¶

本节介绍了可用的元数据同步 API 2.24 开始

• /api/metadata/sync ：此端点执行元数据同步 通过下载和在查询参数中传递的版本名称 从远程服务器导入指定的版本，如定义 设置应用程序。

• 使用此 API 时应格外小心。请注意，有 以完全自动化的方式实现同步的另一种方法 利用“数据管理”中的元数据同步任务 应用程序。详见用户手册第 22 章 22.17 节 关于元数据同步任务。

• 此同步 API 也可用于同步元数据 从元数据同步调度程序失败的版本。由于 它依赖于给定的元数据版本号，应该注意 为调用 this 的顺序而采用。例如。如果这个api是 用于从中央实例同步一些更高版本，然后 同步可能会失败，因为元数据依赖项不存在于 本地实例。

• 假设本地实例在 Version_12 并且如果使用这个端点 从中央同步 Version_15 （类型 BEST_EFFORT ） 例如，调度程序将从以下位置开始同步元数据 版本_16 。所以本地实例不会有元数据 Version_12 和 Version_15 之间的版本。你需要手动 仅使用这些端点同步丢失的版本。

同步元数据版本 ¶

**示例：**将Version_6从中央系统同步到该系统

请求：

curl -u admin:district "https://play.dhis2.org/dev/api/metadata/sync?versionName=Version_6"

元数据存储库 ¶

DHIS2 提供了一个包含元数据包的元数据存储库 各种内容。元数据包是符合 DHIS2 的 JSON 文档 它描述了一组元数据对象。

要检索可用元数据包的索引，您可以发出 对 metadataRepo 资源的 GET 请求：

GET /api/synchronization/metadataRepo

元数据包条目包含有关包的信息和 相关包的 URL。索引可能如下所示：

{
  "packages": [
      "id": "sierre-leone-demo",
      "name": "Sierra Leone demo",
      "description": "Sierra Leone demo database",
      "version": "0.1",
      "href": "https://dhis2.org/metadata-repo/221/sierra-leone-demo/metadata.json"
      "id": "trainingland-org-units",
      "name": "Trainingland organisation units",
      "description": "Trainingland organisation units with four levels",
      "version": "0.1",
      "href": "https://dhis2.org/metadata-repo/221/trainingland-org-units/metadata.json"

客户端可以通过 URL 安装元数据包 带有元数据包的内容类型 text/plain 的 POST 请求 URL 作为 metadataPull 资源的有效负载：

POST / api / synchronization / metadataPull

curl命令示例如下所示：

curl "localhost:8080/api/synchronization/metadataPull" -X POST
  -d "https://dhis2.org/metadata-repo/221/trainingland-org-units/metadata.json"
  -H "Content-Type:text/plain" -u admin:district

Reference to createdBy User ¶

Each object created in DHIS2 will have a property named user which is linked to User who created the object.

From version 2.36 we have changed the name of this property to createdBy to avoid confusion.

However, in order to keep the backwards compability, the legacy user property is still included in the payload and works normally as before.

{
  "createdBy": {
      "displayName": "John Kamara",
      "name": "John Kamara",
      "id": "N3PZBUlN8vq",
      "username": "district"
  "user": {
      "displayName": "John Kamara",
      "name": "John Kamara",
      "id": "N3PZBUlN8vq",
      "username": "district"

Metadata Proposal Workflow ¶

The metadata proposal workflow endpoint allows for a workflow of proposing and accepting changes to metadata.

/api/metadata/proposals

Propose a metadata change ¶

A proposal always targets a single metadata object using:

POST /api/metadata/proposals

Depending on the payload the proposal could:

• Add a new metadata object.
• Update an existing metadata object references by ID.
• Remove an existing metadata object referenced by ID.

To propose adding a new metadata object send a JSON payload like the following:

{
  "type": "ADD",
  "target": "ORGANISATION_UNIT",
  "change": {"name":"My Unit", "shortName":"MyOU", "openingDate": "2020-01-01"}

To propose updating an existing metadata object send a JSON payload like in the below example:

{
  "type": "UPDATE",
  "target": "ORGANISATION_UNIT",
  "targetId": "<id>",
  "change": [
    { "op": "replace", "path": "/name", "value": "New name" }

To propose the removal of an existing object send a payload like in the last example:

{
  "type": "REMOVE",
  "target": "ORGANISATION_UNIT",
  "targetId": "<id>"

Only target type ORGANISATION_UNIT is supported currently.

Accept a metadata change proposal ¶

要接受一个开放的提案，请在提案资源上使用 POST

POST /api/metadata/proposals/<uid>

成功后，提案的状态变为 接受 状态。一旦被接受，提案就不能再被拒绝。

Should a proposal fail to apply it changes to status NEEDS_UPDATE . The reason field contains a summary of the failures when this information is available.

Oppose a metadata change proposal ¶

如果提案不太正确并且需要调整，可以通过发送提案资源的 PATCH 来反对提案

PATCH /api/metadata/proposals/<uid>

可选地，可以在其中添加纯文本正文，以给出提案遭到反对的 原因 。

反对的提案必须处于 PROPOSED 状态，并将更改为 NEEDS_UPDATE 状态。

Adjust a metadata change proposal ¶

A proposal in state NEEDS_UPDATE needs to be adjusted before it can be accepted. To adjust the proposal a PUT request is made for the proposal's resource

PUT /api/metadata/proposals/<uid>

Such an adjustment can either be made without a body or with a JSON body containing an object with the updated change and targetId for the adjustment:

{
  "targetId": "<id>",
  "change": ...

Reject a metadata change proposal ¶

要拒绝打开的提案，请在提案资源上使用 DELETE

DELETE /api/metadata/proposals/<uid>