所需权限
所需权限 | 资源 | 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 | 是 | 部门详情;无部门时为空数组。 |
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
}