追踪器¶

注意事项

跟踪器已在 DHIS2 2.36 中重新实现。本文件介绍了新的跟踪器端点

POST /api/tracker GET /api/tracker/trackedEntities > * GET /api/tracker/trackedEntities GET /api/tracker/enrollments > * GET /api/tracker/enrollments * GET /api/tracker/events ª * `GET /api/tracker/relationships

跟踪器 已废弃）] > 描述了已废弃的(https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-master/tracker-deprecated.html) 描述了已废弃的端点

GET/POST/PUT/DELETE /api/trackedEntityInstance > * GET/POST/PUT/DELETE /api/enrollments GET/POST/PUT/DELETE /api/enrollments > * GET/POST/PUT/DELETE /api/enrollments * GET/POST/PUT/DELETE /api/events. * GET/POST/PUT/DELETE /api/relationships.

过时的端点将在 42 版本中删除！

迁移到新的跟踪器 端点](https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-master/tracker-deprecated.html#webapi_tracker_migration) 应该能帮助你开始迁移。如果您在实践社区 实践社区 上寻求帮助。

跟踪对象{ #webapi_nti_tracker_objects }¶

通过此资源插入的 JavaScript 和 CSS 内容将由 DHIS2 网络应用项目。这在某些情况下特别有用:

跟踪实体{ #tracked-entities }¶

跟踪实体是跟踪器模型的根对象。

See Attribute

注册{ #enrollments }¶

被跟踪实体 "可以注册其有资格参与的 "计划"。被跟踪实体 只要计划配置了与被跟踪实体相同的 "被跟踪实体类型"，被跟踪实体就有资格 实体。我们在本节中将用 "注册 "对象来表示注册。

See Attribute

大事记¶

A list of events owned by the enrollment.

在 API 中，最大的区别在于所有事件要么连接到相同的注册（"事件程序"），要么连接到不同的注册（"跟踪程序"）。 事件程序"）或不同的程序（"跟踪程序"）。下表将 指出这两者之间的任何特殊情况。

人际关系¶

dataValues

注

关系项 "代表一个对象的链接。由于 Relationship 可以是任何 跟踪实体"、"注册 "和 "事件 "等跟踪器对象，因此其值取决于 关系类型例如，如果关系类型从事件连接到`跟踪的 实体"，格式就是严格的：

``json { "来自"：{ "event"：{ "event"："abcdef12345" } }, "to"：{ "trackedEntity"：{ "trackedEntity"："fedcba12345" } } } ```

属性¶

属性 "是描述 "跟踪实体 "的实际值。它们可以通过 跟踪实体类型 "或 "程序"。这隐含地意味着，属性 既可以是跟踪实体的一部分，也可以是注册表的一部分。 跟踪实体 "和 "注册 "的一部分。

注

添加数据时，"属性 "只需要 "属性 "和 "值 "属性。 值 "可以为空，这意味着用户应删除该值。

在跟踪器对象的上下文中，我们将 "跟踪实体属性 "和 "跟踪实体 属性值 "称为 "属性"。然而，属性也是自己的东西，与 元数据。因此，将跟踪实体属性和元数据属性分开至关重要。在 跟踪器 API 中，可以在指定 "idScheme "时引用元数据属性（更多信息请参阅 更多信息请参阅 > 请求参数）。

数据值{ #data-values }¶

属性 "描述的是 "跟踪实体 "或 "注册"，而 "数据值 "描述的是 "事件"。主要区别在于，对于给定的 "跟踪实体"，"属性 "只能有一个值。相比之下，"数据值 "在不同的 "事件 "中可以有许多不同的值，即使这些 "事件 "都属于同一个 "注册 "或 "跟踪实体"。

注

添加数据时，"数据元素 "只需要 "dataElement "和 "value "属性。 值 "可以为空，这意味着用户应删除该值。

笔记¶

DHIS2 追踪器允许使用数据元素和追踪实体属性捕获数据。 但是，有时可能需要记录更多信息或对当前问题的评论。 或对当前问题的评论。此类附加信息可使用注释来捕获。 注释等同于 DHIS2 聚合系统中的数据值注释。

备注分为两类：在事件级别记录的备注和在注册级别记录的备注。 记录。一个注册可以有一个或多个事件。关于每个事件的注释 例如，为什么某个事件错过了、重新安排了，或者为什么只填写了几个数据元素等。 等等，都可以用事件注释来记录。注册中的每个事件都可以有自己的 故事/笔记。然后，我们可以使用 父注册笔记。入学记录也有助于记录，例如，为什么取消入学。 取消注册的原因。何时以及如何使用注释取决于用户的想象力和使用情况。

注册和活动都可以根据需要添加注释，没有数量限制。但是 删除或更新。它们就像一本日志。如果要修改 要修改备注，可以创建另一个备注。删除备注的唯一方法是删除备注的 父对象--事件或注册。

注释没有自己的专用端点；它们作为父事件和/或注册有效载荷的一部分进行交换。 和/或注册有效载荷的一部分。下面是一个有效载荷示例。

``json { "trackedEntity"："oi3PMIGYJH8"、 "注册"：[ { "enrollment"："EbRsJr8LSSO"、 "笔记"：[ { "note"："vxmCvYcPdaW"、 "值"："入学说明 2"。 }, { "值"："注册说明 1" } ], "事件"：[ { "event"："zfzS9WeO0uM"、 "备注"：[ { "note"："MAQFb7fAggS"、 "值"："事件注释 1"。 }, { "值"："事件备注 2"。 } ] } ] } ] }

| 指标组 | 描述 | 需要 | 是的 | 类型 | 例 |
|---|---|---|---|---|---|
| updatedBy | Only for reading data. User that last updated the object. Set on the server. | 不 | 是的 | String:Uid | ABCDEF12345 |
| 价值 | 笔记 | 是的 | 是的 | 不 | Notes do not have a dedicated endpoint; they are exchanged as part of the parent event and/or
enrollment payload. A sample payload is found below. |
| ```json
{
  "trackedEntity": "oi3PMIGYJH8",
  "enrollments": [
    {
      "enrollment": "EbRsJr8LSSO",
      "notes": [
        {
          "note": "vxmCvYcPdaW",
          "value": "Enrollment note 1"
        },
        {
          "value": "Enrollment note 2."
        }
      ],
      "events": [
        {
          "event": "zfzS9WeO0uM",
          "notes": [
            {
              "note": "MAQFb7fAggS",
              "value": "Event Note 1."
            },
            {
              "value": "Event Note 2."
            }
          ]
        }
      ]
    }
  ]
}
``` | Property | 不 | 是的 | Date:ISO 8601 | YYYY-MM-DDThh:mm:ss |
| 日期时间 | 用于标识存储/创建该笔记的客户端的引用。在服务器端设置。 | 不 | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 不 | Boolean |
|     GET /api/metadata/proposals/ | 仅用于读取数据。创建对象的用户。在服务器上设置 | 不 | 是的 | 用户 | String:Any |

### 用户数 { #users } 

| 指标组 | 描述 | 需要 | 是的 | 类型 | 例 |
|---|---|---|---|---|---|
| storedByDataValue | Client reference for who stored/created the note. | 不 | 是的 | String:Uid | ABCDEF12345 |
| 用户名 | Only for reading data. User that created the object. Set on the server. | 不 | 是的 | 不 | 123 |
| {<br>"uid": "ABCDEF12345",<br>"username": "username",<br>"firstName": "John",<br>"surname": "Doe"<br>} | Users | 不 | 是的 | 不 | Immutable |
| 类型 | 例 | 不 | 是的 | 不 | 是的 |

> 必须提供 `uid` 或 `username` 字段中的一个。如果两个都提供，则只考虑用户名。
> 考虑。

### 计划阶段工作清单{ #webapi_working_list_filters }

采集应用程序中的节目阶段工作列表功能旨在显示与特定节目阶段相关的预设工作列表。
与特定程序阶段相关的预设工作清单。该功能使
用户保存与程序阶段相关的筛选器和排序首选项，从而便于组织和管理他们的工作流程。
工作流程的组织和管理。要与它们交互，您需要使用
/api/programStageWorkingLists*资源。这些列表可以共享，并遵循与其他元数据相同的共享模式。
模式。使用 */api/sharing* 时，类型参数将为
*程序阶段工作列表*。

    /api/40/programStageWorkingLists

##### 将 CRUD 操作的有效载荷转入项目阶段工作列表{ #payload-on-crud-operations-to-program-stage-working-lists } 

上述端点可用于获取所有程序阶段的工作列表。要获取单个列表，只需在
即可。如果要删除，也是一样。
另一方面，如果要创建或更新程序阶段工作列表，除了上述的
端点外，还需要提供以下格式的有效载荷：

"assignedUsers":["DXyJmlo9rge"]

| Table: Period filter definition | 描述 | 例 |
|---|---|---|
| 名称 | periodFrom ||
| 描述 | Protected ||
| 项目 | 包含项目 ID 的对象。必须填写。 | {"id" : "uy2gU8kTjF"} |
| 项目阶段 | 包含项目阶段 ID 的对象。必须填写。 | {"id" : "oRySG82BKE6"} |
| 项目阶段查询标准 | 代表各种可能过滤值的对象。请参阅下面的*项目阶段查询标准*定义表。

| Payload | 描述 | 例 |
|---|---|---|
| 用户友好型消息,说明操作是否成功。 | 事件状态。可能的值是 "活动"、"已完成"、"已访问"、"已安排"、"逾期"、"已跳过 "和 "已访问"。 | "状态": "已访问 |
| Name of the working list. Required. | DateFilterPeriod 对象，根据事件创建日期进行过滤。 | {"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"} |
| If not otherwise specified, JSON is the default response for the `GET` method. The API also 
supports CSV export for single and collection endpoints. Furthermore, it supports compressed 
JSON and CSV for the collection endpoint. | DateFilterPeriod 对象，根据事件计划日期进行过滤。 | {"类型"："相对"，"期间"："今天"}。 |
| DateTime | 任何有效的 ProgramStatus。可能的值有 "激活"、"已完成 "和 "已取消"。 | "enrollmentStatus"（注册状态）："已完成" |
| 跟进 | Criteria values | "followUp":true |
| 例 | DateFilterPeriod 对象，根据事件注册日期进行过滤。 | "enrolledAt"：{"type": "RELATIVE", "period": "THIS_MONTH"}。 |
| `"status":"VISITED"` | DateFilterPeriod 对象，根据事件发生日期进行过滤。 | {"类型": "相对", "周期": "本月"} } |
| orgUnit | eventOccurredAt | "orgUnit"："Rp268JB6Ne4" |
| `{"type":"RELATIVE","period":"TODAY"}` | eventScheduledAt | "项目":"a3kGcGDCuk6" |
| Enum | 事件的有效用户选择模式。可能的值有 CURRENT、PROVIDED、NONE、ANY 和 ALL。如果是 PROVIDED（或空），则预期有效负载中的分配用户为非空。 | Any valid EnrollmentStatus. Options are `ACTIVE`, `COMPLETED` and `CANCELLED`. |
| Property | 事件的指定用户列表。与上述 PROVIDED assignedUserMode 一起使用。 | Indicates whether to filter enrollments marked for follow up or not |
| iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。 | enrolledAt | [DateFilterPeriod](#webapi_tracker_workinglists_common_objects) object filtering based on the event enrollment date. |
| `"enrolledAt": {"type":"RELATIVE","period":"THIS_MONTH"}` | enrollmentOccurredAt | [DateFilterPeriod](#webapi_tracker_workinglists_common_objects) object filtering based on the event occurred date. |
| `{"type":"RELATIVE","period":"THIS_MONTH"}` | orgUnit | A valid organisation unit UID |
| A description of the working list. | ouMode | A valid OU selection mode |

请看下面的有效载荷示例：

``json
{
    "name": "Test WL"、
    "program":{"id":"uy2gU8kT1jF"},
    "programStage":{"id":"oRySG82BKE6"},
    "描述"："测试 WL 定义"、
    "programStageQueryCriteria"：
        {
            "status": "VISITED"、
            "eventCreatedAt":{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"},
            "scheduledAt"：{"类型"："相对"，"期间"："今日"}、
            "enrollmentStatus"："COMPLETED"、
            "followUp" : true、
            "enrolledAt"：{"type": "RELATIVE", "period": "THIS_MONTH"}、
            "enrollmentOccurredAt"：{"类型"："相对"，"期间"："THIS_MONTH"}、
            "orgUnit"："Rp268JB6Ne4"、
            "ouMode"："SELECTED"、
            "assignedUserMode": "PROVIDED"、
            "assignedUsers":["DXyJmlo9rge"]、
            "订单"："w75KJ2mc4zz:asc"、
            "displayColumnOrder":["w75KJ2mc4zz", "zDhUuAYrxNC"]、
            "dataFilters":[{
                "dataItem"："GXNUsigphqK"、
                "ge"："10",
                "le"："20"
            }],
            "attributeValueFilters":[{
                "attribute"："ruQQnf6rswq"、
                "eq"："15"
            }]
        }
}

Tracker Import (POST /api/tracker)¶

POST /api/tracker` 端点允许客户端导入以下跟踪器对象

