总览¶

Web API 是一个组件,它使外部系统成为可能 访问和操作存储在 DHIS2 实例中的数据。更多的 准确地说,它为广泛的 为第三方等应用项目公开数据和服务方法 软件客户端、门户网站和内部 DHIS2 模块。

介绍¶

Web API 遵循 REST 架构风格背后的许多原则。以下是一些重要原则:

1. 基本构建块称为*资源*。 资源可以是任何暴露在 Web 上的东西,从文档到 业务流程 - 客户端可能想要与之交互的任何内容。 资源的信息方面可以通过资源*表示*进行检索或交换。 表示是资源在任何特定时间的状态视图。例如,DHIS2 中的*可视化* 资源代表了汇总数据的*可视化*,可用于 一组特定的参数。该资源可以以 各种表示格式获取,包括 JSON 和 CSV。 所有资源都可以通过 URI(也称为
2. URL)唯一标识。所有资源都有一个默认表示。您可以 称为 URL）。所有资源都有一个默认表示法。您可以 查询参数来表明您对特定表示的兴趣。因此,要检索 CSV 格式的 提供*Accept* HTTP 标头、文件扩展名或*format*格式 或在请求 URL 中添加 .csv 或 ?format=csv。 与 API 的交互需要正确使用 HTTP 方法 或 动词。这意味着对于资源,您必须在想要检索它时发出 GET
3. 请求,在想要创建它时发出 POST 请求, 在想要更新它时发出 PUT 请求,在想要删除它时发出 DELETE 请求。 请求，当您要检索它时，POST 请求 创建一个，要更新时*PUT*，要删除时*DELETE*。 基本身份验证

个人访问令牌 (PAT)¶

OAuth 2

• 验证并获取当前已认证用户的信息。
• GET /api/me

• 获取当前已通过身份验证用户的授权列表。

  GET /api/me/authorization

检查当前已通过身份验证的用户是否拥有指定权限。

GET /api/me/authorization/{authority}

例如,检查用户是否拥有 F_CONSTANT_ADD 权限。

GET /api/me/authorization/F_CONSTANT_ADD

响应将以 JSON 格式显示为true或 false。

