所需权限
所需权限 | 资源 | Scope | 资源服务 |
用户同步配置管理(管理) | directory-sync-config | admin.v1.directory-sync-config.manage | qwenwork-biz-service |
PUT /api/openapi/v1/directory-sync/sources/{sourceId}
公共请求头
适用《通过 API 配置 QwenWork 管理后台》的“认证与请求头”章节:Authorization 必填,X-Request-Id 可选;当前接口所需 Scope 见本页。
Idempotency-Key 是否适用及必填性以本页请求参数为准,不能用追踪标识替代幂等键。
请求参数
请求体:必填;Content-Type:application/json。
名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
sourceId | path | string · uuid | 是 | 数据源 ID |
|
Idempotency-Key | header | string | 是 | 幂等键,用于避免重复提交 minLength=1 maxLength=128 |
|
config_revision | body | integer · int64 | 否 | 配置版本号 minimum=1 |
|
credentials | body | object | 否 | 凭据 |
|
default_seat | body | boolean | 是 | 新用户默认申请席位 |
|
deletion_alert_email | body | string | 否 | 告警邮箱 maxLength=320 |
|
deletion_alert_enabled | body | boolean | 是 | 删除告警 |
|
deletion_alert_threshold | body | integer · int64 | 是 | 删除告警阈值 minimum=0 |
|
deletion_policy | body | string | 是 | 离职处理 取值:"deactivate_and_reclaim_seat"、"deactivate_only"、"delete_user" |
|
initial_scim_token | body | string | 否 | 初始 SCIM Token maxLength=255 |
|
name | body | string | 是 | 来源名称 maxLength=255 |
|
schedule | body | string | 是 | 同步频率 取值:"daily"、"every_6_hours"、"manual" |
|
schedule_anchor_at | body | string · date-time | 否 | 同步时间(北京时间) |
|
settings | body | object | 是 | 数据源配置 |
|
source_type | body | string | 是 | 数据源类型 取值:"dingtalk"、"entra_id"、"feishu"、"openldap"、"scim"、"wecom"、"windows_ad" |
|
body.credentials 字段
字段 | 类型 | 必填 | 说明 |
agent_id | string | 否 | 应用 Agent ID(仅写入) maxLength=512 |
app_id | string | 否 | 应用 ID(仅写入) maxLength=512 |
app_secret | string | 否 | 应用密钥(仅写入) maxLength=4096 |
bind_dn | string | 否 | LDAP 绑定 DN(仅写入) maxLength=2048 |
bind_password | string | 否 | LDAP 绑定密码(仅写入) maxLength=4096 |
client_id | string | 否 | 客户端 ID(仅写入) maxLength=512 |
client_secret | string | 否 | 客户端密钥(仅写入) maxLength=4096 |
corp_id | string | 否 | 企业 ID(仅写入) maxLength=512 |
secret | string | 否 | 认证密钥(仅写入) maxLength=4096 |
tenant_id | string | 否 | 租户 ID(仅写入) maxLength=512 |
body.settings 字段
字段 | 类型 | 必填 | 说明 |
connection | object | 是 | 连接配置 |
department_mapping | object | 是 | 部门映射 |
mapping | object | 是 | 成员映射 |
scope | object | 是 | 同步范围 |
wecom | object | 否 | 企业微信部署与地址配置 |
body.settings.connection 字段
字段 | 类型 | 必填 | 说明 |
client_name | string | 否 | SCIM Client maxLength=255 |
tls_enabled | boolean | 否 | 启用 TLS |
url | string | 否 | 服务器地址 maxLength=2048 |
body.settings.department_mapping 字段
字段 | 类型 | 必填 | 说明 |
external_id | string | 是 | 第三方部门 ID(来源字段) maxLength=128 |
name | string | 是 | 部门名称(来源字段) maxLength=128 |
order | string | 否 | 排序(来源字段) maxLength=128 |
parent_external_id | string | 否 | 上级第三方部门 ID(来源字段) maxLength=128 |
status | string | 否 | 状态(来源字段) maxLength=128 |
body.settings.mapping 字段
字段 | 类型 | 必填 | 说明 |
account | string | 否 | 账号(来源字段) maxLength=128 |
department_external_id | string | 否 | 所属部门的第三方部门 ID(来源字段) maxLength=128 |
string | 否 | 邮箱(来源字段) maxLength=128 | |
employee_no | string | 否 | 工号(来源字段) maxLength=128 |
external_id | string | 是 | 第三方用户 ID(来源字段) maxLength=128 |
name | string | 是 | 用户姓名(来源字段) maxLength=128 |
phone | string | 否 | 手机号(来源字段) maxLength=128 |
status | string | 否 | 状态(来源字段) maxLength=128 |
body.settings.scope 字段
字段 | 类型 | 必填 | 说明 |
base_dn | string | 否 | Base DN maxLength=2048 |
mode | string | 是 | 同步范围类型;可选值:all, departments, base_dn, administrative_units 取值:"administrative_units"、"all"、"base_dn"、"departments" |
org_unit_external_ids | array<string> | null | 否 | 范围部门(第三方部门 ID 列表) maxItems=200 |
org_unit_filter | string | 否 | 部门过滤器 maxLength=2048 |
user_filter | string | 否 | 用户过滤器 maxLength=2048 |
body.settings.wecom 字段
字段 | 类型 | 必填 | 说明 |
api_base_url | string | 否 | 企业微信 API 基础地址 maxLength=2048 |
authorization_url | string | 否 | 企业微信授权地址 maxLength=2048 |
deployment | string | 是 | 企业微信部署类型;可选值:standard, private 取值:"private"、"standard" |
请求示例
将 <BASE_URL> 替换为企业部署的千问办公 API 服务地址,并填写实际参数。示例中的占位值不能直接用于请求。
curl --request PUT \
--url '<BASE_URL>/api/openapi/v1/directory-sync/sources/<sourceId>' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Idempotency-Key: <UNIQUE_REQUEST_ID>' \
--header 'Content-Type: application/json' \
--data '{
"config_revision": 1,
"credentials": {
"agent_id": "<string>",
"app_id": "<string>",
"app_secret": "<string>",
"bind_dn": "<string>",
"bind_password": "<string>",
"client_id": "<string>",
"client_secret": "<string>",
"corp_id": "<string>",
"secret": "<string>",
"tenant_id": "<string>"
},
"default_seat": false,
"deletion_alert_email": "<string>",
"deletion_alert_enabled": false,
"deletion_alert_threshold": 0,
"deletion_policy": "delete_user",
"initial_scim_token": "<string>",
"name": "<string>",
"schedule": "manual",
"schedule_anchor_at": "2026-08-27T10:00:00Z",
"settings": {
"connection": {
"client_name": "<string>",
"tls_enabled": false,
"url": "<string>"
},
"department_mapping": {
"external_id": "<string>",
"name": "<string>",
"order": "<string>",
"parent_external_id": "<string>",
"status": "<string>"
},
"mapping": {
"account": "<string>",
"department_external_id": "<string>",
"email": "<string>",
"employee_no": "<string>",
"external_id": "<string>",
"name": "<string>",
"phone": "<string>",
"status": "<string>"
},
"scope": {
"base_dn": "<string>",
"mode": "all",
"org_unit_external_ids": [
"<string>"
],
"org_unit_filter": "<string>",
"user_filter": "<string>"
}
},
"source_type": "dingtalk"
}'
响应状态表
HTTP 状态码 | 触发条件 | 响应结构引用 | 客户端处理建议 |
200 | 请求成功 | 见本文“响应结果” | 读取响应结果。 |
default | 未单独列出的认证、授权、校验或依赖错误 | 见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构 | 按状态与 code 处理;写操作重试前核实结果及幂等要求。 |
响应结果
Content-Type: application/json
名称 | 类型 | 必填 | 说明 | 示例 |
config_revision | integer · int64 | 是 | 配置版本号 |
|
connection_status | string | 是 | 连接状态 |
|
created_at | string · date-time | 是 | 创建时间 |
|
created_by_email | string | 否 | 创建人邮箱 |
|
created_by_name | string | 否 | 创建人 |
|
credential_configured | boolean | 是 | 是否已配置凭据 |
|
default_seat | boolean | 是 | 新用户默认申请席位 |
|
deletion_alert_email | string | 否 | 告警邮箱 |
|
deletion_alert_enabled | boolean | 是 | 删除告警 |
|
deletion_alert_threshold | integer · int64 | 是 | 删除告警阈值 |
|
deletion_policy | string | 是 | 离职处理 |
|
external_id_field | string | 是 | 第三方用户 ID 映射字段 |
|
external_id_field_locked | boolean | 是 | 第三方用户 ID 映射是否已锁定 |
|
id | string · uuid | 是 | 数据源 ID |
|
last_activity_at | string · date-time | 否 | 最近活动时间 |
|
last_connected_at | string · date-time | 否 | 最近连接时间 |
|
last_connection_error_code | string | 否 | 最近连接错误码 |
|
modified_at | string · date-time | 是 | 更新时间 |
|
name | string | 是 | 来源名称 |
|
next_run_at | string · date-time | 否 | 下次同步时间 |
|
schedule | string | 是 | 同步频率 |
|
schedule_anchor_at | string · date-time | 否 | 同步时间(北京时间) |
|
settings | object | 是 | 数据源配置 |
|
source_type | string | 是 | 数据源类型 |
|
status | string | 是 | 状态 |
|
updated_by_email | string | 否 | 更新人邮箱 |
|
updated_by_name | string | 否 | 更新人 |
|
settings
字段 | 类型 | 必填 | 说明 |
connection | object | 是 | 连接配置 |
department_mapping | object | 是 | 部门映射 |
mapping | object | 是 | 成员映射 |
scope | object | 是 | 同步范围 |
wecom | object | 否 | 企业微信部署与地址配置 |
settings.connection
字段 | 类型 | 必填 | 说明 |
client_name | string | 否 | SCIM Client maxLength=255 |
tls_enabled | boolean | 否 | 启用 TLS |
url | string | 否 | 服务器地址 maxLength=2048 |
settings.department_mapping
字段 | 类型 | 必填 | 说明 |
external_id | string | 是 | 第三方部门 ID(来源字段) maxLength=128 |
name | string | 是 | 部门名称(来源字段) maxLength=128 |
order | string | 否 | 排序(来源字段) maxLength=128 |
parent_external_id | string | 否 | 上级第三方部门 ID(来源字段) maxLength=128 |
status | string | 否 | 状态(来源字段) maxLength=128 |
settings.mapping
字段 | 类型 | 必填 | 说明 |
account | string | 否 | 账号(来源字段) maxLength=128 |
department_external_id | string | 否 | 所属部门的第三方部门 ID(来源字段) maxLength=128 |
string | 否 | 邮箱(来源字段) maxLength=128 | |
employee_no | string | 否 | 工号(来源字段) maxLength=128 |
external_id | string | 是 | 第三方用户 ID(来源字段) maxLength=128 |
name | string | 是 | 用户姓名(来源字段) maxLength=128 |
phone | string | 否 | 手机号(来源字段) maxLength=128 |
status | string | 否 | 状态(来源字段) maxLength=128 |
settings.scope
字段 | 类型 | 必填 | 说明 |
base_dn | string | 否 | Base DN maxLength=2048 |
mode | string | 是 | 同步范围类型;可选值:all, departments, base_dn, administrative_units 取值:"administrative_units"、"all"、"base_dn"、"departments" |
org_unit_external_ids | array<string> | null | 否 | 范围部门(第三方部门 ID 列表) maxItems=200 |
org_unit_filter | string | 否 | 部门过滤器 maxLength=2048 |
user_filter | string | 否 | 用户过滤器 maxLength=2048 |
settings.wecom
字段 | 类型 | 必填 | 说明 |
api_base_url | string | 否 | 企业微信 API 基础地址 maxLength=2048 |
authorization_url | string | 否 | 企业微信授权地址 maxLength=2048 |
deployment | string | 是 | 企业微信部署类型;可选值:standard, private 取值:"private"、"standard" |
三方成员自定义字段映射
钉钉、飞书、企业微信允许在 settings.mapping 的 external_id、name、email、phone、employee_no、account、status 中填写自定义来源路径。部门及成员关系保持原规则,其他来源不扩展。
来源 | 示例 |
普通成员字段 | user.profile.identifier |
钉钉扩展属性 | user.extension["成本中心"] |
飞书自定义属性(按字段 ID) | user.custom_attrs["C-123"].value.text |
企业微信扩展属性(按名称) | user.extattr.attrs["员工编号"].text.value |
完整路径最多 128 个字符,支持对象点路径及双引号括号键;不支持脚本、通配符或数组下标。只读取当前成员接口已返回的标量,配置不会授予字段读取权限,也不会新增逐人补查。
缺失/空白/不适用类型沿用现有空值保留规则;同 ID/名称出现冲突值时不选取任意一项。状态沿用通用状态值规则,不执行自定义转换。第三方 ID 缺失或冲突按原校验与清理保护处理。
原预设、历史别名和企微 employee_no 工号兼容逻辑保持。路径无效返回既有 422 来源配置错误;Scope、权限、接口结构及并发版本规则不变。
响应示例
{
"config_revision": 0,
"connection_status": "<string>",
"created_at": "2026-08-27T10:00:00Z",
"created_by_email": "<string>",
"created_by_name": "<string>",
"credential_configured": false,
"default_seat": false,
"deletion_alert_email": "<string>",
"deletion_alert_enabled": false,
"deletion_alert_threshold": 0,
"deletion_policy": "<string>",
"external_id_field": "<string>",
"external_id_field_locked": false,
"id": "<uuid>",
"last_activity_at": "2026-08-27T10:00:00Z",
"last_connected_at": "2026-08-27T10:00:00Z",
"last_connection_error_code": "<string>",
"modified_at": "2026-08-27T10:00:00Z",
"name": "<string>",
"next_run_at": "2026-08-27T10:00:00Z",
"schedule": "<string>",
"schedule_anchor_at": "2026-08-27T10:00:00Z",
"settings": {
"connection": {
"client_name": "<string>",
"tls_enabled": false,
"url": "<string>"
},
"department_mapping": {
"external_id": "<string>",
"name": "<string>",
"order": "<string>",
"parent_external_id": "<string>",
"status": "<string>"
},
"mapping": {
"account": "<string>",
"department_external_id": "<string>",
"email": "<string>",
"employee_no": "<string>",
"external_id": "<string>",
"name": "<string>",
"phone": "<string>",
"status": "<string>"
},
"scope": {
"base_dn": "<string>",
"mode": "all",
"org_unit_external_ids": [
"<string>"
],
"org_unit_filter": "<string>",
"user_filter": "<string>"
}
},
"source_type": "<string>",
"status": "<string>",
"updated_by_email": "<string>",
"updated_by_name": "<string>"
}
企业微信私有化配置
企业微信保持 source_type: "wecom"。settings.wecom 为可选对象:deployment 为 standard 或 private, api_base_url 为私有化企微的 HTTPS API 基础地址;authorization_url 为可选授权地址。 未配置时使用标准版固定地址;更新省略 settings.wecom 时保留原配置。 私有化服务须兼容企微协议且能由服务端直接访问,禁止明文 HTTP、跳过证书校验或失败时回退公网地址。 连接测试、部门读取和同步复用该地址;原属性映射、Scope 和同步策略不变。 消息回调凭据在管理控制台单独配置,不通过本接口读取或写入。