For the complete DHIS2 documentation index, see llms.txt.

总览¶

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

介绍¶

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

基本构建块称为*资源*。资源可以是任何暴露在 Web 上的东西，从文档到业务流程 - 客户可能想要与之交互的任何内容。可以检索或交换资源的信息方面通过资源*表示*。表示是一个视图资源代表了汇总数据的可视化,可用于一组特定的参数。该资源可以以一组特定的参数。该资源可以在所有资源都可以通过 URI(也称为
所有资源都可以由 URI 唯一标识（也称为作为 URL）。所有资源都有一个默认表示。你可以通过以下方式表明您对特定表示感兴趣提供 Accept HTTP 标头、文件扩展名或格式或在请求 URL 中添加 .csv 或 ?format=csv。分析数据回复时，您可以提供 Accept: application/csv （接受：应用程序/csv）。动词。这意味着对于资源,您必须在想要检索它时发出 GET
与 API 的交互需要正确使用 HTTP 方法或动词。这意味着对于资源，您必须发出 GET 当你想要检索它时请求，当你想要时 POST 请求要创建一个，* PUT （当您要更新时）， DELETE *（当您要删除时）基本身份验证

认证方式¶

OAuth 2

验证并获取当前已认证用户的信息。
GET /api/me
获取当前已通过身份验证用户的授权列表。

您可以通过向以下 URL 发送 GET 请求，验证并获取当前已通过身份验证的用户的信息：

/ api / 33 / me

以及有关权限的更多信息（如果用户有特定的权限）通过使用端点：

/ api / 33 / me / authorities
/ api / 33 / me / authorities / ALL

基本认证¶

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 }

