文档中心

ArkClaw 企业版

UserManagement

ListUsers - 批量查询用户详情

批量查询用户详情。

请求参数

下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Action string 必选示例值：ListUsers

要执行的操作，取值：ListUsers。

Version string 必选示例值：2026-05-01

API的版本，取值：2026-05-01。

Filter.Emails.N string[] 可选示例值：Filter.Emails.1=zhang**@example.com&Filter.Emails.2=li**@example.com

通过用户邮箱地址查询用户，支持精确匹配，您可以填写一个或多个用户邮箱地址。

参数 - N：表示用户邮箱地址的序号，取值范围：1～100。

多个邮箱地址之间用&分隔。

Filter.DepartmentUid string 可选示例值：d4bc986c-6474-4c7f-96f3-c020b8ab****

通过部门UID查询用户，请传入部门UID，仅支持精准匹配。部门UID可以在ArkClaw控制台“用户管理”页面中的“部门管理”页签获取。

Filter.DepartmentUidRecursive boolean 可选示例值：true

是否递归查询部门下的用户。

仅在Filter.DepartmentUid传入正确的部门UID时生效，若Filter.DepartmentUid未传入或传入空值，Filter.DepartmentUidRecursive的值不生效。

取值：

true ：查询指定部门及其所有子部门下的用户。

false （默认）：仅查询指定部门的直属用户，不包含子部门。

Filter.Email string 可选示例值：zhang**

通过用户邮箱地址查询用户，支持模糊匹配。

Filter.EmailPhoneNameIsNullOrEmpty boolean 可选示例值：true

是否筛选显示名称、手机号或邮箱存在空值的用户，取值：

true：是。

false：仅返回显示名称、手机号、邮箱三项均已填写且非空的用户。

不传入本参数则返回全部用户。

Filter.GroupUid string 可选示例值：usergroup1

通过分组UID查询用户，请传入分组UID，仅支持精准匹配。

Filter.Name string 可选示例值：zhang**

通过用户显示名称查询用户，支持模糊匹配。

Filter.NotInAnyDepartment boolean 可选示例值：false

是否筛选不属于任何部门的用户，取值：

true：仅返回未加入任何部门的用户。

false（默认）：不限制部门归属，返回全部用户。

Filter.NotInAnyGroup boolean 可选示例值：false

是否筛选不属于任何分组的用户，取值：

true：仅返回未加入任何分组的用户。

false（默认）：不限制分组归属，返回全部用户。

Filter.PhoneNumber string 可选示例值：138****

通过用户手机号查询用户，支持模糊匹配。

Filter.UserIds.N string[] 可选示例值：Filter.UserIds.1=baadc2dc-****&Filter.UserIds.2=9fc5ff57-****

通过用户ID查询用户，您可以填写一个或多个用户ID。

参数 - N：表示用户ID的序号，取值范围：1～100。

多个邮箱地址之间用&分隔。

MaxResults integer 可选示例值：20

分页查询时设置的每页行数。

最小值：1。

最大值：100。

默认值：10。

若传入非法MaxResults值，会被自动调整为默认值。

NextToken string 可选示例值：Y2kteWVqMXJreTVma3F0YzM4e******

分页查询凭证，用于标记分页的位置，初次调用该接口时无需设置。下次查询时，取值为上一次API调用返回的NextToken参数值。

SpaceId string 必选示例值：csi-yei8347ta8xmf5qd****

ArkClaw实例所属空间ID。可以在ArkClaw控制台“空间概览”页面的“基本信息”获取。

返回参数

下方仅列出本接口特有的返回参数。更多信息请参见返回结构。

NextToken string 示例值：Y2kteWVqMXJreTVma3F0YzM4e******

分页查询凭证，用于标记分页的位置，初次调用该接口时无需设置。下次查询时，取值为上一次API调用返回的NextToken参数值。

Users object[] 示例值：--

用户列表数据。

CreatedAt string 示例值：2026-01-01T11:02:08+08:00

用户创建时间，时间格式为time.RFC3339。

UserId string 示例值：baadc2dc-****

用户在身份认证用户池中的唯一标识ID。

