跳转至
For the complete DHIS2 documentation index, see llms.txt.
使用API

用户数

EVENT_REGISTRATION_PARSER

单个事件的注册。这用于事件项目。

SMS command types for Android

当互联网不可用时,Android应用项目可以使用这些命令类型通过SMS提交数据。 SMS由Android应用项目组成。

类型

用法

默认值 Potential duplicate status Parameter name
仅与当前用户相关联的数据视图组织单位,可退回到数据采集组织单位。 TRACKER_EVENT 跟踪器项目的事件注册。
SIMPLE_EVENT TRACKER_EVENT 关系
建立关系。 假 删除事件。
Users 假 本节介绍用户资源方法。
/api/users query users 资源提供了额外的查询参数
标准参数(例如分页)。在用户处查询用户
资源可以使用以下参数。
Table: User query parameters Parameter 类型
描述 query 文本
Query value for first name, surname, username and email, case in-sensitive. 假 文本
Query for phone number. canManage false | true
Filter on whether the current user can manage the returned users through the managed user group relationships. authSubset false | true
Filter on whether the returned users have a subset of the authorities of the current user. 假 日期
查询参数 假 数
定义要返回的页码。 Parameter 日期
定义每页返回的元素数量。 Parameter false | true
Filter on users who have self-registered their user account. invitationStatus none | all | expired

Filter on user invitations, including all or expired invitations.

欧

识别码

Filter on users who are associated with the organisation unit with the given identifier.

