更新用户接口

更新时间:
复制 MD 格式

所需权限

所需权限

资源

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

email

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

是

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

-

email

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
    }
  }
}