所需权限
所需权限 | 资源 | Scope | 资源服务 |
用户与部门管理(管理) | user-directory | admin.v1.user-directory.manage | qwenwork-biz-service |
PATCH /api/openapi/v1/users/{userId}
公共请求头
适用《通过 API 配置 QwenWork 管理后台》的“认证与请求头”章节:Authorization 必填,X-Request-Id 可选;当前接口所需 Scope 见本页。
Idempotency-Key 是否适用及必填性以本页请求参数为准,不能用追踪标识替代幂等键。
邮箱可信域名规则
非空邮箱必须精确匹配组织当前已验证且未删除的可信域名;没有可信域名时返回 422 directory_user_email_domain_not_verified。不支持通配符或父域名继承。 本接口按合并后的完整资料校验:省略 email 会保留原值,即使仅修改姓名或部门,只要结果仍有非空邮箱, 也必须满足域名规则。可以显式提交 "email": "" 清空,但仍须保留账号、手机号或工号至少一种有效身份。 此项收紧零域名下原有写入规则。调用方应在升级前配置并验证域名,或按上述方式移除邮箱输入。 独立启用账号、授予席位及已有登录会话不因本次变更而新增限制。
第三方 ID 补绑
可选传入第三方 ID,仅允许给未绑定用户补绑,或重复提交相同 ID。非空值去首尾空白后最多 255 个字符,区分大小写。省略或 null 保留写入时的最新绑定;空字符串或纯空白返回 422。
替换已有绑定返回 409 / directory_user_third_party_id_rebind_forbidden;被同组织其他用户占用返回 409 / directory_user_third_party_id_conflict。
仅传此字段即可补绑,其他资料保持原值;仍执行已有完整资料校验、用户范围与受管对象限制。
请求参数
请求体:必填;Content-Type:application/json。
名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
userId | path | string · uuid | 是 | 用户 ID | "<uuid>" |
Idempotency-Key | header | string | 否 | 幂等键,用于避免重复提交 | "<string>" |
third_party_user_id | body | string | null | 否 | 仅补绑或同值重试;省略/null 保留,禁止改绑与清空。 | "crc-user-001" |
account | body | string | 否 | 账号 | "<string>" |
department_ids | body | array | null | 否 | 当前组织内的部门,最多 200 项且不可重复 | ["<string>"] |
body | string | 否 | 邮箱 | "<string>" | |
job_number | body | string | 否 | 工号 | "<string>" |
name | body | string | 否 | 姓名 | "<string>" |
phone | body | string | 否 | 手机号 | "<string>" |
请求示例
将 <BASE_URL> 替换为企业部署的千问办公 API 服务地址,并填写实际参数。示例中的占位值不能直接用于请求。
curl --request PATCH \
--url '<BASE_URL>/api/openapi/v1/users/<userId>' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Idempotency-Key: <UNIQUE_REQUEST_ID>' \
--header 'Content-Type: application/json' \
--data '{
"third_party_user_id": "crc-user-001",
"account": "<string>",
"department_ids": [
"<string>"
],
"email": "<string>",
"job_number": "<string>",
"name": "<string>",
"phone": "<string>"
}'
响应状态表
本表描述业务服务返回;网关自行生成的响应以网关契约为准,本轮未验证部署网关返回。
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 管理后台》的“通用错误”结构; 见本文“已提交与同步恢复” | 先查询当前状态;仅有 committed=true 才确认已提交,按恢复信息处理。 |
default | 其他未单列的业务服务错误 | 见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构 | 保留状态码、code 与请求标识;不要推断已提交或已回滚。 |
Cache-Control: no-store。
PATCH 的 Idempotency-Key 可选;当前没有重放账本,不保证同键去重。超时后先查询用户状态。
响应结果
本节仅描述返回信息,不增加请求参数。sync_management 仅在存在同步归属记录时返回;无记录时省略。它不是创建或更新用户时必须填写的对象。
历史来源快照需独立的 admin.v1.directory-sync-runs.read 权限;旧记录无执行 ID 或快照时,不以当前配置替代历史信息。
名称 | 类型 | 必填 | 说明 | 示例 |
account | string | 否 | 账号 | "<string>" |
created_at | string · date-time | 是 | 用户创建时间。 | "2026-09-19T01:00:00Z" |
credential | object | 是 | 密码生命周期信息,不包含密码或哈希。 |
|
department_ids | array | null | 是 | 所属部门(部门 ID 列表) | ["<string>"] |
departments | array | 是 | 部门详情;无部门时为空数组。 |
|
string | 否 | 邮箱 | "<string>" | |
email_domain_valid | boolean | 是 | IAM 当前组织邮箱域校验结果。 | false |
job_number | string | 否 | 工号 | "<string>" |
last_active_at | string · date-time | 否 | IAM 最近活跃时间;无记录时省略,不等同于最近业务使用时间。 | "2026-09-23T01:00:00Z" |
name | string | 是 | 姓名 | "<string>" |
phone | string | 否 | 手机号 | "<string>" |
phone_number_masked | string | 否 | 脱敏电话。 |
|
qid | string · uuid | 是 | QID | "<uuid>" |
seat_status | string | 是 | 席位授权 取值:"assigned"、"unassigned" | "assigned" |
source | string | 是 | IAM 实际创建来源;外部 ID 不代表同步来源。 取值:"directory-sync"、"manual" | "manual" |
status | string | 是 | 用户状态 取值:"active"、"disabled"、"pending" | "pending" |
sync_management | object | 否 | 仅有同步归属记录时返回;不是请求参数。 |
|
third_party_user_id | string | 是 | 第三方用户 ID;未设置时为空字符串。 | "external-001" |
updated_at | string · date-time | 是 | 更新时间 | "2026-08-27T10:00:00Z" |
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 | 否 | 密码更新时间;无记录时省略。 |
departments[]
字段 | 类型 | 必填 | 说明 |
external_id | string | 否 | 部门外部 ID;未设置时省略。 |
id | string · uuid | 是 | 部门 ID。 |
is_primary | boolean | 是 | 是否为主部门。 |
name | string | 是 | 部门名称。 |
path | string | 是 | 部门路径。 |
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
{
"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"
}
特殊响应
字段冲突
复用结构:见《通过 API 配置 QwenWork 管理后台》的“公共错误字段”结构
仅用于 409 的唯一字段冲突;其他业务冲突可能只有通用错误。
名称 | 类型 | 必填 | 说明 | 示例 |
code | string | 是 | 该分支必有的业务错误码。 | "request_rejected" |
details | object | 是 | 仅在该错误分支有结构化详情时出现。 |
|
details
字段 | 类型 | 必填 | 说明 |
conflicts | array | 是 | 唯一字段冲突列表;不包含提交或恢复详情。 |
details.conflicts[]
字段 | 类型 | 必填 | 说明 |
field | string | 是 | 相关的公开请求字段名。 |
name | string | 否 | 冲突用户姓名;超出应用授权范围时省略。 |
user_id | string · uuid | 否 | 相关用户 ID;冲突详情中超出授权范围时省略。 |
响应示例 — 409
{
"error": "Conflict",
"detail": "Third-party ID already exists.",
"code": "directory_user_third_party_id_conflict",
"details": {
"conflicts": [
{
"field": "third_party_user_id"
}
]
}
}
已提交与同步恢复
复用结构:见《通过 API 配置 QwenWork 管理后台》的“公共错误字段”结构
仅在 details.committed=true 时使用。recovery 与 results 至少有一项;两者可以同时存在。没有该详情的 503 不证明写入已提交或回滚。
名称 | 类型 | 必填 | 说明 | 示例 |
code | string | 是 | 该分支必有的业务错误码。 取值:"iam_openapi_execution_unavailable" | "iam_openapi_execution_unavailable" |
details | object | 是 | 仅在该错误分支有结构化详情时出现。 |
|
details
至少包含字段:recovery / results
字段 | 类型 | 必填 | 说明 |
committed | boolean | 是 | 固定为 true:本地写入已提交,不代表同步成功。 取值:true |
recovery | object | 否 | 总体或该用户的同步恢复信息。 |
results | array | 否 | 逐用户同步结果;可与总体 recovery 同时存在。 |
details.recovery
字段 | 类型 | 必填 | 说明 |
automatic_retry | boolean | 是 | 是否由系统自动重试。 |
next_retry_at | string · date-time | 否 | 下次重试时间;未安排时省略。 |
requires_action | boolean | 是 | 是否需要调用方或管理员处理。 |
state | string | 是 | 恢复状态:succeeded、processing、retrying、action_required、unconfirmed。 取值:"action_required"、"processing"、"retrying"、"succeeded"、"unconfirmed" |
details.results[]
字段 | 类型 | 必填 | 说明 |
code | string | 否 | 稳定业务错误码;没有业务码时可省略。 |
recovery | object | 是 | 总体或该用户的同步恢复信息。 |
user_id | string | 是 | 本条同步结果的用户 ID。 |
details.results[].recovery
复用结构:见本文“details.recovery”
用户写入等待与重试规则见API 首页“错误处理”中的“用户写入的同步等待与重试”。
响应示例 — 503
{
"error": "Service Unavailable",
"detail": "The write was saved; synchronization is pending.",
"code": "iam_openapi_execution_unavailable",
"details": {
"committed": true,
"recovery": {
"state": "processing",
"automatic_retry": false,
"requires_action": false
}
}
}