活动钩子{ #event-hooks }¶

事件钩子{ #webapi_event_hooks }¶

事件钩子 API 允许用户订阅 DHIS2 内部发生的 Web 事件。DHIS2 会以“尽力而为”的方式向订阅者发送事件，这意味着无法保证订阅者一定能收到该事件。

目前，发布的事件主要分为两类：一类是元数据事件，用于记录元数据对象的创建、更新和删除；另一类是调度器事件，用于记录任何类型的内部计划任务（如分析任务）的运行情况。

该端点位于 /api/eventHooks，且必须在您的 dhis.conf 文件中通过 event_hooks.enabled = on 这一配置项启用才能正常工作。

事件钩子主要有两个概念：你需要配置源（包括路径以及要应用的字段过滤器）和一个或多个目标（Webhook、JMS 等）。

为了说明其中的一些要点，我们将通过一个简单的 Webhook 来演示，该 Webhook 用于监听 dataElements 的元数据变更，并且已启用 Webhook 目标。

除了 source 和 target 之外，还有两个属性需要注意：一个是你提供的 name，它用于在 UI 中查看时的视觉提示；另一个是 disabled，其默认值为 false，但可让你暂时禁用某些当前可能不相关的事件钩子。

{
  "name": "webhook-api-token",
  "disabled": false,
  "source": {
    "path": "metadata.dataElement",
    "fields": "id,code,name"
  },
  "targets": [
    {
      "type": "webhook",
      "url": "http://localhost:3000/api/gateway",
      "auth": {
        "type": "api-token",
        "token": "EB3F6799-AA5A-47E8-B6B7-97EA54EB3873"
      }
    }
  ]
}

来源{ #source }¶

这里我们将重点讨论事件钩子中的 source.path 部分。对于 path 属性，我们支持两种主要路径：

metadata.type.id，您可以根据需要进行细化，例如，使用 metadata 可以监听所有元数据，而使用 metadata.organisationUnit 则仅监听组织单位的操作。

调度器事件也是如此，其路径为 scheduler.type.id，例如 scheduler.ANALYTICS_TABLE。

此外还支持字段过滤，默认过滤条件为 id,displayName，但您可以自由选择任何所需的字段进行过滤。为了保持系统轻量，不建议请求过大的数据包（因为根据您的路径不同，可能会发生许多事件）

目标{ #target }¶

在准备好 source（包括路径和过滤器）之后，您现在必须设置一个或多个目标。所有目标都必须指定 type 属性，而具体的数据负载会根据该属性而有所不同。

控制台{ #console }¶

console 目标是我们拥有的最简单的目标，它没有参数，唯一的作用就是将事件打印到系统日志中（在测试时可能会很有用）

{
  "type": "console"
}

Webhook{ #webhook }¶

webhook 目标会向您指定的 url 发送一个出站 HTTP 请求。该请求可选地包含身份验证（同时支持 api-token 和 http-basic），这些功能开箱即用。但如果您有自定义需求，也可以添加任何所需的请求头。 有效载荷将以 application/json 格式发送，具体内容取决于您在源中设置的字段过滤器。

{
  "type": "webhook",
  "url": "http://localhost:3000/api/gateway",
  "headers": {},
  "auth": {
    "type": "api-token",
    "token": "EB3F6799-AA5A-47E8-B6B7-97EA54EB3873"
  }
}

{
  "type": "webhook",
  "url": "http://localhost:3000/api/gateway",
  "auth": {
    "type": "http-basic",
    "username": "admin",
    "password": "admin"
  }
}

Apache Artemis JMS{ #apache-artemis-jms }¶

jms 目标允许您向 Apache Artemis 实例发送 JMS 消息（支持 JMS ⅔）。该目标非常适合对这些事件进行异步处理，并确保服务器在处理过程中不会被阻塞。如果您更倾向于使用 queue，可以将 useQueue 设置为 true。

{
  "type": "jms",
  "brokerUrl": "tcp://localhost:61616",
  "useQueue": false,
  "username": "guest",
  "password": "guest"
}

Apache Kafka{ #apache-kafka }¶

与 jms 目标类似，使用 kafka 目标可将这些事件发送到 Apache Kafka 实例中。目前尚不支持身份验证。

{
  "type": "kafka",
  "topic": "dhis2.hooks"
}