按标识符查询用户{ #user-query-by-identifier }

false | true

Filter on users who are associated with the organisation units linked to the currently logged in user.

includeChildren

false | true

用户查找

page

数

The page number.

通过标识符查找用户

数

The page size.

orgUnitBoundary

  • 串
  • Restrict search to users having a common organisation unit with the current user for the given boundary
  • createdBy

JSON 格式的有效载荷如下所示,其中attributes指元数据属性,groupSets指组织单位组集,dataItems指数据元素、指标、数据集和计划指标:

To retrieve all user accounts which were initially self-registered:

/api/users?selfRegistered=true

User query by identifier

用户查询

/api/users/{id}

An example for a particular identifier looks like this:

/api/users/OYLGMiazHtW
  • User lookup
  • 用户查找 API 提供了一个端点来检索用户 响应包含最少的信息集。它不需要一个 特定权限,适合客户端查询信息 例如用户名和姓氏,不会暴露潜在的敏感信息 用户信息。
  • ``` / api / userLookup 
    - updatedAtClient

User lookup by identifier

JSON 格式的有效载荷如下所示,其中`attributes `指元数据属性,`groupSets `指组织单位组集,`dataItems `指数据元素、指标、数据集和计划指标:
    GET / api / userLookup / {id} 
    用户 `id` 将与以下用户属性匹配
按照指定的顺序:

用户标识

### 用户名

用户名

请求示例如下所示:
    / api / userLookup / QqvaU7JjkUV 
    该响应将包含有关用户的最少信息。

```json
{
  "id": "QqvaU7JjkUV",
  "username": "nkono",
  "firstName": "Thomas",
  "surname": "Nkono",
  "displayName": "Thomas Nkono"
}
    User lookup query

您可以使用以下API请求向用户查询。

GET / api / userLookup?query = {string}

query 请求参数是强制性的。查询string将被匹配 针对以下用户属性:

名字

姓

电子邮件

用户名

In addition to the query parameter the search can be restricted by the orgUnitBoundary parameter as described in table of parameters for users above.

请求示例如下所示:

/ api / userLookup?query = John

响应将包含有关与请求匹配的用户的信息。

{
  "users": [
    {
      "id": "DXyJmlo9rge",
      "username": "jbarnes",
      "firstName": "John",
      "surname": "Barnes",
      "displayName": "John Barnes"
    },
    {
      "id": "N3PZBUlN8vq",
      "username": "jkamara",
      "firstName": "John",
      "surname": "Kamara",
      "displayName": "John Kamara"
    }
  ]
}

用户帐户创建和更新 { #webapi_users_create_update }

通过 API 支持创建和更新用户。一个基本的 创建用户的有效负载类似于以下示例。注意密码 将以纯文本形式发送,因此请记住为网络传输启用 SSL/HTTPS。

{
  "id": "Mj8balLULKp",
  "firstName": "John",
  "surname": "Doe",
  "email": "johndoe@mail.com",
  "userCredentials": {
    "id": "lWCkJ4etppc",
    "userInfo": {
    "id": "Mj8balLULKp"
  },
  "username": "johndoe123",
  "password": "Your-password-123",
  "skype": "john.doe",
  "telegram": "joh.doe",
  "whatsApp": "+1-541-754-3010",
  "facebookMessenger": "john.doe",
  "avatar": {
    "id": "<fileResource id>"
  },
  "userRoles": [
    {
      "id": "Ufph3mGRmMo"
    }
  ]
  },
  "organisationUnits": [
    {
      "id": "Rp268JB6Ne4"
    }
  ],
  "userGroups": [
    {
      "id": "wl5cDMuUhmF"
    }
  ]
}
  • ```bash curl -X POST -d @u.json "http://server/api/33/users" -u user:pass -H "Content-Type: application/json" 
      - 在用户创建负载中,仅在导入时支持用户组
或一次*发布*一个用户。如果您尝试创建多个
user 在指定用户组时,您将不会收到错误,并且
将创建用户,但不会分配用户组。这是设计使然
并且由于用户和用户之间的多对多关系而受到限制
用户组,其中用户组是关系的所有者。更新
或者创建多个用户和他们的用户组,考虑一个项目来*POST*
一次一个,或 *POST* 所有用户,然后执行另一个操作
在指定新用户的标识符的同时更新他们的用户组。

  - When creating a user the payload may also contain user settings.
These are added as `settings` object to the root object.
Each key-value pair becomes a member in the `settings` object, for example:
    ```json
{
    "id": "Mj8balLULKp",
    "firstName": "John",
    "surname": "Doe",
    "settings": {
        "keyUiLocale": "de"
    },
    //...
}

创建用户后,Location 标头与 新生成的 ID(你也可以使用 /api/system/id 提供你自己的 端点)。然后可以使用相同的有效负载进行更新,但请记住 然后使用 PUT 而不是 POST 并且端点现在是/api/users/ID。

```bash

curl -X PUT -d @u.json "http://server/api/33/users/ID" -u user:pass -H "Content-Type: application/json" 

有关可用的全部有效负载的更多信息,请参见`/ api / schemas / user`。

有关上传和检索用户头像的更多信息,请参阅
`/fileResources` 端点。

用户帐户邀请 { #webapi_user_invitations } 
The Web API supports inviting people to create user accounts through the
`invite` resource. To create an invitation you should POST a user in XML
or JSON format to the invite resource. A specific username can be forced
by defining the username in the posted entity. By omitting the username,
the person will be able to specify it herself. The system will send out
an invitation through email. This requires that email settings have been
properly configured.

邀请资源可用于安全地
允许人们在其他人不知道密码的情况下创建帐户
或通过以纯文本形式传输密码。用于的有效载荷
邀请与创建用户相同。 JSON 格式的示例负载
看起来像这样:


### ```json
{
  "firstName": "John",
  "surname": "Doe",
  "email": "johndoe@mail.com",
  "userCredentials": {
    "username": "johndoe",
    "userRoles": [{
      "id": "Euq3XfEIEbx"
    }]
  },
  "organisationUnits": [ {
    "id": "ImspTQPwCqd"
  } ],
  "userGroups": [ {
    "id": "vAvEltyXGbD"
  }]
}

用户邀请实体可以这样发布:

curl -d @invite.json "localhost/api/33/users/invite" -u admin:district
  -H "Content-Type:application/json"

要同时向多个用户发送邀请,您必须使用 格式略有不同。对于 JSON:

{
  "users": [ {
    "firstName": "John",
    "surname": "Doe",
    "email": "johndoe@mail.com",
    "userCredentials": {
      "username": "johndoe",
      "userRoles": [ {
        "id": "Euq3XfEIEbx"
      } ]
    },
    "organisationUnits": [ {
      "id": "ImspTQPwCqd"
      } ]
    }, {
    "firstName": "Tom",
    "surname": "Johnson",
    "email": "tomj@mail.com",
    "userCredentials": {
      "userRoles": [ {
        "id": "Euq3XfEIEbx"
      } ]
    },
    "organisationUnits": [ {
      "id": "ImspTQPwCqd"
      } ]
    }
  ]
}

The Web API supports inviting people to create user accounts through the invite resource. To create an invitation you should POST a user in XML or JSON format to the invite resource. A specific username can be forced by defining the username in the posted entity. By omitting the username, the person will be able to specify it herself. The system will send out an invitation through email. This requires that email settings have been properly configured.

curl -d @invites.json "localhost/api/33/users/invites" -u admin:district
  -H "Content-Type:application/json"

发送用户账号邀请有一定的要求

出去: 电子邮件SMTP服务器必须在服务器上正确配置。

被邀请的用户必须指定了有效的电子邮件。

如果指定了用户名,则它不得已被其他人使用

现有用户。

如果不满足这些要求中的任何一个,邀请资源将返回

带有 409 Conflict 状态代码和描述性消息。

User login (Experimental) { #webapi_user_login }

该端点不用于外部使用,除非你正在实施一个自定义登录应用项目,除非你有非常好的理由,否则你可能不应该这样做。

A user can log in and get a session cookie with the following example:
POST /api/auth/login
with JSON body:

```json

{ "username": "username", "password": "password", "twoFactorCode": "two_factor_code" }

Successful response looks like:  

```json
{
    "loginStatus": "SUCCESS",
    "redirectUrl": "/dhis-web-dashboard/"
}

User account confirm invite (Experimental) { #webapi_user_confirm_invite }

> Important

Before confirming an invitation, an admin user should have set up the User and sent an invitation link. That prerequisite also adds some required data in the userinfo database table (idToken, restoreToken, restoreExpiry) for that user, in order to complete the invite.

A user can confirm an invitation through the following endpoint:
POST /api/auth/invite
with JSON body:

{
    "username": "TestUser",
    "firstName": "Test",
    "surname": "User",
    "password": "Test123!",
    "email": "test@test.com",
    "phoneNumber": "123456789",
    "g-recaptcha-response": "recaptchaResponse",
    "token": "aWRUb2tlbjpJRHJlc3RvcmVUb2tlbg=="
}

Note
The g-recaptcha-response value would be populated through the use of the core Login App UI normally.
The token field expects a Base64-encoded value. In this example, decoded, it's idToken:IDrestoreToken. This would be sent by email to the invited user (it is actually created internally (and populated in the database) during the /api/users/invite operation).

Successful response looks like: 

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "message": "Account updated"
}

User account registration (Experimental) { #webapi_user_registration }

A user can register directly through the following endpoint:

POST /api/auth/registration with JSON body: 

{
    "username": "testSelfReg",
    "firstName": "test",
    "surname": "selfReg",
    "password": "P@ssword123",
    "email": "test@test.com",
    "phoneNumber": "12345oooo",
    "g-recaptcha-response": "recap response"
}

A successful response looks like: 

{
    "httpStatus": "Created",
    "httpStatusCode": 201,
    "status": "OK",
    "message": "Account created"
}

User forgot password (Experimental)

This endpoint is used to trigger the forgotten password flow. It can be triggered by supplying the username or email of the user whose password needs resetting.
POST /api/auth/forgotPassword with JSON body: 

{
    "emailOrUsername": "testUsername1"
}

A successful response returns an empty 200 OK. This should trigger an email to be sent to the user which allows them to reset their password.

User password reset (Experimental) { #webapi_user_password_reset }

Once a user has received an email with a link to reset their password, it will contain a token which can be used to reset their password.
POST /api/auth/passwordReset with JSON body:

```json

{ "newPassword": "ChangeMe123!", "resetToken": "token-value-from-email-link" } 

A successful response returns an empty `200 OK`. The user should now be able to log in using the new password.

用户复制 { #webapi_user_replication }

要复制用户,您可以使用 *replica* 资源。复制一个
用户在调试或重现报告的问题时很有用
特定用户。您需要提供新的用户名和密码
您稍后将用于验证的复制用户。请注意,您
需要 ALL 权限才能执行此操作。要复制用户,您
可以发布如下所示的 JSON 有效负载:

```json
{
  "username": "user_replica",
  "password": "SecretPassword"
}

此有效负载可以发布到您提供的副本资源 要在 URL 中复制的用户标识符:

用户数据批准工作流程

使用curl复制用户的示例如下所示:

curl -d @replica.json "localhost/api/33/users/N3PZBUlN8vq/replica"
  -H "Content-Type:application/json" -u admin:district

在连接到同一身份供应商账户的用户账户之间切换{ #switching-between-user-accounts-connected-to-the-same-identity-provider-account }

User administrators (with appropriate rights) can reset another user's account by triggering password recovery. Once triggered an email is sent to the user containing a recovery link. Users following the link get to a form which allows to set a new password.

To trigger this workflow for user tH7WIiIJ0O3 use:

POST /api/37/users/tH7WIiIJ0O3/reset

禁用和启用用户帐户 { #webapi_user_disable }

可以将用户帐户标记为禁用。 禁用的用户无法再登录。

要将具有UIDtH7WIiIJ0O3的用户标记为已禁用(需要具有适当权限的用户):

POST / api / 36 / users / tH7WIiIJ0O3 / disabled

要再次启用禁用的用户,请相应地使用(要求具有适当权限的用户):

POST / api / 36 / users / tH7WIiIJ0O3 / enabled

用户有效期 { #webapi_user_expiration }

可以为用户帐户设置到期日期。 它标记了用户帐户已过期的时间点 并且无法再使用。过期的用户无法再登录。

To update the expiration date of user with UID tH7WIiIJ0O3 and set it to the date 2021-01-01 use (requires user with appropriate rights):

POST / api / 36 / users / tH7WIiIJ0O3 / expired?date = 2021-01-01

取消设置到期日期,以使帐户永不过期 相应地使用(需要具有适当权限的用户):

POST / api / 36 / users / tH7WIiIJ0O3 /未过期

User data approval workflows

要查看用户可以访问哪些数据批准工作流和级别, 您可以按以下方式使用* dataApprovalWorkflows *资源:

GET / api / users / {id} / dataApprovalWorkflows

Switching between user accounts connected to the same identity provider account

If linked accounts are enabled in dhis.conf and a user has logged in via OIDC, then it is possible for the user to switch between DHIS2 accounts that are linked to the same identity provider account using this API call:

GET /dhis-web-commons-security/logout.action?current={current_username}&switch={username_to_switch_to}

This has the effect of signing out the current user and signing in the new user. It looks seamless as it is happening, except that the new user ends up on the default page of the DHIS2 instance.

Note that this API call will likely change in the future, but its general function will remain the same.

To see a list of users that can be switched to, use this API call: