如何使用DHIS2 Web API与R填充DHIS2数据集

1. 准备依赖包 #

R中处理DHIS2 API需要用到httr（发送HTTP请求）和jsonlite（处理JSON数据），先安装并加载：

install.packages(c("httr", "jsonlite"))
library(httr)
library(jsonlite)

2. 获取关键ID信息 #

DHIS2的API操作依赖各类实体的ID，需要先获取以下几个核心ID：

2.1 获取组织单位ID（Rosinor CHP） #

发送GET请求查询组织单位，过滤名称定位目标：

# DHIS2演示服务器基础URL
base_url <- "https://play.dhis2.org/2.38nightly/api"

# 查询组织单位
org_units <- GET(
  paste0(base_url, "/organisationUnits"),
  query = list(filter = "name:eq:Rosinor CHP", fields = "id,name"),
  authenticate("admin", "district")
) %>% content(as = "text") %>% fromJSON()

# 提取ID
rosinor_chp_id <- org_units$organisationUnits$id[1]

2.2 获取数据集ID（HIV儿科月度汇总） #

同理查询数据集：

datasets <- GET(
  paste0(base_url, "/datasets"),
  query = list(filter = "name:eq:HIV儿科月度汇总", fields = "id,name"),
  authenticate("admin", "district")
) %>% content(as = "text") %>% fromJSON()

hiv_pediatric_id <- datasets$datasets$id[1]

2.3 获取数据元素ID（表单字段对应） #

可以通过数据集关联的dataElements获取该数据集下的所有数据元素，或者直接查询特定名称的数据元素：

# 获取数据集关联的所有数据元素
data_elements <- GET(
  paste0(base_url, "/datasets/", hiv_pediatric_id, "/dataElements"),
  query = list(fields = "id,name"),
  authenticate("admin", "district")
) %>% content(as = "text") %>% fromJSON()

# 示例：获取“新登记的HIV暴露婴儿”的ID
exposed_infant_id <- data_elements$dataElements$id[data_elements$dataElements$name == "新登记的HIV暴露婴儿"]

2.4 时期格式 #

DHIS2的时期格式为YYYYMM，2023年3月对应202303。

3. 构造数据提交Payload #

按照DHIS2 API要求的格式构造数据，核心是dataValues数组，每个元素包含数据元素ID、时期、组织单位ID、数值：

# 构造数据列表
payload <- list(
  dataValues = list(
    list(
      dataElement = exposed_infant_id,
      period = "202303",
      orgUnit = rosinor_chp_id,
      value = "15" # 示例数值
    ),
    # 可添加更多字段数据
    list(
      dataElement = "其他数据元素ID",
      period = "202303",
      orgUnit = rosinor_chp_id,
      value = "8"
    )
  )
)

# 转为JSON格式
payload_json <- toJSON(payload, auto_unbox = TRUE)

4. 发送数据到DHIS2 API #

用POST请求提交数据，注意添加认证头：

response <- POST(
  paste0(base_url, "/dataValueSets"),
  authenticate("admin", "district"),
  body = payload_json,
  content_type("application/json")
)

# 检查响应状态
if (status_code(response) == 200) {
  cat("数据提交成功！\n")
} else {
  cat("数据提交失败，响应信息：\n")
  print(content(response))
}

关键注意事项 #

• 确保使用正确的账号权限：演示服务器默认账号admin/district拥有足够权限
• 验证数据元素ID与表单字段的对应关系：可通过DHIS2前端的数据元素管理页面确认
• 提交前可先用GET请求/api/dataValueSets查询现有数据，验证ID和时期格式是否正确

内容的提问来源于stack exchange，提问作者Tumaini Kilimba