• 跟踪实体
• 入学人数
• 活动
• 关系
• 嵌入其他[跟踪器对象]的数据（#webapi_nti_tracker_objects）

请求参数{ #request-parameters }¶

目前，跟踪器导入端点支持以下参数：

注意：idScheme 及其元数据特定 idScheme 参数，如 orgUnitIdScheme、programIdScheme......用于允许和使用默认的 AUTO。 AUTO已被删除。默认 idScheme 已为UID。任何 idScheme "AUTO "发送的请求将与之前的行为相同，即使用 "UID 使用UID`进行匹配。

扁平和嵌套有效载荷{ #flat-and-nested-payloads }¶

导入器支持平面和嵌套有效载荷。

** 平坦部**

扁平有效载荷可包含每个核心跟踪器对象的集合。 ：顶层。这可以与已经分配了 UID 的现有数据无缝配合。但是 对于新数据，客户端必须为对象之间的任何引用提供新的 UID。例如 例如，如果您导入一个新的跟踪实体，该跟踪实体需要 客户需提供一个 UID，以便将注册与该 UID 相链接。

嵌套

嵌套有效载荷是最常用的结构。在这里，跟踪器对象被嵌入到 ：它们的父对象。例如，跟踪实体中的注册。这种 这种结构的优点是，客户端无需为这些引用提供 UID，因为这将自动完成。 自动完成。

注意

虽然嵌套的有效载荷可能会让客户端更容易处理，但有效载荷总是会在导入之前被 在导入前将其扁平化。这意味着，对于大型导入，提供扁平结构的 有效载荷将为导入过程本身提供更多控制和更低的开销。

下面列出了**FLAT**和**NESTED**版本有效载荷的示例。

***扁平***有效载荷{ #flat-payload }¶

false

NESTED 有效载荷{ #nested-payload }¶

true, false

SYNC 和 ASYNC{ #sync-and-async }¶

对用户来说，同步导入与异步导入的主要区别在于 API 的即时响应。对于同步导入，响应将在导入完成后立即返回，并附带 importSummary。 导入完成后就会返回导入摘要（importSummary）。但是，对于异步导入，响应将 将是即时的，并包含一个客户端可以轮询导入更新的引用。

对于重要的导入，客户端使用异步导入可能会有好处，以避免等待响应的时间过长。 避免长时间等待响应。

ASYNC 响应示例如下。关于 SYNC 响应，请查看 importSummary 部分。

FULL, FAIL_FAST, SKIP

CSV 导入{ #csv-import }¶

要使用 CSV 导入事件，请使用 CSV 主体文件并将 "Content-Type "设置为 "POST "请求 application/csv 或 text/csv.

大事记¶

The following updates one of the data values of an event:

CSV PAYLOAD 示例{ #csv-payload-example }¶

{
  "events": [
    {
      "event": "ZwwuwNp6gVd",
      "dataValues": [
        {
          "dataElement": "bx6fsa0t90x",
          "value": "true"
        }
      ],
      "attributeOptionCombo": "HllvX50cXC0",
      "attributeCategoryOptions": "xYerKDKCefk",
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "occurredAt": "2019-08-01T00:00:00.000",
      "orgUnit": "y77LiPqLMoq",
      "program": "IpHINAT79UW",
      "programStage": "A03MvHHogjR",
      "scheduledAt": "2019-08-19T13:59:13.688",
      "status": "ACTIVE",
      "trackedEntity": "Kj6vYde4LHh"
    }
  ]
}

事件,状态,项目,项目阶段,报名情况,组织单位,发生时间,计划时间,几何信息,纬度,经度,后续处理,已删除,创建时间,客户端创建时间,更新时间,客户端更新时间,完成人,完成时间,更新人,属性选项组合,属性类别选项,指派用户,数据元素,值,存储数据值,更新数据值,创建数据值
A7rzcnZTe2T,ACTIVE,eBAyeGv0exc,Zj7UnCAulEk,RiLEKhWHlxZ,DwpbWkiqjMy,2023-02-12T23:00:00Z,2023-02-12T23:00:00Z,"POINT (-11.468912037323042 7.515913998868316)",7.515913998868316,-11.468912037323042,false,false,2017-09-08T19:40:22Z,,2017-09-08T19:40:22Z,,,,,HllvX50cXC0,xYerKDKCefk,,F3ogKBuviRA,"[-11.4880220438585,7.50978830548003]",false,,2016-12-06T17:22:34.438Z,2016-12-06T17:22:34.438Z

The following deletes one of the data values of an event:

导入摘要{ #webapi_nti_import_summary }¶

{
  "events": [
    {
      "event": "ZwwuwNp6gVd",
      "dataValues": [
        {
          "dataElement": "bx6fsa0t90x",
          "value": null
        }
      ],
      "attributeOptionCombo": "HllvX50cXC0",
      "attributeCategoryOptions": "xYerKDKCefk",
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "occurredAt": "2019-08-01T00:00:00.000",
      "orgUnit": "y77LiPqLMoq",
      "program": "IpHINAT79UW",
      "programStage": "A03MvHHogjR",
      "scheduledAt": "2019-08-19T13:59:13.688",
      "status": "ACTIVE",
      "trackedEntity": "Kj6vYde4LHh"
    }
  ]
}

注

这些端点依赖于应用项目内存中存储的信息。这意味着信息 在某些情况下，如应用项目重启或大量 导入请求。

Make a POST to /api/tracker with importStrategy set to DELETE. The payload should include only the UIDs of the trackedEntities, enrollments, events or relationships you wish to delete.

GET /tracker/jobs/{uid}

请求* 示例{ #request-example }¶

GET /tracker/jobs/PQK63sMwjQp.

****回复****示例{ #response-example }¶

``json [ { "uid"："PQK63sMwjQp"、 "level"："INFO"、 "category"："tracker_import_job"、 "时间"： "2024-03-19T13:18:16.3"2024-03-19T13:18:16.370", "消息"："导入完成，状态为 OK，创建 0 个，更新 0 个，删除 0 个，忽略 0 个"、 "完成": true、 "id"："PQK63sMwjQp" }, { "uid"："XIfTJ1UUNcd"、 "level"："INFO"、 类别"tracker_import_job"、 "时间"： "2024-03-19T13:18:16.36"2024-03-19T13:18:16.369", "消息"："PostCommit"PostCommit"、 "completed": false、 "id"："XIfTJ1UUNcd" }, { "uid"："uCG4FNJLLBJ"、 "级别"："INFO"、 "category"："tracker_import_job"、 "时间"： "2024-03-19T13:18:16.3"2024-03-19T13:18:16.364", "信息"： "Commit Transaction"提交事务"、 "completed": false、 "id"："uCG4FNJLLBJ" }, { "uid"："xfOUv2Lk2MC"、 "level"："INFO"、 类别"tracker_import_job"、 "时间"： "2024-03-19T13:18:16.361"2024-03-19T13:18:16.361", "信息"： "Running Rule Engine Validation"（运行规则引擎验证"运行规则引擎验证"、 "completed": false、 "id"："xfOUv2Lk2MC" }. }, { "uid"："cSPfA776obb"、 "level"："INFO"、 类别"tracker_import_job"、 "时间"： "2024-03-19T13:18:16.325"："2024-03-19T13:18:16.325", "消息"："正在运行规则引擎"运行规则引擎"、 "completed": false、 "id"："cSPfA776obb }, { "uid"："mru3HJrFGKA"、 "level"："INFO"、 "category"："tracker_import_job"、 "时间"： "2024-03-19T13:18:16.31"2024-03-19T13:18:16.313", "信息"： "Running Validation"运行验证"、 "completed": false、 "id"："mru3HJrFGKA" }, { "uid"："oTbCUJ2RnA6"、 "level"："INFO"、 "类别"： "tracker_import_job"tracker_import_job"、 "时间"："2024-03-19T13:18:16.312", "信息"： "Running PreProcess"运行预处理"、 "completed": false、 "id"："oTbCUJ2RnA6" }, { "uid"："lcUNbWTn6uh"、 "level"："INFO"、 "类别"： "tracker_import_job"tracker_import_job"、 "时间"： "2024-03-19T13:18:16.312"2024-03-19T13:18:16.312", "消息"："计算有效载荷大小"计算有效载荷大小"、 "completed": false、 "id"："lcUNbWTn6uh" }, { "uid"："l4jQiSS9qdK"、 "level"："INFO"、 "类别"："tracker_import_job"、 "时间"："2024-03-19T13:18:15.903", "信息"： "Running PreHeat"（运行预热"Running PreHeat"、 "completed": false、 "id"："l4jQiSS9qdK" }, { "uid"："qGbiuqgwPX5"、 "level"："INFO"、 "类别"： "tracker_import_job"tracker_import_job"、 "时间"： "2024-03-19T13:18:15.8"2024-03-19T13:18:15.850", "消息"："加载文件内容"加载文件内容"、 "completed": false、 "id"："qGbiuqgwPX5" }, { "uid"："eWNHzVf7iAj"、 "level"："INFO"、 "category"："tracker_import_job"、 "时间"： "2024-03-19T13:18:15.8"2024-03-19T13:18:15.838", "消息"："正在加载文件资源"加载文件资源"、 "completed": false、 "id"："eWNHzVf7iAj" }. }, { "uid"："t9gOjotekQt"、 "level"："INFO"、 "类别"："tracker_import_job"、 "时间"： "2024-03-19T13:18:15.837"2024-03-19T13:18:15.837", "message":"Tracker import started"、 "completed": false、 "dataType"："PARAMETERS"、 "data"：{ "userId"："xE7jOejl9FI"、 "importMode"："VALIDATE"、 "idSchemes"：{ "dataElementIdScheme"：{ "idScheme"："UID"、 "attributeUid": null }, "orgUnitIdScheme"：{ "idScheme"："UID"、 "attributeUid": null }, "programIdScheme"：{ "idScheme"："UID"、 "attributeUid": null }, "programStageIdScheme"：{ "idScheme"："UID"、 "attributeUid": null }, "idScheme"：{ "idScheme"："UID"、 "attributeUid": null }, "categoryOptionComboIdScheme"：{ "idScheme"："UID"、 "attributeUid": null }, "categoryOptionIdScheme"：{ "idScheme"："UID"、 "attributeUid": null } }, "导入策略"create_and_update"、 "atomicMode"："ALL"、 "flushMode"："AUTO"、 "验证模式"FULL"、 "skipPatternValidation": false、 "skipSideEffects": false、 skipSideEffects": false, "skipRuleEngine": false、 "filename": null、 "报告模式"ERRORS" （错误 }, "id"："t9gOjotekQt" } ]

CSV payload example

`GET /tracker/jobs/{uid}/report`

| 默认值|描述|例
|---|---|---|
|`fields`|现有跟踪器导入任务的 UID。|ABCDEF12345|
|报告模式|报告的详细程度。|`FULL`|`ERRORS`|`WARNINGS`|

#### ***请求**** 示例{ #request-example } 

`GET /tracker/jobs/mEfEaFSCKCC/report`.

#### ****回复****示例{ #response-example } 

eAjkbUGBcZ5

Request example

### 导入摘要结构{ #import-summary-structure } 

Response example

```json
[
  {
    "uid": "PQK63sMwjQp",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.370",
    "message": "Import complete with status OK, 0 created, 0 updated, 0 deleted, 0 ignored",
    "completed": true,
    "id": "PQK63sMwjQp"
  },
  {
    "uid": "XIfTJ1UUNcd",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.369",
    "message": "PostCommit",
    "completed": false,
    "id": "XIfTJ1UUNcd"
  },
  {
    "uid": "uCG4FNJLLBJ",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.364",
    "message": "Commit Transaction",
    "completed": false,
    "id": "uCG4FNJLLBJ"
  },
  {
    "uid": "xfOUv2Lk2MC",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.361",
    "message": "Running Rule Engine Validation",
    "completed": false,
    "id": "xfOUv2Lk2MC"
  },
  {
    "uid": "cSPfA776obb",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.325",
    "message": "Running Rule Engine",
    "completed": false,
    "id": "cSPfA776obb"
  },
  {
    "uid": "t9gOjotekQt",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:15.837",
    "message": "Tracker import started",
    "completed": false,
    "dataType": "PARAMETERS",
    "data": {
      "userId": "xE7jOejl9FI",
      "importMode": "VALIDATE",
      "idSchemes": {
        "dataElementIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "orgUnitIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "programIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "programStageIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "idScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "categoryOptionComboIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "categoryOptionIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        }
      },
      "importStrategy": "CREATE_AND_UPDATE",
      "atomicMode": "ALL",
      "flushMode": "AUTO",
      "validationMode": "FULL",
      "skipPatternValidation": false,
      "skipSideEffects": false,
      "skipRuleEngine": false,
      "filename": null,
      "reportMode": "ERRORS"
    },
    "id": "t9gOjotekQt"
  }
]

状态*

GET /tracker/jobs/{uid}/report

Parameter

描述

验证报告*

path /{uid}

ID of an existing tracker import job.

{
  "validationReport": {
    "errorReports": [
      {
        "message": "Could not find TrackedEntityType: `Q9GufDoplCL`.",
        "errorCode": "E1005",
        "trackerType": "TRACKED_ENTITY",
        "uid": "Kj6vYde4LHh"
      },
      ...
    ],
    "warningReports" : [ ... ]
  }
}

报告包含一条信息和一个描述实际错误的代码（有关错误信息，请参阅 错误代码 部分。 代码](#error-codes) 部分了解有关错误的更多信息）。此外，报告还包括 trackerType "和 "uid"，旨在描述错误发生在数据的哪个位置。在此 在本例中，有一个 uid 为 Kj6vYde4LHh 的 TRACKED_ENTITY ，其中引用了一个未找到的跟踪实体类型。 实体类型的引用。

注

当引用跟踪器对象的 uid 时，它们在 有效载荷。例如，被跟踪实体的 uid 在有效载荷中的名称是 跟踪实体"。注册"、"事件 "和 "关系 "也是如此、 事件和关系。

如果有效载荷中没有提供 uid，导入过程将生成新的 uid。这意味着 错误报告可能会引用一个不存在于有效负载中的 uid。

错误代表有效载荷中存在导入项目无法规避的问题。任何错误都会 阻止数据导入。另一方面，警告是指可以安全规避的问题。 但应让用户知道发生了这种情况。警告不会阻止数据 无法导入。

统计*

统计信息提供了导入的快速概览。导入完成后，这些将是 实际计数，表示创建、更新、删除或忽略了多少数据。

例：

{
  "stats": {
    "created": 2,
    "updated": 2,
    "deleted": 1,
    "ignored": 5,
    "total": 10
  }
}

created 指创建了多少个新对象。一般来说，有效负载中没有 uid 将被视为新对象。

updated 指更新对象的数量。如果一个对象的有效载荷中设置了 uid，那么只要数据库中存在相同的 uid，它 将被视为更新，只要数据库中存在相同的 uid。

deleted "指的是导入过程中删除的对象数量。只有当 导入配置为删除数据时才会删除，而且只有在有效载荷中的对象已设置了 uids 时才会删除。 设置。

忽略 "指的是未被持久化的对象。对象被忽略有多种原因，例如 例如，试图创建已经存在的对象。忽略总是安全的，所以如果 被忽略的对象是不必要的，或者是由于导入的配置造成的。

捆绑报告*

导入完成后，bundleReport 会包含所有导入的 tracker 对象。

例如，TRACKED_ENTITY：

status is based on the presence of the most significant validationReport. ERROR has the highest significance, followed by WARNING and finally OK. This implies that ERROR is reported as long as a single error was found during the import, regardless of how many warnings occurred.

如图所示，每种类型的跟踪器对象都将被报告，每种对象都有自己的统计信息和 对象报告这些 objectReports 将提供每个导入对象的详细信息，如它们的 类型、uid 以及任何适用的错误或警告报告。

信息*

The validationReport might include errorReports and warningReports if any errors or warnings were present during the import. When present, they provide a detailed list of any errors or warnings encountered.

导入摘要报告级别{ #import-summary-report-level }¶

如前所述，GET /tracker/jobs/{uid}/report可以使用特定的reportMode参数检索。 报告模式 "参数进行检索。默认情况下，端点将返回一个 reportMode 为ERROR的importSummary。 ERROR.

The deleted field refers to the number of objects deleted during the import. Deletion only happens when the import is configured to delete data and only then when the objects in the payload have existing uids set.

错误代码{ #webapi_nti_error_codes }¶

Bundle report

验证方式¶

使用跟踪器导入项目导入数据时，会执行一系列验证，以确保数据的有效性。 数据的有效性。本节将介绍执行的一些不同类型的验证 以便更好地了解导入验证是否失败。

所需属性{ #required-properties }¶

在导入数据时，每个跟踪器对象都有几个必须具备的属性 数据。有关所需属性的详尽列表，请参阅[跟踪器对象 部分]（#webapi_nti_tracker_objects）。

Relationship: {0}, already exists.

1. E4016
2. Relationship: {0}, do not exist.
3. E4017

Relationship: {0}, is already deleted and cannot be modified.

格式{ #formats }¶

Relationship: {0}, linking {1}: {2} to {3}: {4} already exists.

• E4020
• User: {0}, has no write access to relationship: {1}.
• E5000

用户访问{ #user-access }¶

将根据元数据（共享）和组织单位（组织单位范围 和数据中引用的组织单位（组织单位范围）进行验证。 数据。有关共享和组织单位作用域的更多信息，请参阅以下章节。 章节。

在数据库中查找参考资料的同时，共享也会得到验证。用户访问权限之外的元数据 将被视为不存在。导入将验证数据中引用的任何元数据。 元数据。

而组织单位则具有双重目的。它主要确保数据 只有在导入用户 "捕获范围 "内的组织单位时，才能导入数据。 范围 "内的组织单位导入数据。其次，组织单位还用于限制可用的程序。这意味着 这意味着，如果你试图为一个组织单位导入数据，而该组织单位无法访问你要导入的 程序，则导入将无效。

Undefined error message.

属性和数据值{ #attribute-and-data-values }¶

属性和数据值分别是被跟踪实体和事件的一部分。但是 属性可以通过类型（TrackedEntityType）或项目（Program）链接到被跟踪实体。 项目（Program）。此外，属性也可以是唯一的。

Required properties

强制性属性和数据值也会被检查。目前不允许删除强制属性。 不允许。有些用例要求单独发送值，而有些用例则要求将所有值作为一个整体发送。 值作为一个整体发送。程序可配置为在 "ON_COMPLETE "或 "ON_UPDATE_ `"时验证强制属性。 ON_UPDATE_AND_INSERT "来适应这些用例。

导入时将验证唯一属性。这意味着只要提供的 值在整个系统中是唯一的，就可以通过。但是，如果唯一值是 则导入失败。

组态¶

The reference points to the correct type of data and exists in the database

• 特征类型（用于几何图形）
• If the first condition fails, the import will fail with a message about a missing reference. However, suppose the reference points to something that doesn't exist or which the user cannot access. In that case, both cases will result in a message about the reference not being found.
• Formats
• Some of the properties of tracker objects require a specific format. When importing data, each of these properties is validated against the expected format and will return different errors depending on which property has a wrong format. Some examples of properties that are validated this way:
• 还有更多

UIDs (These cover all references to other data or metadata in DHIS2.)

计划规则{ #webapi_nti_program_rules }¶

用户可以配置 程序规则，为跟踪器表单添加条件行为。 跟踪器表单添加条件行为。除了在跟踪器应用程序中运行这些规则外，跟踪器导入程序也会 也会运行这些规则的一部分。由于导入程序也会运行这些规则，因此我们可以确保 多一层验证。

并非所有项目规则操作都受支持，因为它们只适用于前台演示。 受支持的项目规则操作的完整列表如下。

程序规则在导入程序中的评估方式与在 Tracker 应用程序中的评估方式相同。 总之，执行程序规则时会考虑以下条件：

• 程序规则必须与导入的数据相关联。例如，程序阶段或数据 元件。
• 项目规则的条件必须为真

项目规则的结果取决于这些规则中定义的操作：

• 项目规则操作可能会导致两种不同的结果：警告或错误。
• 错误会导致验证失败，而警告则会在 进口摘要。
  • SHOWWARNING 和 WARNINGONCOMPLETION 操作只能生成警告。
  • SHOWERROR、ERRORONCOMPLETION 和 SETMANDATORYFIELD 操作只能生成错误。
  • ASSIGN 操作既可生成警告，也可生成错误。
  • 当操作为空属性/数据元素赋值时，系统会发出警告。 生成。
  • 当操作正在为一个属性/数据元素赋值时，该元素已经具有与该属性/数据元素相同的 值，就会发出警告。
  • 当操作为已有值的属性/数据元素赋值时 和要赋值的值不同，就会产生错误，除非 RULE_ENGINE_ASSIGN_OVERWRITE "系统设置为 "true"。

此外，项目规则也会产生副作用，如发送和计划信息。更多 有关副作用的更多信息，请参阅下一节。

注

在导入过程中，可以使用 skipProgramRules 参数跳过项目规则。

副作用{ #webapi_nti_side_effects }¶

SENDMESSAGE

X

SCHEDULEMESSAGE

注

某些配置可以控制副作用的执行。可以在导入过程中设置 skipSideEffects 标志，以完全跳过副作用。例如，如果你导入了一些不想触发通知的内容，这个参数就很有用。

为事件分配用户{ #webapi_nti_user_event_assignment }¶

When the action is assigning a value to an attribute/data element that already has the same value to be assigned, a warning is generated.

When the action is assigning a value to an attribute/data element that already has a value and the value to be assigned is different, an error is generated unless the RULE_ENGINE_ASSIGN_OVERWRITE system setting is true.

此外,项目规则也会产生副作用,如发送和计划信息。更多 有关副作用的更多信息,请参阅下一节。

{
  ...
  "events": [
    {
      "event": "ZwwuwNp6gVd",
      "programStage": "nlXNK4b7LVr",
      "orgUnit": "O6uvpzGd5pu",
      "enrollment": "MNWZ6hnuhSw",
      "assignedUser" : "M0fCOxtkURr"
    }
  ],
  ...
}

在本例中，uid 为M0fCOxtkURr的用户将被分配给uid 为ZwwuwNp6gVd的事件。 的事件。一个事件只能分配一个用户。

要使用这一功能，相关项目阶段必须启用用户分配功能，而且为用户提供的 uid 必须是一个有效的现有用户。

跟踪器输出{ #webapi_nti_export }¶

The following side effects are currently supported:

• 跟踪实体
• 活动
• ** 注册**
• 关系

注

• 所有跟踪器导出端点默认使用 JSON 响应内容。CSV "仅支持 被跟踪的实体和事件。 您可以通过在请求中添加 Accept 标头 text/csv 或 application/csv 来导出 CSV 文件。 到请求中。 您可以下载 zip 和 gzip 格式的文件：
• 跟踪实体的 CSV 事件的 JSON 和 CSV 您可以通过为 CSV 添加Accept标头***application/csv+gzip***来导出 Gzip 文件。 或 application/json+gzip 用于 JSON。
• 对于 CSV 或 JSON，可通过添加 Accept 标头***application/csv+zip***导出 Zip 文件。 application/json+zip 用于 JSON。

常见请求参数{ #common-request-parameters }¶

以下终端支持分页的标准参数。

• 跟踪实体 GET /api/tracker/trackedEntities
• Events GET /api/tracker/events
• Enrollments GET /api/tracker/enrollments
• Relationships GET /api/tracker/relationships

类型¶

注意事项

请注意，性能与请求的数据量直接相关。较大的页面 将需要更多时间返回。

组织单位选择模式的请求参数{ #request-parameters-for-organisational-unit-selection-mode }¶

可用的组织单位选择模式有 "选定"、"儿童"、"替代者"、 可接受"、"捕获 "和 "全部"。本节 部分](#webapi_nti_orgunit_scope)中对每种模式都有详细说明。

用于过滤响应的请求参数{ #webapi_nti_field_filter }¶

pageSize

例子¶

跟踪实体 (GET /api/tracker/trackedEntities){ #tracked-entities-get-apitrackertrackedentities }¶

Organisation unit selection modes

• GET /api/tracker/trackedEntities
• Field filter responses { #webapi_tracker_field_filter }
• GET /api/tracker/trackedEntities/{id}
• 检索给定 id 的被跟踪实体

Query parameter example

CSV{ #csv }¶

串

• Returns all fields
• 跟踪实体类型 (UID)
• Returns fields createdAt and uid
• fields=enrollments[*,!uid]
• Returns all fields of enrollments except uid
• fields=enrollments[uid]
• 组织单位（UID）
• fields=enrollments[uid,enrolledAt]
• Returns enrollments fields uid and enrolledAt
• Tracked entities { #webapi_tracker_export_tracked_entities }
• 几何图形（WKT, https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry. Two endpoints are dedicated to tracked entities:
• GET /api/tracker/trackedEntities
• retrieves tracked entities matching given criteria
• 属性
• retrieves a tracked entity given the provided ID
• If not otherwise specified, JSON is the default response for the GET method. The API also supports CSV export for single and collection endpoints. Furthermore, compressed CSV types is an option for the collection endpoint.
• CSV
• In the case of CSV, the fields request parameter has no effect, and the response will always contain the following fields:
• trackedEntity (UID)
• trackedEntityType (identifier in requested idScheme)
• createdAt (Datetime)
• createdAtClient (Datetime)

updatedAt (Datetime)

GZIP{ #gzip }¶

orgUnit (identifier in requested idScheme)

ZIP{ #zip }¶

deleted (boolean)

跟踪实体收集端点 GET /api/tracker/trackedEntities¶

You can omit it in case of a Point type and with latitude and longitude provided)

latitude (Latitude of a Point type of Geometry)

DateTime

ISO-8601

查询不区分大小写。以下规则适用于查询 参数。

• orgUnitIdScheme Enum

• UID, CODE, NAME, ATTRIBUTE:{uid} 指定（零或一）。

• 如果指定了 "程序状态"，则 "程序 "也必须是 指定的。

• Mode

• 描述 CURRENT

• 过滤器项目只能指定一次。

请求示例{ #example-requests }¶

与特定组织单位和计划相关的所有被跟踪实体的查询如下所示 如下

GET /api/tracker/trackedEntities?program=IpHINAT79UW&orgUnits=DiszpKrYNg8

Includes unassigned events only.

GET /api/tracker/trackedEntities?program=IpHINAT79UW&orgUnits=DiszpKrYNg8&filter=w75KJ2mc4zz:EQ:John

为过滤器指定了多个操作数和过滤器的查询 物品：

GET /api/tracker/trackedEntities?orgUnits=DiszpKrYNg8&program=ur1Edk5Oe2n&filter=lw1SqmMlnfh:GT:150&filter=lw1SqmMlnfh:LT:190

Filter the result down to a limited set of tracked entities with events that are assigned to the given user IDs by using assignedUser=id1,id2.This parameter will only be considered if assignedUserMode is either PROVIDED or null. The API will error out, if for example, assignedUserMode=CURRENT and assignedUser=someId.

GET /api/tracker/trackedEntities?orgUnits=DiszpKrYNg8&program=ur1Edk5Oe2n&filter=lw1SqmMlnfh:EQ:/:/,//

要将程序注册日期指定为查询的一部分，请执行以下操作：

GET /api/tracker/trackedEntities?orgUnits=DiszpKrYNg8&program=IpHINAT79UW&fields=trackedEntity,enrollments[enrolledAt]&enrollmentEnrolledAfter=2024-01-01

要在 IN 过滤器中使用多个值查询属性：

GET /api/tracker/trackedEntities?trackedEntityType=nEenWmSyUEp&orgUnits=DiszpKrYNg8&filter=w75KJ2mc4zz:IN:Scott;Jimmy;Santiago

您可以使用一系列运算符进行过滤：

跟踪实体响应示例{ #tracked-entities-response-example }¶

Operator

JSON{ #json }¶

可根据所需字段过滤响应，请参阅用于过滤响应的请求参数 响应的请求参数

JSON 响应可以如下所示：

!null

CSV{ #csv }¶

CSV 响应如下：

Filtering by a tracked entity attribute narrows the response to tracked entities matching given filters. A filter is a colon separated property or attribute UID with optional operator and value pairs.

跟踪实体收集限制{ #tracked-entities-collection-limits }¶

A filter like filter=H9IlTX2X6SL:!null returns all entries where the given attribute has a value.

• KeyTrackedEntityMaxLimit 在系统设置中：KeyTrackedEntityMaxLimit "定义了最大的 在 API 响应中跟踪实体，保护数据库和服务器资源。无限制 中所述，通过 /api/systemSettings进行配置。 A minimum number of characters required to perform a search (0 means no minimum)

• Blocked operators. Only sw, ew, and like can be blocked. All other operators cannot be blocked. The following request: 超过此限制。在捕获范围内搜索时没有限制 would fail if the minimum character limit was set to 5 (since "John" has only 4 characters), or if the EQ operator was blocked for the specified tracked entity attribute. Tracked entities response

• The API supports CSV and JSON response for GET /api/tracker/trackedEntities.

JSON格式

• Responses can be filtered on desired fields, see field filter for more information.

• A JSON response looks like the following:

Tracked Entities single object endpoint GET /api/tracker/trackedEntities/{uid}¶

该端点的目的是检索一个给定 uid 的被跟踪实体。

请求语法¶

GET /api/tracker/trackedEntities/{uid}?program={programUid}&fields={fields}

请求示例{ #example-requests }¶

Request syntax

GET /api/tracker/trackedEntities/PQfMcpmXeFE

跟踪实体响应示例{ #tracked-entity-response-example }¶

类型

JSON{ #json }¶

json 响应示例：

``json { "trackedEntity"："PQfMcpmXeFE"、 "trackedEntityType"："nEenWmSyUEp"、 "createdAt"："2014-03-06T05:49:28.256", "createdAtClient"："2014-03-06T05:49:28.256", "updatedAt"："2016-08-03T23:49:43.309", "orgUnit"："DiszpKrYNg8"、 "inactive": false、 "deleted": false、 "potentialDuplicate": false、 "属性"： [[ { "属性"： ["w75KJ2mc4zz"、 "代码"："MMD_PER_NAM"、 "displayName"（显示名称）："名字"、 "创建时间"："2016-08-03T23:49:43.308", "updatedAt"："2016-08-03T23:49:43.308", "valueType"（值类型）： "TEXT"（文本"TEXT"、 "值"："约翰" }, { "属性"："zDhUuAYrxNC"、 "显示名"："姓氏"、 "创建时间"："2016-08-03T23:49:43.309", "updatedAt"："2016-08-03T23:49:43.309", "valueType"（值类型）： "TEXT"（文本"TEXT"、 "值"："凯莉" } ], "注册"：[ { "注册"："JMgRZyeLWOo"、 "创建时间"："2017-03-06T05:49:28.340", "创建于客户端"："2016-03-06T05:49:28.340", "updatedAt"："2017-03-06T05:49:28.357", "trackedEntity"："PQfMcpmXeFE"、 "程序"： "IpHINAT79U"IpHINAT79UW"、 "状态"："ACTIVE"、 "orgUnit"："DiszpKrYNg8"、 "enrolledAt"："2024-03-06T00:00:00.000", "occurredAt"："2024-03-04T00:00:00.000", "followUp": false、 "deleted": false、 "事件"： [[ { "event"："Zq2dg6pTNoj"、 "状态"："ACTIVE"、 "程序"："IpHINAT79UW"、 "程序阶段"： "ZzYYXq4fJie"ZzYYXq4fJie"、 "注册"： "JMgRZyeLWOO"："JMgRZyeLWOo"、 "跟踪实体"： "PQfMcpmX"PQfMcpmXeFE"、 "关系"：[], "scheduledAt"："2023-03-10T00:00:00.000", "followUp": false、 "deleted": false、 "createdAt"："2017-03-06T05:49:28.353", "createdAtClient"："2016-03-06T05:49:28.353", "updatedAt"："2017-03-06T05:49:28.353", "attributeOptionCombo"："HllvX50cXC0"、 "attributeCategoryOptions"："xYerKDKCefk"、 "dataValues"：[], "notes"：[], "followup": false } ], "关系"：[], "属性"：[ { "属性"： ["w75KJ2mc4zz"、 "代码"："MMD_PER_NAM"、 "displayName"（显示名称）："名字"、 "创建时间"："2016-08-03T23:49:43.308", "updatedAt"："2016-08-03T23:49:43.308", "valueType"（值类型）： "TEXT"（文本"TEXT"、 "值"："约翰" }, { "属性"："zDhUuAYrxNC"、 "显示名"："姓氏"、 "创建时间"："2016-08-03T23:49:43.309", "updatedAt"："2016-08-03T23:49:43.309", "valueType"（值类型）： "TEXT"（文本"TEXT"、 "值"："凯莉" }, { "属性"："AuPLng5hLbE"、 "代码"："国家标识符"、 "displayName"（显示名称）："国家标识符"、 "createdAt"："2016-08-03T23:49:43.301", "updatedAt"："2016-08-03T23:49:43.301", "valueType"（值类型）： "TEXT"（文本"TEXT"、 "值"："245435245" }, { "属性"："ruQQnf6rswq"、 "显示名称"："结核病编号"、 "创建时间"："2016-08-03T23:49:43.308", "updatedAt"（更新时间"2016-08-03T23:49:43.308", "valueType"（值类型）： "TEXT"（文本"TEXT"、 "值"： "1z 1f2 a84"1Z 1F2 A84 59 4464 173 6" }, { "属性"："cejWyOfXge6"、 "显示名称"："性别"、 "创建时间"："2016-08-03T23:49:43.307", "updatedAt"："2016-08-03T23:49:43.307", "valueType"（值类型）： "TEXT"（文本"TEXT"、 "值"："男性" }, { "属性"："VqEFza8wbwA"、 "代码"："mmd_per_adr1"、 "显示名称"："地址"、 "创建时间"："2016-08-03T23:49:43.307", "updatedAt"（更新时间"2016-08-03T23:49:43.307", "valueType"（值类型）："TEXT"（文本"TEXT"、 "值"："主要街道 2" } ], "备注"：[] } ], "programOwners"：[ { "orgUnit"："DiszpKrYNg8"、 "trackedEntity"："PQfMcpmXeFE"、 "程序"："ur1Edk5Oe2n" }, { "orgUnit"："DiszpKrYNg8"、 "trackedEntity"："PQfMcpmXeFE"、 "程序"："IpHINAT79UW" } } ] }

###### CSV{ #csv } 

`uid`

#### Return the tracked entity with specified `uid`
`GET /api/tracker/trackedEntities/{uid}/changeLogs`

串

|默认值|Potential duplicate status|`order`|
|---|---|---|
|`fields`|JSON格式|Include specified sub-objects in the response|
|程序|JSON格式|```
GET /api/tracker/trackedEntities/PQfMcpmXeFE
```|

##### 跟踪实体属性值更改日志响应示例{ #tracked-entity-attribute-value-change-logs-response-example } 

json 响应示例：

``json
{
   "pager":{
      "page":1、
      "页面大小":10
   },
   "changeLogs":[
      {
         "createdBy":{
            "uid": "AIK2aQOJIbj"、
            "username": "tracker"、
            "firstName": "Tracker demo"、
            "姓": "用户"
         },
         "createdAt":"2024-06-20T14:51:16.433",
         "类型": "更新"、
         "更改":{
            "dataValue":{
               "dataElement": "bx6fsa0t90x"、
               "previousValue": "true"、
               "currentValue": "false"
            }
         }
      },
      {
         "createdBy":{
            "uid": "AIK2aQOJIbj"、
            "username": "tracker"、
            "firstName": "Tracker demo"、
            "姓": "用户"
         },
         "createdAt":"2024-06-20T14:50:32.966",
         "类型": "创建"、
         "更改":{
            "dataValue":{
               "dataElement": "ebaJjqltK5N"、
               "currentValue": "0"。
            }
         }
      }
   ]
}

The response will be the same as the collection endpoint but referring to a single event, although it might have multiple rows for each data element value.

注册人数 (GET /api/tracker/enrollments){ #enrollments-get-apitrackerenrollments }¶

有两个端点专门用于注册：

• 串
  • Tracked entity UID.
• 项目
  • 检索给定 id 的注册信息

注册信息收集端点 GET /api/tracker/enrollments¶

order

查询不区分大小写。以下规则适用于查询参数。

• 必须使用 orgUnit 参数（一个或多个）指定至少一个组织单位，或 必须指定*orgUnitMode=ALL*。

• 只能指定 program 和 trackedEntity 参数中的一个（0 或 1）。

• 如果指定了 programStatus，则还必须指定 program。

• 如果指定了*followUp*，则还必须指定*program*。

• 如果指定了 enrolledAfter 或 enrolledBefore，则还必须指定 program。

请求示例{ #example-requests }¶

ISO-8601

GET /api/tracker/enrollments?orgUnits=DiszpKrYNg8

要将响应限制在属于特定计划的注册人数上，您可以包含一个 程序查询参数：

GET /api/tracker/enrollments?orgUnits=O6uvpzGd5pu&orgUnitMode=DESCENDANTS&program=ur1Edk5Oe2n

At least one organisation unit must be specified using the orgUnit

GET /api/tracker/enrollments?orgUnits=DiszpKrYNg8&program=M3xtLkYBlKI&enrolledAfter=2023-11-14&enrolledBefore=2024-02-07

order

GET /api/tracker/enrollments?trackedEntity=ClJ3fn47c4s

Comma-separated list of property name or attribute or UID and sort direction pairs in format propName:sortDirection.

GET /api/tracker/enrollments?orgUnitMode=ACCESSIBLE&trackedEntity=tphfdyIiVL6

输出的最大限制。¶

JSON` 响应可以如下所示。

Comma-separated list of enrollment UIDs.

Enrollments single object endpoint GET /api/tracker/enrollments/{uid}¶

该端点的目的是检索一个给定 uid 的 Enrollment。

请求语法¶

GET /api/tracker/enrollment/{uid}

请求示例{ #example-requests }¶

报名查询：

GET /api/tracker/enrollments/JMgRZyeLWOo

输出的最大限制。¶

The purpose of this endpoint is to retrieve an enrollment given its ID.

事件 (GET /api/tracker/events){ #events-get-apitrackerevents }¶

有两个端点专门用于处理事件：

• GET /api/tracker/events
  • 检索符合给定条件的事件
• GET /api/tracker/events/{id}
  • 检索给定 id 的事件

如果未另行指定，JSON 将是 GET 方法的默认响应。 API 还支持单个和集合端点的 CSV 导出。此外，它还支持 压缩 JSON 和 CSV。

活动 CSV{ #events-csv }¶

串

• 事件
• 状态（字符串）
• 程序
• 程序阶段
• 注册
• 组织单位（UID）
• occurredAt (DateTime)
• scheduledAt (DateTime)
• 几何图形（WKT, https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry. Two endpoints are dedicated to tracked entities:
• GET /api/tracker/trackedEntities
• retrieves tracked entities matching given criteria
• followUp （布尔）
• Returns enrollments fields uid and enrolledAt
• 创建时间（DateTime）
• 创建于客户端（日期时间）
• updatedAt (DateTime)
• updatedAtClient (DateTime)
• completedBy (字符串)
• completedAt (DateTime)
• updatedBy（用户的用户名）
• attributeOptionCombo (UID)
• attributeCategoryOptions (UID)
• assignedUser （用户的用户名）
• dataElement (UID)
• trackedEntity (UID)
• trackedEntityType (identifier in requested idScheme)
• providedElsewhere (布尔值)
• storedByDataValue （字符串）
• createAtDataValue （日期时间）
• updatedAtDataValue （日期时间）

有关更多字段说明，请参阅 [事件]（#events）和 [数据值]（#data-values）。

活动 GZIP{ #events-gzip }¶

身份证

活动 ZIP{ #events-zip }¶

用户名

事件收集端点 GET /api/tracker/events¶

ID

Comma-separated list of event UIDs.

请求示例{ #example-requests }¶

attributeCategoryCombo (see note)

GET /api/tracker/events?orgUnit=YuQRtpLP10I&orgUnitMode=CHILDREN

Attribute category combo identifier. Must be combined with attributeCategoryOptions.

GET /api/tracker/events?orgUnit=O6uvpzGd5pu&orgUnitMode=DESCENDANTS

串

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc

includeDeleted

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&order=scheduledAt

When true, soft deleted events will be included in your query result.

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&order=occurredAt:desc&pageSize=10&page=1

串

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=M3xtLkYBlKI&trackedEntity=dNpxRu1mWG5

查询所有早于或等于 2024-02-03 且与计划和组织相关的事件 单位：

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&occurredBefore=2024-02-03

串

GET /api/tracker/events?orgUnit=g8upMTyEZGZ&program=M3xtLkYBlKI&filter=rFQNCGMYud2:GT:35&filter=rFQNCGMYud2:LT:50

Filter the result down to a limited set of tracked entities with events that are assigned to the given user IDs by using assignedUser=id1,id2.This parameter will only be considered if assignedUserMode is either PROVIDED or null. The API will error out, if for example, assignedUserMode=CURRENT and assignedUser=someId.

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,//

事件响应示例{ #events-response-example }¶

The query for all events with children of a particular organisation unit:

JSON{ #json }¶

The query for all events with all descendants of a particular organisation unit, implying all organisation units in the sub-hierarchy:

``json { "pager"：{ "page"：1, "pageSize"：1 }, "事件"：[ { "event"："A7rzcnZTe2T"、 "状态"："ACTIVE"、 "程序"："eBAyeGv0exc"、 "programStage"："Zj7UnCAulEk"、 "注册"： "RiLEKhWHlxZ"："RiLEKhWHlxZ"、 "orgUnit"："DwpbWkiqjMy"、 "occurredAt"："2023-02-13T00:00:00.000", "scheduledAt"："2023-02-13T00:00:00.000", "followUp": false、 "deleted": false、 "createdAt"："2017-09-08T21:40:22.000", "createdAtClient"："2016-09-08T21:40:22.000", "更新时间"： "2017-09-08t21:40:22.000"："2017-09-08T21:40:22.000", "attributeOptionCombo"："HllvX50cXC0"、 "attributeCategoryOptions"："xYerKDKCefk"、 "几何"：{ "类型"："点"、 "坐标"： [[ -11.468912037323042, 7.515913998868316 ] }, "dataValues"（数据值）：[ { "创建时间"："2016-12-06T18:22:34.438", "更新时间"："2016-12-06T18:22:34.438", "storedBy"："bjorn"、 "providedElsewhere": false、 "dataElement"："F3ogKBuviRA"、 "value"："[-11.4880220438585,7.50978830548003]" }, { "createdAt"："2013-12-30T14:23:57.423", "updatedAt"："2013-12-30T14:23:57.423", "storedBy"："lars"、 "providedElsewhere": false、 "dataElement"："eMyVanycQSC"、 "值"："2018-02-07" }, { "创建时间"："2013-12-30T14:23:57.382", "updatedAt"："2013-12-30T14:23:57.382", "storedBy"："lars"、 "providedElsewhere": false、 "dataElement"："oZg33kd9taw"、 "值"："男" } ], "备注"：[], "followup": false } ] }

###### CSV{ #csv } 

Query for all events with a certain program and organisation unit, sorting by scheduled date
ascending:

#### ```
GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&order=scheduledAt

查询某一项目和组织单位中发生日期最新的 10 个事件 - 通过分页和按发生日期降序排序的方法 通过分页和按发生日期降序排序:

请求语法¶

Query for all events with a certain program and organisation unit for a specific tracked entity:

请求示例{ #example-requests }¶

The CSV response can look like the following:

GET /api/tracker/events/rgWr86qs0sI

事件响应示例{ #event-response-example }¶

The purpose of this endpoint is to retrieve one Event given its uid.

JSON{ #json }¶

GET /api/tracker/events/{uid}?fields={fields}

CSV{ #csv }¶

类型

Allowed values¶

描述

此端点可检索特定事件数据值的更改日志。它会返回该特定事件随时间变化的所有事件数据值的列表。

事件数据值更改日志响应示例{ #event-data-value-change-logs-response-example }¶

json 响应示例：

CSV

The response will be the same as the collection endpoint but referring to a single event, although it might have multiple rows for each data element value.

关系 (GET /api/tracker/relationships){ #relationships-get-apitrackerrelationships }¶

Parameter

类型

Allowed values

• GET /api/tracker/relationships?[trackedEntity={trackedEntityUid}|enrollment={enrollmentUid}|event={eventUid}]&fields=[fields]

请求参数{ #request-parameters }¶

串

• 只能传递 "trackedEntity"、"enrollment"、"event "中的一个参数

注

使用 "trackedEntity"、"enrollment "或 "event "参数将返回任何关系，其中 跟踪实体"、"注册 "或 "事件 "是关系的一部分（从或至）。只要 用户有访问权限。

回复示例{ #example-response }¶

串

跟踪器门禁控制{ #webapi_nti_access_control }¶

Identifier of an event

元数据共享{ #webapi_nti_metadata_sharing }¶

串

共享设置的工作原理很简单--在 Tracker 数据 导入/导出过程中强制执行。要读取数据值，用户需要拥有数据读取权限。如果用户要 修改数据，则需要拥有数据写入权限。同样，如果用户要修改 元数据，就必须授予元数据写入权限。

Include specified sub-objects in the response

order

串

Comma-separated list of property name or attribute or UID and sort direction pairs in format propName:sortDirection.

有关数据共享的更多详细信息，请查阅 数据 共享。

组织单位范围{ #webapi_nti_orgunit_scope }¶

组织单位是 DHIS2 中最基本的对象之一。它们定义了一个范围 允许用户记录和/或读取数据的范围。有三种组织单位 可分配给用户的组织单位有三种。它们是数据采集、数据查看（不用于跟踪器）和跟踪器搜索。 搜索。顾名思义，这些组织单位定义了一个范围，在此范围内，用户可以进行相应的操作。 进行相应操作的范围。

Boolean

true, false

api/tracker/trackedEntities?orgUnit=UID&orgUnitMode=specific_organisation_unit_selection_mode

The following rules apply to the query parameters.

1. 选择：顾名思义，该模式缩小了由 向请求中指定的组织单位请求 API。
2. 儿童：在此模式下，组织单位范围使用所选的 组织单位及其直属单位，即下一级组织单位。
3. 后代：在此模式下，选定的组织单元及其下的所有内容、 不仅包括直系子代，还包括所有后代，构成数据操作 宇宙
4. 捕获：该模式包括与当前系统相关联的数据采集组织单位。 用户和所有后代。它包括子层次结构中的所有组织单位。
5. 可访问：该模式旨在检索用户搜索范围内的数据 组织单位。这包括用户可见的所有内容，包括打开和已审计的内容。 搜索范围内的程序，以及用户的受保护程序和封闭程序中的数据。 捕获范围。如果用户没有搜索组织单位，系统默认为捕获范围、 确保用户始终可以访问至少一个宇宙。捕获范围 它是强制性的，是保证用户数据环境的基本要素。
6. 全部：该模式仅供授权用户使用，特别是具有 ALL（全部）权限的用户。 (超级用户）。具有 F_TRACKED_ENTITY_INSTANCE_SEARCH_IN_ALL_ORGUNITS 权限的用户还可以 在全系统范围内搜索，但需要共享对返回程序、程序阶段和/或跟踪程序的访问权限 实体类型。对于未经授权的用户，将出现异常。

前三种模式（SELECTED、CHILDREN 和 DESCENDANTS）希望在请求中提供一个组织单位，而后三种模式（CAPTURE、ACCESSIBLE 和 ALL）则不希望在请求中提供组织单位。 而后三种模式（CAPTURE、ACCESSIBLE 和 ALL）则不需要。 实际上，如果提供了组织单位，请求就会失败。

如果在 API 请求中明确提供时，组织单位模式将是上述所列模式之一。由于这不是一个必填字段，如果没有指定，那么默认值为 默认值为*SELECTED*，否则为*ACCESSIBLE*。

Users can do the fine-tuning by passing a specific value of orgUnitMode in their API request:

请注意，与 Tracker 对象相关的组织单位关联有 4 种类型。A 跟踪实体有一个组织单位，通常称为注册组织单位。 注册有一个与之相关的组织单位。事件也有一个 关联。跟踪实体-计划组合也有一个所有者组织单元。 组合。

Currently, there are six selection modes available: SELECTED, CHILDREN, DESCENDANTS, CAPTURE, ACCESSIBLE, and ALL.

例如，在没有程序上下文的情况下检索 TrackedEntity 时，组织单位范围适用于注册组织单位。 作用域适用于 TrackedEntity 的注册组织单位。而当 组织单位范围则应用于所有者组织单位。 组织单位范围适用于所有者组织单位。

跟踪器计划所有权{ #webapi_nti_ownership }¶

从 2.30 开始引入一个新概念，即 "追踪者所有权"。这就为 TrackedEntity - Program 组合引入了一个新的组织 单位关联。我们称其为 组织单位。所有者组织单元 用来决定读写与程序相关的跟踪数据时的访问权限。这一点 访问级别](#webapi_nti_access_level) 配置一起，决定与程序相关数据（注册）的访问行为。 行为。如果相应的所有者组织--用户--可以访问一个 TrackedEntity 的 如果该 TrackedEntity-Program 组合对应的所有者组织单位（OrganisationUnit 在用户的组织单位范围内（搜索/捕获）。对于配置为 的程序，其所有者组织单位必须在用户的搜索范围内。 范围。对于访问级别为*PROTECTED*或*CLOSED*的程序，所有者组织单位必须在用户搜索范围内。 组织单位必须在用户的捕获范围内，才能访问特定被跟踪实体的相应程序数据。 的程序数据。无论程序访问级别如何，要访问 无论程序访问级别如何，要访问跟踪器对象，所请求的组织单位必须始终在用户的搜索范围内。A 用户不能请求其搜索范围之外的对象，除非它使用组织单位模式 并且有足够的权限使用该模式。

请求跟踪实体而不指定项目时，响应将只包含满足 元数据共享设置 和以下标准之一的跟踪实体： - 被跟踪的实体已加入用户可访问数据的至少一个项目，且用户可访问所有者组织单元。 - 被跟踪实体未加入用户可访问数据的任何项目，但用户可访问被跟踪实体的注册组织单位。

CAPTURE¶

The data capture organisation units associated with the current user and all organisation units in the sub-hierarchy.

这种临时进入的行为被称为 "打破玻璃"。 目前，允许临时访问的时间为 3 小时。DHIS2 将对打破玻璃的行为以及用户指定的 用户指定的原因。不可能临时访问已配置为 * 关闭 * 访问级别的项目。 临时访问已配置为*关闭*访问级别的项目是不可能的。

全部

/api/tracker/ownership/override?trackedEntity=DiszpKrYNg8&program=eBAyeGv0exc&reason=patient+showed+up+for+emergency+care

跟踪器所有权转移¶

The organisation unit mode will be one of the ones listed above when it is explicitly provided in the API request. Since it is not a mandatory paramter, when not specified, the default value will be SELECTED if an organisation unit is present, and ACCESSIBLE if not.

/api/tracker/ownership/transfer?trackedEntity=DiszpKrYNg8&program=eBAyeGv0exc&ou=EJNxP3WreNP

访问级别{ #webapi_nti_access_level }¶

DHIS2 对 Tracker 数据提供额外的保护。除了标准的 元数据和数据保护的标准功能外，Tracker 数据还受到额外的 访问级别保护机制。 目前，可为程序配置四种访问级别 程序：开放、审核、保护和关闭。

例如,在没有项目上下文的情况下检索 "跟踪实体 "时,组织单位 范围适用于被跟踪实体的注册组织单位。而当 组织单位范围适用于所有者组织单位。 组织单位范围适用于所有者组织单位。

打开{ #open }¶

A new concept called Tracker Ownership is introduced from 2.30. This introduces a new organisation unit association for a TrackedEntity - Program combination. We call this the Owner (or Owning) Organisation unit of a TrackedEntity in the context of a Program. The Owner organisation unit is used to decide access privileges when reading and writing tracker data related to a program. This, along with the Program's Access Level configuration, decides the access behavior for Program-related data (Enrollments and Events). A user can access a TrackedEntity's Program data if the corresponding Owner OrganisationUnit for that TrackedEntity-Program combination falls under the user's organisation unit scope (Search/Capture). For Programs that are configured with access level OPEN or AUDITED , the Owner OrganisationUnit has to be in the user's search scope. For Programs that are configured with access level PROTECTED or CLOSED , the Owner OrganisationUnit has to be in the user's capture scope to be able to access the corresponding program data for the specific tracked entity. Irrespective of the program access level, to access Tracker objects, the requested organisation unit must always be within either the user's search scope or capture scope. A user cannot request objects outside these two scopes unless they are using the organisation unit mode ALL and have sufficient privileges to use that mode.

经审计的{ #audited }¶

被跟踪的实体已加入用户可访问数据的至少一个项目,且用户

受保护的{ #protected }¶

这种访问级别的限制稍多一些。受保护程序中的数据只有在所有者组织单位属于用户捕获范围的情况下才能被用户访问。 只有当所有者组织单位属于用户的捕获范围时，用户才能访问受保护程序内的数据。但是，如果用户 在搜索范围内只有所有者组织单位的用户，可以通过[打破玻璃](#webapap... 玻璃](#webapi_nti_tracker_ownership_override)获得临时所有权。用户必须说明为什么要访问手头的数据。 他们为什么要访问手头的数据。然后，系统会将理由和访问审核记录在案，并提供 3 个月的临时访问权限。 审核，并为用户提供 3 小时的临时访问权限。请注意，打破玻璃时 时，所有者组织单位保持不变，只有打碎玻璃的用户才能获得临时访问权。 获得临时访问权。

关闭{ #closed }¶

这是最受限制的访问级别。在访问级别为 如果所有者组织单位不在用户的捕获范围内，则无法访问 "关闭 "程序下记录的数据。 范围。在这种配置下也无法打破玻璃或获得临时所有权。 请注意，仍有可能将所有权转移到另一个组织单位。只有 才能将 TrackedEntity-Program 组合的所有权转移给另一个组织单位。 另一个组织单位。如果所有权转移，所有者组织单位将被更新。