UpdatedAt string 示例值：2026-01-01T11:02:08+08:00

用户信息更新时间，时间格式为time.RFC3339。

PreferredUsername string 示例值：zhang**

用户名。

PhoneNumber string 示例值：+86138****8000

用户手机号码。

NumLogins integer 示例值：10

登录次数。

Name string 示例值：张**

用户姓名。

Email string 示例值：zhang**@example.com

用户邮箱地址。

DepartmentUids string[] 示例值：fc6b28f5-0f02-41cc-****

用户所属部门UID列表。

GroupUids string[] 示例值："usergroup1"

用户所属用户组UID列表。

CustomAttributes object[] 示例值：--

用户自定义属性列表。

Name string 示例值：department_code

自定义属性名称。

Value string 示例值：engineering

自定义属性值。

UnionId string 示例值：bca-1f-****

外部身份提供商用户唯一标识。

请求示例

GET /?Action=ListUsers&Version=2026-05-01&SpaceId=csi-yei8347ta8xmf5qd**** HTTP/1.1​
Host: https://arkclaw.cn-beijing.volcengineapi.com​
X-Date: 20260616T140849Z​
Authorization: HMAC-SHA256 Credential=Adfks******wekfwe/20260616/cn-beijing/arkclaw/request, SignedHeaders=host;x-date, Signature=47a7d934ff7b37c03938******cd7b8278a40a1057690c401e92246a0e41085f​
​
​

返回示例

{​
  "ResponseMetadata": {​
    "RequestId": "2026061117512420024504****",​
    "Action": "ListUsers",​
    "Version": "2026-05-01",​
    "Service": "arkclaw",​
    "Region": "cn-beijing"​
  },​
  "Result": {​
    "NextToken": "Y2kteWVqMXJreTVma3F0YzM4e******",​
    "Users": [​
      {​
        "CreatedAt": "2026-01-01T11:02:08+08:00",​
        "UserId": "baadc2dc-****",​
        "UpdatedAt": "2026-01-01T11:02:08+08:00",​
        "PreferredUsername": "zhang**",​
        "PhoneNumber": "+86138****8000",​
        "NumLogins": 10,​
        "Name": "zhang**",​
        "Email": "zhang**@example.com",​
        "DepartmentUids": [​
          "d4bc986c-6474-4c7f-96f3-c020b8ab****"​
        ],​
        "GroupUids": [​
          "usergroup1"​
        ],​
        "CustomAttributes": [​
          {​
            "Name": "department_code",​
            "Value": "engineering"​
          }​
        ]​
      },​
      {​
        "CreatedAt": "2026-01-01T11:02:08+08:00",​
        "UserId": "9fc5ff57-****",​
        "UpdatedAt": "2026-01-01T11:02:08+08:00",​
        "PreferredUsername": "li**",​
        "PhoneNumber": "+86139****8010",​
        "NumLogins": 5,​
        "Name": "li**",​
        "Email": "li**@example.com",​
        "DepartmentUids": [​
          "d4bc986c-6474-4c7f-96f3-c020b8ab****"​
        ],​
        "GroupUids": [​
          "usergroup1"​
        ],​
        "CustomAttributes": [​
          {​
            "Name": "department_code",​
            "Value": "engineering"​
          }​
        ]​
      }​
    ]​
  }​
}​

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

状态码	错误码	错误信息	说明
400	InvalidFilterUserIds.TooMany	The number of specified Filter.UserIds exceeds the maximum limit of 100.	指定的Filter.UserIds数量超过最大限制（100）。
400	InvalidMaxResults.Malformed	The specified MaxResults is malformed.	无效的MaxResults。
400	InvalidNextToken.Malformed	The specified NextToken is malformed.	无效的NextToken。
400	MissingParameter.SpaceId	The required parameter SpaceId is not supplied.	参数SpaceId不能为空。
404	InvalidSpace.NotFound	The specified space does not exist.	指定的ClawSpace不存在。
500	InternalError	An internal error has occurred.	内部错误，请重试。如果多次尝试失败，请提交工单。

最近更新时间：2026.09.11 10:49:54

这个页面对您有帮助吗？

有用

无用