查询用户列表接口

更新时间:
复制 MD 格式

所需权限

所需权限

资源

Scope

资源服务

用户与部门信息读取(读取)

user-directory

admin.v1.user-directory.read

qwenwork-biz-service

GET /api/openapi/v1/users

公共请求头

适用《通过 API 配置 QwenWork 管理后台》的“认证与请求头”章节:Authorization 必填,X-Request-Id 可选;当前接口所需 Scope 见本页。

Idempotency-Key 是否适用及必填性以本页请求参数为准,不能用追踪标识替代幂等键。

请求参数

名称

位置

类型

必填

说明

示例

third_party_user_ids

query

array | null

否

重复传入的第三方用户 ID,最多 100 个,去除首尾空白后各为 1–255 字符;区分大小写精确匹配,与其他筛选和应用用户范围取交集,拒绝空值;省略则不按此项筛选。

["<string>"]

sort_order

query

string

否

创建时间 ASC/DESC,默认 DESC;同值按用户 ID 升序。

DESC

include_descendants

query

boolean

否

包含子部门,默认 true;始终与应用用户范围取交集。

true

keyword

query

string

否

搜索关键词

"<string>"

department_id

query

string · uuid

否

所属部门(部门 ID)

"<uuid>"

status

query

string

否

用户状态

"pending"

seat_status

query

string

否

席位授权

"assigned"

page

query

integer · int64

否

页码

1

page_size

query

integer · int64

否

每页条数

20

请求示例

将 <BASE_URL> 替换为企业部署的千问办公 API 服务地址,并填写实际参数。示例中的占位值不能直接用于请求。

curl --request GET \
  --url '<BASE_URL>/api/openapi/v1/users?third_party_user_ids=<third_party_user_ids>&keyword=<keyword>&department_id=<department_id>&status=<status>&seat_status=<seat_status>&page=1&page_size=20' \
  --header 'Authorization: Bearer <API_KEY>'

响应状态表

本表描述业务服务返回;网关自行生成的响应以网关契约为准,本轮未验证部署网关返回。

HTTP 状态码

触发条件

响应结构引用

客户端处理建议

200

执行成功

见本文“响应结果”

读取成功结构。

400

请求或依赖请求被拒绝

见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构

检查 code 与请求,不原样重试。

401

认证信息缺失或无效

见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构

核对凭据后重试。

403

Scope、授权范围或准入条件不满足

见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构

核对权限与目标资源。

404

目标用户或关联资源不存在

见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构

核对资源 ID 和当前状态。

409

业务状态或唯一字段冲突

见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构

按 code 和详情处理冲突,再决定是否重试。

422

参数或业务校验失败

见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构

修正参数后重试。

503

依赖服务不可用

见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构

退避重试或联系管理员;此读取操作不返回写入提交信息。

default

其他未单列的业务服务错误

见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构

保留状态码、code 与请求标识;不要推断已提交或已回滚。

Cache-Control: no-store。

总页数可由 ceil(total/page_size) 推导;total=0 时为 0。

响应结果

本节仅描述返回信息,不增加请求参数。sync_management 仅在存在同步归属记录时返回;无记录时省略。它不是创建或更新用户时必须填写的对象。

历史来源快照需独立的 admin.v1.directory-sync-runs.read 权限;旧记录无执行 ID 或快照时,不以当前配置替代历史信息。

名称

类型

必填

说明

示例

items

array | null

是

用户列表。

-

page

integer · int64

是

页码

0

page_size

integer · int64

是

每页条数

0

total

integer · int64

是

总条数

0

items[]

字段

类型

必填

说明

account

string

否

账号

created_at

string · date-time

是

用户创建时间。

credential

object

是

密码生命周期信息,不包含密码或哈希。

department_ids

array | null

是

所属部门(部门 ID 列表)

departments

array

是

部门详情;无部门时为空数组。

email

string

否

邮箱

email_domain_valid

boolean

是

IAM 当前组织邮箱域校验结果。

job_number

string

否

工号

last_active_at

string · date-time

否

IAM 最近活跃时间;无记录时省略,不等同于最近业务使用时间。

name

string

是

姓名

phone

string

否

手机号

phone_number_masked

string

否

脱敏电话。

qid

string · uuid

是

用户 ID(QID);对应用户编辑接口路径中的 userId

seat_status

string

是

席位授权;可选值:assigned, unassigned 取值:"assigned"、"unassigned"

source

string

是

IAM 实际创建来源;外部 ID 不代表同步来源。 取值:"directory-sync"、"manual"

status

string

是

用户状态;可选值:pending, active, disabled 取值:"active"、"disabled"、"pending"

sync_management

object

否

仅有同步归属记录时返回;不是请求参数。

third_party_user_id

string

是

第三方用户 ID;未设置时为空字符串。

updated_at

string · date-time

是

更新时间

items[].credential

字段

类型

必填

说明

credential_version

integer · int64

是

凭证版本。

first_login_completed_at

string · date-time

否

首次登录完成时间;未完成时省略。

must_change_password

boolean

是

是否需要修改密码。

password_state

string

是

密码状态:unset 未设置、initial 初始密码、active 已生效;可选值:unset, initial, active 取值:"active"、"initial"、"unset"

password_updated_at

string · date-time

否

密码更新时间;无记录时省略。

items[].departments[]

字段

类型

必填

说明

external_id

string

否

第三方部门 ID;对应部门创建、编辑接口的 external_id,未设置时省略

id

string · uuid

是

部门 ID。

is_primary

boolean

是

是否为主部门。

name

string

是

部门名称。

path

string

是

部门路径。

items[].sync_management

字段

类型

必填

说明

config_revision

integer · int64

否

来源配置版本。

created_by_sync

boolean

否

权威创建来源;true 时 source=directory-sync,外部 ID 不代表同步来源。

external_id

string

是

同步来源中的标识符。

managed

boolean

是

是否由同步管理用户字段。

managed_fields

array

是

受管理的公开字段名称;使用 phone/job_number/department_ids。

managed_org_unit_ids

array | null

否

受管理的部门 ID。

run_id

string

否

来源执行 ID;通过 directory-sync/runs/{runId} 查询。

source_id

string

是

同步来源 ID;通过 directory-sources 查配置,directory-sync/runs 查执行详情。

source_type

string

是

同步来源类型。

响应示例

200

{
  "items": [
    {
      "account": "<string>",
      "department_ids": [
        "<string>"
      ],
      "email": "<string>",
      "job_number": "<string>",
      "name": "<string>",
      "phone": "<string>",
      "qid": "<uuid>",
  "email_domain_valid": false,
      "seat_status": "assigned",
      "source": "manual",
      "status": "pending",
      "updated_at": "2026-08-27T10:00:00Z",
      "third_party_user_id": "external-001",
      "departments": [
        {
          "id": "22222222-2222-4222-8222-222222222222",
          "name": "Engineering",
          "path": "Company/Engineering",
          "external_id": "external-dept",
          "is_primary": true
        }
      ],
      "credential": {
        "password_state": "active",
        "must_change_password": false,
        "credential_version": 2
      },
      "created_at": "2026-09-19T01:00:00Z",
      "last_active_at": "2026-09-23T01:00:00Z"
    }
  ],
  "page": 0,
  "page_size": 0,
  "total": 0
}