用户数¶

用户数¶

本节介绍用户资源方法。

/api/用户

用户查询¶

users 资源提供了额外的查询参数 标准参数（例如分页）。在用户处查询用户 资源可以使用以下参数。

表：用户查询参数

以“konan”作为名字或姓氏的最多 10 个用户的查询（案例 不敏感）与当前相比拥有部分权限的人 用户：

/api/users?query=konan&authSubset=true&pageSize=10

要检索最初自行注册的所有用户帐户：

/api/users?selfRegistered=true

用户按标识符查询¶

您可以使用以下语法检索具有特定标识符的用户的完整信息。

/api/users/{id}

特定标识符的示例如下所示：

/api/users/OYLGMiazHtW

用户查找¶

用户查找 API 提供了一个端点来检索用户 响应包含最少的信息集。它不需要一个 特定权限，适合客户端查询信息 例如用户名和姓氏，不会暴露潜在的敏感信息 用户信息。

/ api / userLookup

用户查找端点有两种方法。

通过标识符查找用户¶

您可以使用以下API请求按标识符进行用户查找。

GET / api / userLookup / {id}

用户 id 将与以下用户属性匹配 按照指定的顺序：

• 用户标识
• 用户名
• 用户名

请求示例如下所示：

/ api / userLookup / QqvaU7JjkUV

该响应将包含有关用户的最少信息。

{
  "id": "QqvaU7JjkUV",
  "username": "nkono",
  "firstName": "Thomas",
  "surname": "Nkono",
  "displayName": "Thomas Nkono"
}

用户查询¶

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

GET / api / userLookup？query = {string}

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

• 名字
• 姓
• 电子邮件
• 用户名

除 query 参数外，还可通过 orgUnitBoundary 参数限制搜索，如上文用户参数表所述。 orgUnitBoundary "参数限制搜索，如上文用户参数表所述。

请求示例如下所示：

/ 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"
    }
  ]
}

用户帐户创建和更新¶

通过 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"
    }
  ]
}

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

在用户创建负载中，仅在导入时支持用户组 或一次*发布*一个用户。如果您尝试创建多个 user 在指定用户组时，您将不会收到错误，并且 将创建用户，但不会分配用户组。这是设计使然 并且由于用户和用户之间的多对多关系而受到限制 用户组，其中用户组是关系的所有者。更新 或者创建多个用户和他们的用户组，考虑一个程序来*POST* 一次一个，或 POST 所有用户，然后执行另一个操作 在指定新用户的标识符的同时更新他们的用户组。

创建用户时，有效载荷还可能包含用户设置。 这些设置将作为 settings 对象添加到根对象中。 例如，每个键值对都会成为settings对象中的一个成员： User lookup query

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

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

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

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

用户帐户邀请¶

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 格式的示例负载 看起来像这样：

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

要创建多个邀请，您可以将有效负载发布到 api/users/invites 资源如下：

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

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

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

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

• 如果指定了用户名，则它不得已被其他人使用 现有用户。

如果不满足这些要求中的任何一个，邀请资源将返回 带有 409 Conflict 状态代码和描述性消息。

用户登录（试验性）{ #webapi_user_login }¶

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

用户可以通过以下示例登录并获取会话 cookie：
POST /api/auth/login
正文为JSON：

用户帐户邀请 { #webapi_user_invitations } 成功的答复是这样的

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

用户账户确认邀请（试验性）{ #webapi_user_confirm_invite }¶

重要
在确认邀请之前，管理员用户应设置用户并发送邀请链接。为了完成邀请，该前提条件还会在 userinfo 数据库表中为该用户添加一些必要的数据（idToken, restoreToken, restoreExpiry）。

用户可以通过以下端点确认邀请：
POST /api/auth/invite
并附带 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"
      } ]
    }
  ]
}

成功的答复是这样的

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

用户账户注册（试验性）{ #webapi_user_registration }¶

用户可通过以下端点直接注册：
POST /api/auth/registration 带有 JSON 主体：

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

成功的答复是这样的

现有用户。

用户忘记密码（试验性）{ #webapi_user_forgot_password }¶

User login (Experimental) { #webapi_user_login }

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

成功响应会返回空的 200 OK。这将触发一封电子邮件发送给用户，允许他们重置密码。

用户密码重置（试验性）{ #webapi_user_password_reset }¶

Successful response looks like:

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

成功响应将返回空的 200 OK。现在用户应该可以使用新密码登录了。

用户复制¶

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

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

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

/ api / 33 / users / <uid> /副本

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

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

重置用户密码{ #webapi_user_reset }¶

用户管理员（拥有适当权限）可通过触发密码恢复来重置其他用户的账户。 触发密码恢复。一旦触发，就会向用户发送一封电子邮件 包含一个密码恢复链接。用户通过链接进入一个表单，可以 设置新密码。

To trigger this workflow for user tH7WIiIJ0O3 use:

POST /api/37/users/tH7WIiIJ0O3/reset

禁用和启用用户帐户¶

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

要将具有UIDtH7WIiIJ0O3的用户标记为已禁用（需要具有适当权限的用户）：

POST / api / 36 / users / tH7WIiIJ0O3 / disabled

要再次启用禁用的用户，请相应地使用（要求具有适当权限的用户）：

POST / api / 36 / users / tH7WIiIJ0O3 / enabled

用户有效期¶

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

要更新 UID 名为 tH7WIiIJ0O3 的用户的过期日期 并将其设置为2021-01-01的日期（需要具有相应权限的用户）：

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

取消设置到期日期，以使帐户永不过期 相应地使用（需要具有适当权限的用户）：

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

用户数据批准工作流程¶

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

GET / api / users / {id} / dataApprovalWorkflows

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

如果dhis.conf 中启用了链接账户，且用户已通过 OIDC 登录，则用户可使用此 API 调用在链接到同一身份供应商账户的 DHIS2 账户之间切换：

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

这样做的效果是注销当前用户并登录新用户。除了新用户最终会出现在 DHIS2 实例的默认页面上之外，其他操作看起来都很顺利。

请注意，这个 API 调用将来可能会改变，但其一般功能将保持不变。

要查看可切换到的用户列表，请使用此 API 调用：

GET /api/account/linkedAccounts

当前用户信息¶

为了获取有关当前已验证用户的信息和 它与其他资源的关联，您可以使用 me 资源 （您也可以通过其旧名称 currentUser 来引用它）。目前 用户相关资源为您提供有用的信息 构建客户端，例如用于数据输入和用户管理。这 下面描述了这些资源及其用途。

提供有关您当前登录的用户的基本信息 in as，包括用户名、用户凭据、分配的组织 单位：

/ api / me

提供有关当前未读消息和解释的信息：

/ api / me / dashboard

为了更改密码，此端点可用于验证 新输入的密码。密码验证将基于 系统中配置的 PasswordValidationRules。这个端点支持 POST 和密码字符串应在 POST 正文中发送。

/ api / me / validatePassword

更改密码时，此端点（支持 POST）可用于 验证旧密码。密码字符串应在 POST 正文中发送。

/ api / me / verifyPassword

返回授予当前用户的权限集：

/ api / me / authorization

返回 true 或 false，表示当前用户是否已被 授予给定的<auth>授权：

/ api / me / authorization / <auth>

给出与当前用户相关的数据批准级别：

/ api / me / dataApprovalLevels

提供当前用户可以访问的数据批准工作流。 对于每个工作流程，显示用户可能看到的数据批准级别，以及 他们在每个级别上具有什么权限：

/ api / me / dataApprovalWorkflows