A.在账户页面上创建令牌{ #a-creating-a-token-on-the-accounts-page }¶

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

1.服务器/脚本上下文：{ #1-serverscript-context }¶

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

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

2.浏览器上下文：{ #2-browser-context }¶

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

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

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

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

限制类型 { #constraint-types }

到期时间

允许的 IP 地址

不同的约束类型如下：¶

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

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

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

允许的 IP 地址{ #allowed-ip-addresses }¶

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

HTTP 引用来源 { #http-referrers }

允许的 HTTP 方法{ #allowed-http-methods }¶

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

允许的 HTTP 引用项目{ #allowed-http-referrers }¶

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

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

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

保存令牌：{ #saving-your-token }¶

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

d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

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

{}

B.通过 API 创建令牌{ #b-creating-a-token-via-the-api }¶

示例说明如何使用 API 创建新的个人访问令牌：

POST https://play.dhis2.org/dev/api/apiToken
Content-Type: application/json
Authorization: Basic admin district

{}

注意:令牌密钥只会在此响应中显示一次。您需要将其复制并保存在安全的地方,以便以后使用!

令牌本身由三部分组成:

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

重要：令牌密钥只会在此回复中显示一次。您需要将其复制并保存在安全的地方，以便以后使用！

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

通过应用项目接口配置令牌：{ #configure-your-token-via-the-api }¶

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

注意：创建令牌后只能修改约束条件！

PUT https://play.dhis2.org/dev/api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: Basic admin district

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

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

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

Authorization: ApiToken [YOUR_SECRET_API_TOKEN_KEY]

举例：

GET https://play.dhis2.org/dev/api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

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

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

DELETE https://play.dhis2.org/dev/api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

创建客户端¶

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

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

使用Web API添加客户端¶

可以通过 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"

我们将使用此客户端作为下一个赠款类型示例的基础。

授权类型密码¶

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

名称	描述
此响应的 HTTP 状态代码,更多信息请参见 RFC 2616(第 10 节)。	status
DHIS2状态,可能的值为OK、WARNING 或 ERROR,其中`OK`表示一切顺利,`ERROR`表示操作未完成,`WARNING`表示操作部分成功,如果消息包含`response`属性,请在那里查找更多信息。	message
用户友好型消息,说明操作是否成功。	DHIS2状态，可能的值为OK
技术性更强、对开发人员更友好的消息(目前尚未使用)。	response
`WebMessage`格式未来扩展的扩展点。	日期和期间格式 { #webapi_date_period_format }
在整个 Web API 中,我们会引用日期和期间。日期格式
如下:	`WebMessage`格式未来扩展的扩展点。

日期和期间格式¶

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

年-月-日

例如，如果您想表达 2014 年 3 月 20 日，则必须使用 2014-03-20。

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

示例

描述	格式	例	描述
周	yyyyWn	20040315	2004W10
2004 年第 10 周	周三开始的周	yyyyWedWn	2015WedW5
第 5 周,周三开始	周四开始的周	yyyyThuWn	2015ThuW6
第 6 周,周四开始	周六开始的周	2015年第6周星期四	2015SatW7
第 7 周,周六开始	yyyySatWn	yyyySunWn	2015SunW8
第 8 周,周日开始	双周	yyyyBiWn	2015BiW1
2015 年第 1-2 周	月份	yyyyMM	2004 年 3 月
双月	yyyyMMB	200403	200401B
2004 年 1-2 月	季度	yyyyQn	2004Q1
2004 年 1-3 月	六个月	yyyySn	2004S1
2004 年 1 月至 6 月	4月开始的六个月	yyyyAprilSn	2004AprilS1
2004 年 4 月至 9 月	年份	yyyy	2004 年
4月开始的财政年度	yyyyApril	2004	2004
2004April	2004 年 4 月至 2005 年 3 月	7月开始的财政年度	yyyyJuly
2004July	2004 年 7 月至 2005 年 6 月	10月开始的财政年度	yyyyOct
2004Oct	2004 年 10 月至 2005 年 9 月	相对时期 { #webapi_date_relative_period_values }	在应用项目接口的某些部分,如分析资源,您可以
除固定时间段(如上定义)外,还可以使用相对时间段。
相对时间段是相对于当前日期而言的,可用于创建动态报告等。
创建动态报告。可用的相对周期值如下表所示
如下表所示。

相对时期¶

在 API 的某些部分，例如分析资源，您可以除了固定期间（如上定义）之外，还使用相对期间。相对期间是相对于当前日期并允许例如用于创建动态报告。可用的相对期间值是：

THIS_WEEK, LAST_WEEK, LAST_4_WEEKS, LAST_12_WEEKS, LAST_52_WEEKS,
THIS_BIWEEK, LAST_BIWEEK, LAST_4_BIWEEKS,
THIS_MONTH, LAST_MONTH, THIS_BIMONTH, LAST_BIMONTH, THIS_QUARTER, LAST_QUARTER,
THIS_SIX_MONTH, LAST_SIX_MONTH, MONTHS_THIS_YEAR, QUARTERS_THIS_YEAR,
THIS_YEAR, MONTHS_LAST_YEAR, QUARTERS_LAST_YEAR, LAST_YEAR, LAST_5_YEARS, LAST_10_YEARS, LAST_10_FINANCIAL_YEARS, LAST_12_MONTHS, 
LAST_3_MONTHS, LAST_6_BIMONTHS, LAST_4_QUARTERS, LAST_2_SIXMONTHS, THIS_FINANCIAL_YEAR,
LAST_FINANCIAL_YEAR, LAST_5_FINANCIAL_YEARS

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

Analytics query resources support extra parameters to express periods.

用于 /analytics/enrollments/query 的 enrollmentDate

用于 /analytics/events/query 的 eventDate
用于 /analytics/enrollments/query 的 enrollmentDate

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

自定义日期周期¶

事件查询资源

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

条件可以用以下形式表示

analytics/events/query/...?..&eventDate=2021&...

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

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

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

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

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

当局 { #authorities }

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

GET /api/authorities¶

系统授权 ID 和名称可通过以下方式列出：

/api/authorities

元数据 { #webapi_metadata } 标识符方案 { #webapi_identifier_schemes }

总览¶

介绍¶