总览¶

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

介绍¶

Web API 遵循 REST 背后的许多原则 建筑风格。提一些重要的：

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

认证方式¶

DHIS2 Web API 支持三种身份验证协议：

• 基本身份验证
• 个人访问令牌 (PAT)

• OAuth 2

  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 标头。更正式的格式是:

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

基本认证¶

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

授权：基本base64encode（用户名：password）

大多数网络感知开发环境都支持 Basic 身份验证，例如 Apache HttpClient 和 Spring RestTemplate。 一个重要的注意事项是此身份验证方案不提供安全性 因为用户名和密码是以纯文本形式发送的，可以很容易地 被攻击者观察到。仅当服务器是 使用 SSL/TLS (HTTPS) 加密与客户端的通信。考虑这个 为了提供与 Web 的安全交互的硬性要求 应用程序接口。

两因素验证¶

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

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

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

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

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

创建令牌¶

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

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

B. 通过 API 创建令牌。¶

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

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

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

2. 浏览器上下文¶

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

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

配置令牌¶

"这种类型的应用程序，如公共门户网站，将使用网络浏览器访问"。

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

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

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

限制类型 { #constraint-types }

到期时间

允许的 IP 地址

允许的 HTTP 方法¶

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

这是一个以逗号分隔的 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 令牌列表底部,背景为绿色 和文本 "新创建的令牌"。 秘密令牌密钥的外观与此类似:

重要：这不是一项安全功能。参考者标头很容易被欺骗。 此设置旨在阻止未经授权的第三方开发人员连接 连接到公共访问实例。

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

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

使用应用项目接口{ #creating-a-token-with-the-api } 创建令牌

d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

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

{}

使用应用项目接口{ #creating-a-token-with-the-api } 创建令牌¶

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

POST /api/apiToken
Content-Type: 应用项目/json
授权：基本管理区

{}

令牌本身由三部分组成:

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

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

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

使用应用项目接口{ #configure-token-with-the-api } 配置令牌¶

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

PUT /api/apiToken/jJYrtIVP7qU
Content-Type: 应用项目/json
授权：Basic 管理区

{
  “版本”：1，
  “类型”：“PERSONAL_ACCESS_TOKEN”，
  “过期”：163465349603200，
  “属性”： [
      {
        "type": "IpAllowedList",
        “allowedIps”：[“192.168.0.1”]
      },
      {
        "type": "方法允许列表",
        “允许的方法”：[“GET”]
      }
  ]
}

例如:¶

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

Authorization: ApiToken [YOUR_SECRET_API_TOKEN_KEY]

例如：

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

OAuth2¶

您可以在创建 PAT 的个人资料页面的用户界面中删除 PAT、 或像这样通过应用项目接口删除：

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

创建客户端¶

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"

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

授权类型密码¶

所有授权类型中最简单的是 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¶

通常，访问令牌的有效性有限。你可以看看 在上一个示例中响应的 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¶

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

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

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

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

错误和信息消息 { #webapi_error_info_messages }

第 3 步：这一步类似于我们在密码授予类型中所做的， 使用给定的代码，我们现在将要求访问令牌：

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"

错误和信息消息¶

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 和描述性信息。

httpStatus

日期和期间格式¶

在整个 Web API 中，我们指的是日期和期间。日期格式 是：

期间格式

期间类型

下表描述了期间格式（也可在 API 端点/api/periodTypes)

示例

相对时期¶

在应用项目接口的某些部分，如分析资源，您可以 除固定时间段（如上定义）外，还可以使用相对时间段。 相对时间段是相对于当前日期而言的，可用于创建动态报告等。 创建动态报告。可用的相对周期值如下表所示 如下表所示。

可以通过以下方式检索这些相对周期的 ISO 表示法 向 /api/relativePeriods/{RELATIVE_PERIOD_KEYWORD} 提出 GET 请求。

该终端支持以下参数： - startDate"（开始日期）： 代表计算相对周期的起始日期。格式为yyyyy-MM-dd`。如果没有提供，默认为今天。 - 财务年度起始"：应为 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 表示值，可以发出以下请求 的 ISO 表示，可以发出以下请求： GET /api/relativePeriods/LAST_3_MONTHS?startDate=2021-08-15

在这种情况下的回答是

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

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

用于 `/analytics/events/query` 的 `eventDate`

用于 `/analytics/enrollments/query` 的 `enrollmentDate`

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

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

#### 自定义日期周期

事件查询资源

| 注册查询资源 | `eventDate`  | [x] |
|--------------------|------------------------|---------------------------|
| [ ]        | `lastUpdated`                    | [x]                       |
| [x]   | `lastUpdated`                    | `lastUpdated`                       |
| [ ]    | `lastUpdated`                    | [x]                       |
| [x]     | `lastUpdated`                    | `lastUpdated`                       |
| [x]      | `lastUpdated`                    | `lastUpdated`                       |

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

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

返回格式如下:

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

元数据 { #webapi_metadata }

标识符方案 { #webapi_identifier_schemes }