基本认证 { #webapi_basic_authentication }

DHIS2 Web API 支持*基本身份验证*。基本身份验证 是一种客户端通过 HTTP 将登录凭据发送到 Web 服务器的技术。从技术上讲,用户名后附有冒号和 密码,经过 Base64 编码,前缀 Basic 并作为值提供给 Authorization HTTP 标头。更正式的格式是:

Authorization: Basic base64encode(username:password)

大多数网络开发环境都支持基本¶

身份验证,例如 Apache HttpClient 和 Spring RestTemplate。 一个重要的注意事项是此身份验证方案不提供安全性, 因为用户名和密码是以纯文本形式发送的,可以很容易地 被攻击者截获。仅当服务器 使用 SSL/TLS (HTTPS) 加密与客户端的通信时才应使用。请将此 视为与 Web API 进行安全交互的硬性要求。

两因素验证 { #webapi_2fa }

DHIS2 支持两因素身份验证。这可以为每个用户启用。 启用后,用户将被要求在登录时输入 2FA 代码。您 可以在此处阅读更多关于 2FA 的信息。

个人访问令牌{ #webapi_pat_authentication }

个人访问令牌 (PAT) 是使用 API 时对 DHIS2 进行身份验证的密码替代方法。¶

个人访问令牌(PAT)是使用 API 时对 DHIS2 进行身份验证的另一种方式。

PAT 可作为 HTTP 基本身份验证的一种更安全的替代方式。 在创建新应用或脚本等时,PAT 应该是您的首选。

HTTP 基本身份验证被认为是不安全的,原因包括¶

它会以明文发送用户名和密码。在 未来的 DHIS2 版本中,基本身份验证可能会被弃用或改为选择启用,这意味着需要在配置中明确启用基本身份验证。 重要的安全问题! { #important-security-concerns }

您的 PAT 将自动继承用户拥有的所有权限和授权。 因此,根据您打算使用令牌的方式,限制授予令牌的访问权限极为重要。 请参阅 配置您的令牌 部分。

如果您只想让令牌访问服务器的某一特定部分,建议您创建一个新的专用用户,并只分配您希望它访问的角色/权限。 如果您只想让令牌访问服务器的一个狭窄且特定的部分,建议您创建一个新的专用用户,并只分配您希望它访问的角色/权限。

创建令牌¶

要创建新的 PAT,您有两个选择:

A. 在账户个人资料页面的用户界面上创建令牌。

B. 通过 API 创建令牌。¶

A. 在账户页面上创建令牌 { #a-creating-a-token-on-the-account-page } * 使用用户名和密码登录,进入个人资料页面 (点击右上角,从下拉菜单中选择 "编辑个人资料")。 在用户配置文件页面,从左侧菜单中选择 "个人访问令牌"。 现在您应该在 "管理个人访问令牌" 页面上看到 文本:"您没有任何有效的个人访问令牌"。 点击 "生成新令牌" 创建新令牌。 弹出 "生成新令牌" 窗口,为您提供两种选择: * 1. 服务器/脚本上下文 { #1-serverscript-context }

"该类型用于不会被浏览器访问的集成和脚本"。¶

如果您计划在应用、脚本或类似文件中使用令牌,则应选择此类型。

2. 浏览器上下文¶

"这种类型适用于将通过 Web 浏览器访问的应用,如公共门户网站"。

如果您需要在网页上链接到 DHIS2,或嵌入 iframe, 这可能就是您需要的令牌类型。

配置令牌¶

选择需要的令牌类型后,可以为令牌配置不同的访问限制。 所谓限制,是指如何限制和缩小令牌的使用范围。 如果计划在公共环境中使用令牌,这一点至关重要, 例如,在其他网站的公共仪表板上嵌入 iframe。 由于令牌总是拥有与用户相同的访问权限/授权,因此如果您打算在公共环境中使用令牌,或者在任何您无法 100% 控制的环境中使用它,就需要特别小心。

注意:如果其他人获取了您的令牌,他们可以执行您的用户可以执行的任何操作。 无法区分使用令牌执行的操作和用户执行的其他操作。

重要:如果您打算在非安全和/或公共环境中使用 PAT 令牌,强烈建议您创建一个单独的专用用户,该用户只能拥有您希望令牌拥有的角色/权限,¶

例如,在您无法 100% 控制的 PC 或服务器上,或 "嵌入" 到另一台服务器的网页中。

限制类型 { #constraint-types }

到期时间

允许的 IP 地址

允许的 HTTP 方法¶

• 允许的 HTTP 引用来源
• 有效期 { #expiry-time }
• 到期时间用于设置令牌的有效期,默认为 30 天。过期后,令牌将直接返回 401(未授权)响应。 您可以设置任何到期时间,但我们强烈建议您根据自己的使用情况设置一个合理的过期时间。
• IP 地址 { #ip-addresses }

这是一个以逗号分隔的 IP 地址列表,用于限制令牌请求的来源。¶

重要:IP 地址验证依赖于 X-Forwarded-For 标头,该标头可能被伪造。 为了安全起见,请确保负载平衡器或反向代理会覆盖该标头。

HTTP 方法¶

以逗号分隔的 HTTP 方法列表,您希望令牌能够使用这些方法。 如果您只需要令牌来查看数据,而不是修改或删除数据,那么只选择 GET HTTP 方法 是合理的。

HTTP 引用来源 { #http-referrers }

HTTP 引用来源是添加到请求中的一个标头,当您点击链接时,它会显示您点击链接时所在的网站/页面。¶

点击此处了解有关 HTTP 引用来源头的更多信息: https://en.wikipedia.org/wiki/HTTP_referer

这可用于限制使用嵌入到其他网站页面上的 "公共" 令牌。 确保引用来源标头与网站主机名相匹配,有助于避免令牌被滥用, 例如,如果有人在公共论坛上发布令牌。

重要:这不是一项安全功能。Referer 标头很容易被欺骗。¶

此设置旨在阻止未经授权的第三方开发人员连接 到公共访问实例。

保存令牌 { #saving-a-token }

完成令牌配置后,点击弹出窗口右下方的 "生成新令牌" 按钮保存。 这样,令牌将被保存,并在服务器上生成一个秘密令牌密钥。 新的密钥将显示在 PAT 令牌列表底部,背景为绿色 和文本 "新创建的令牌"。 秘密令牌密钥的外观与此类似:

d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

重要:生成的秘密令牌密钥只会显示一次,因此请务必¶

现在就复制令牌密钥,并将其保存在安全的地方,以便以后使用。 秘密令牌密钥将在服务器上安全散列,只有该秘密令牌密钥的散列才会保存到数据库中。 这样做的目的是在有人未经授权访问数据库时,最大限度地减少安全影响。 这与处理密码的方式类似。

使用应用项目接口{ #creating-a-token-with-the-api } 创建令牌 示例说明如何使用 API 创建新的个人访问令牌:

POST /api/apiToken
Content-Type: application/json
Authorization: Basic admin

{}

注意:记住请求体中的空 JSON 主体 ({})!¶

这将返回一个包含类似令牌的响应:

{
  "httpStatus": "已创建",
  "httpStatusCode": 201,
  "status": "正常",
  "response": {
     "responseType": "ApiTokenCreationResponse",
     "key": "d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092",
     "uid": "jJYrtIVP7qU",
     "klass": "org.hisp.dhis.security.apikey.ApiToken",
     "errorReports": []
  }
}

令牌本身由三部分组成:

前缀: (d2pat_) 表示这是什么类型的令牌。

随机字节 Base64 编码: (5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ)

CRC32 校验和:(1151814092) 校验和部分以 0 填充,因此长度始终为 10 个字符。 1. 使用 API { #configure-token-with-the-api } 配置令牌 2. 要更改令牌上的任何限制条件,可发出以下 HTTP API 请求。 3. 注意:创建令牌后,只能修改约束条件。

```bash¶

PUT /api/apiToken/jJYrtIVP7qU Content-Type: application/json Authorization: Basic admin

```json
{
  "version": 1,
  "type": "PERSONAL_ACCESS_TOKEN",
  "expires": 163465349603200,
  "attributes": [
      {
        "type": "IpAllowedList",
        "allowedIps": ["192.168.0.1"]
      },
      {
        "type": "MethodAllowedList",
        "allowedMethods": ["GET"]
      }
  ]
}

使用个人访问令牌 { #using-a-personal-access-token }

要使用新创建的令牌发出请求,请使用相应的授权标头 。授权标头格式如下:

Authorization: ApiToken [YOUR_SECRET_API_TOKEN_KEY]

例如:¶

GET /api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

删除个人访问令牌{ #deleting-a-personal-access-token }

方案

DELETE /api/apiToken/jJYrtIVP7qU
Content-Type: 应用项目/json
授权:ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

OAuth2¶

DHIS2支持* OAuth2 身份验证协议。OAuth2是开放的 授权标准,允许第三方客户端代表DHIS2用户进行连接,并为对Web API的后续请求获取*bearer token。DHIS2不支持细粒度 OAuth2角色,而是根据用户角色提供应用访问权限,基于 DHIS2用户的身份。

您要允许其使用OAuth 2身份验证的每个客户端都必须 在DHIS2中注册。要添加新的OAuth2客户端,请转到应用>设置> OAuth2客户端。 在用户界面中,单击*添加新*,然后输入所需的客户端名称和授权类型。

创建客户端¶

可以通过Web API添加OAuth2客户端。例如,我们可以 发送这样的有效载荷:

{
  "name": "OAuth2 Demo Client",
  "cid": "demo",
  "secret": "1e6db50c-0fee-11e5-98d0-3c15c2c6caf6",
  "grantTypes": [
    "password",
    "refresh_token",
    "authorization_code"
  ],
  "redirectUris": [
    "http://www.example.org"
  ]
}

可用以下命令发送有效负载:¶

SERVER="https://play.dhis2.org/dev"
curl -X POST -H "Content-Type: application/json" -d @client.json
  -u admin:district "$SERVER/api/oAuth2Clients"

该客户端将作为下一个授权类型示例的基础。

授权类型:密码 { #webapi_oauth2_password }

所有授权类型中最简单的是*password*授权类型。这 种授权类型类似于基本身份验证,因为它 要求客户端收集用户的用户名和密码。作为 示例,我们可以使用我们的演示服务器:

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"

curl -X POST -H "Accept: application/json" -u demo:$SECRET "$SERVER/uaa/oauth/token"
  -d grant_type=password -d username=admin -d password=district

这将给您类似的响应:¶

{
  "expires_in": 43175,
  "scope": "ALL",
  "access_token": "07fc551c-806c-41a4-9a8c-10658bd15435",
  "refresh_token": "a4e4de45-4743-481d-9345-2cfe34732fcc",
  "token_type": "bearer"
}

现在,我们将专注于access_token,这就是我们 将用作身份验证(承载)令牌的内容。例如,我们将获取 使用我们的令牌访问所有数据元素:

SERVER="https://play.dhis2.org/dev"
curl -H "Authorization: Bearer 07fc551c-806c-41a4-9a8c-10658bd15435" "$SERVER/api/33/dataElements.json"

授权类型:refresh_token { #webapi_refresh_token }

通常,访问令牌的有效性有限。您可以查看 上一个示例中响应的expires_in属性, 了解令牌何时到期。要获得新的access_token,您 可以再次访问服务器并使用refresh_token, 这允许您获得更新的令牌而无需要求 再次使用用户凭据。

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"
REFRESH_TOKEN="a4e4de45-4743-481d-9345-2cfe34732fcc"

curl -X POST -H "Accept: application/json" -u demo:$SECRET "$SERVER/uaa/oauth/token"
  -d "grant_type=refresh_token" -d "refresh_token=$REFRESH_TOKEN"

响应与获得令牌开始时的响应完全相同。¶

授权类型:authorization_code { #webapi_authorization_code }

如果您不想在外部存储用户凭据,建议使用授权码授权类型。 它允许DHIS2直接从用户收集用户名/密码,而不是由客户端 收集,然后代表用户进行身份验证。请注 意这种方法使用了客户端有效载荷中的redirectUris部分。

第 1 步:使用 Web 浏览器访问以下 URL。如果您有多个 重定向 URI,可能需要添加 &redirect_uri=http://www.example.org 到 URL:

```bash¶

SERVER="https://play.dhis2.org/dev" $SERVER/uaa/oauth/authorize?client_id=demo&response_type=code

第 2 步:在用户成功登录并接受您的
客户端访问后,它将重定向回您的重定向 URI,如下所示:

    http://www.example.org/?code=XYZ

第 3 步:这一步类似于我们在密码授权类型中所做的,
使用获得的代码,我们现在将请求访问令牌:

```bash
SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"

curl -X POST -u demo:$SECRET -H "Accept: application/json" $SERVER/uaa/oauth/token
-d "grant_type=authorization_code" -d "code=XYZ"

错误和信息消息 { #webapi_error_info_messages }

Web API 使用统一的格式返回所有错误/警告和 信息性消息:

{
  "httpStatus": "Forbidden",
  "message": "You don't have the proper permissions to read objects of this type.",
  "httpStatusCode": 403,
  "status": "ERROR"
}

在这里,我们可以看到用户试图访问一个¶

无法访问的资源。它使用了 HTTP 状态代码 403、HTTP 状态信息 forbidden 和描述性消息。

WebMessage 属性

名称

描述

httpStatus

例如,如果要表达 2014 年 3 月 20 日,必须使用¶

2014-03-20。

下表描述了期间格式(也可通过 API 端点/api/periodTypes获取)

期间格式

期间类型

格式

示例

周期类型{ #webapi_period_types }¶

DHIS2 中可用的经期类型可从以下 资源中查阅：

GET /api/periodTypes

支持 fields 查询参数，默认包含所有字段。

表：周期类型的属性

响应中的一个条目如下所示：

{
  "name": "FinancialFeb",
  "displayName": "财政年度（2月）",
  "isoDuration": "P1Y",
  "isoFormat": "yyyyFeb",
  "frequencyOrder": 365,
  "label": null,
  "displayLabel": null
}

自定义周期类型标签{ #webapi_period_type_label }¶

周期类型可以设置自定义标签，这允许您在 各个客户端应用程序中重命名该周期类型，例如将 财政 年度（2月） 显示为 学年（2月）。客户端应用程序应 渲染 displayLabel，若未设置自定义标签，则 回退到 displayName。

周期类型是预定义的，无法创建或删除，因此不支持 POST 和 DELETE 请求。label 属性是唯一可写入的属性； 所有其他属性均为不可变的，如果它们包含在 请求正文中，将被忽略。

要设置标签，请发送一个PUT请求，其中包含要更新的周期类型的name 以及新的label。周期类型通过请求正文中的name来标识， 而非通过路径参数：

PUT /api/periodTypes

{
  "name": "FinancialFeb",
  "label": "学年（2月）"
}

请求成功时返回：

{
  "status": "OK",
  "message": "FinancialFeb 已成功更新。"
}

此时将返回一个同时设置了 label 和 displayLabel 的周期类型：

{
  "name": "FinancialFeb",
  "displayName": "财政年度（2月）",
  "isoDuration": "P1Y",
  "isoFormat": "yyyyFeb",
  "frequencyOrder": 365,
  "label": "学年（2月）",
  "displayLabel": "学年（2月）"
}

要删除自定义标签，请将 label 设置为 null：

{
  "name": "FinancialFeb",
  "label": null
}

空字符串同样被接受，并且也会阻止自定义标签 显示。 请注意，该值将按原样存储，因此 label 此时 返回值为 "" 而非 null，而 displayLabel 在两种 情况下均为 null。因此，发送 null 是将周期类型恢复到 原始无标签状态的方法。

由于标签是直接从请求正文中提取的，因此如果请求 中完全省略了 label，该标签也会被清除。

如果请求中的 name 与现有周期类型不匹配， 则该请求将被拒绝，返回 400 Bad Request 状态码及消息 “FinancialFeb 不 存在。”。更新周期类型标签需要 ALL 权限。

名称¶

关键词

可以通过向 /api/relativePeriods/{RELATIVE_PERIOD_KEYWORD} 发送 GET 请求， 获取这些相对周期的 ISO 表示形式。

该端点支持以下参数： - startDate：表示用于计算相对时段的起始日期。格式：yyyy-MM-dd。如果未提供，则默认为今天。 - financialYearStart：应为 FINANCIAL_YEAR_FEBRUARY、FINANCIAL_YEAR_APRIL、FINANCIAL_YEAR_JULY、FINANCIAL_YEAR_AUGUST、 FINANCIAL_YEAR_SEPTEMBER、FINANCIAL_YEAR_OCTOBER 之一。若未指定，默认值为 FINANCIAL_YEAR_OCTOBER。

例如，要获取以 2021-08-15 为起始日期的相对时间段 LAST_3_MONTHS 的 ISO 表示形式，可以发送以下请求： GET /api/relativePeriods/LAST_3_MONTHS?startDate=2021-08-15

在此情况下，应答如下：

{
[
"202105",
"202106",
"202107"
]
}

这些参数会替代默认的 pe 维度:¶

用于 /analytics/events/query 的 eventDate

用于 /analytics/enrollments/query 的 enrollmentDate

• 允许在一个或多个日期字段上添加条件并将它们合并。
• 自定义日期时段的使用 { #usage-of-custom-date-periods }

在支持自定义日期时段的资源中,有一些额外的查询参数,这些参数将被组合起来,以表达时间维度上的条件。

自定义日期周期¶

事件查询资源

可以在同一查询中合并多个时间字段:

/api/analytics/events/query/...?..&eventDate=2021&incidentDate=202102&...

所有这些条件都可以与 pe 维度相结合:

/api/analytics/events/query/...?..&dimension=pe:TODAY&enrollmentDate=2021&incidentDate=202102&...

支持的格式见上文 "日期和期间格式"。还提供了一种额外的格式来表达一系列日期:yyyyMMdd_yyyyMMdd 和 yyyy-MM-dd_yyyy-MM-dd。

在下面的示例中,端点将返回计划在 20210101 和 20210104 之间发生的事件:

/api/analytics/events/query/...?..&dimension=pe:TODAY&enrollmentDate=2021&incidentDate=202102&scheduledDate=20210101_20210104&...

当局 { #authorities }

所有可用的系统授权都可以通过以下端点列出其标识符和名称:

GET /api/authorities¶

返回格式如下:

{
  "systemAuthorities": [
    {
      "id": "ALL",
      "name": "ALL"
    },
    {
      "id": "F_ACCEPT_DATA_LOWER_LEVELS",
      "name": "Accept data at lower levels"
    }
  ]
}

元数据 { #webapi_metadata }

标识符方案 { #webapi_identifier_schemes }