保存目录数据源配置接口

更新时间:
复制 MD 格式

所需权限

所需权限

资源

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

"<uuid>"

Idempotency-Key

header

string

是

幂等键,用于避免重复提交 minLength=1 maxLength=128

"<string>"

config_revision

body

integer · int64

否

配置版本号 minimum=1

1

credentials

body

object

否

凭据

-

default_seat

body

boolean

是

新用户默认申请席位

false

deletion_alert_email

body

string

否

告警邮箱 maxLength=320

"<string>"

deletion_alert_enabled

body

boolean

是

删除告警

false

deletion_alert_threshold

body

integer · int64

是

删除告警阈值 minimum=0

0

deletion_policy

body

string

是

离职处理 取值:"deactivate_and_reclaim_seat"、"deactivate_only"、"delete_user"

"delete_user"

initial_scim_token

body

string

否

初始 SCIM Token maxLength=255

"<string>"

name

body

string

是

来源名称 maxLength=255

"<string>"

schedule

body

string

是

同步频率 取值:"daily"、"every_6_hours"、"manual"

"manual"

schedule_anchor_at

body

string · date-time

否

同步时间(北京时间)

"2026-08-27T10:00:00Z"

settings

body

object

是

数据源配置

-

source_type

body

string

是

数据源类型 取值:"dingtalk"、"entra_id"、"feishu"、"openldap"、"scim"、"wecom"、"windows_ad"

"dingtalk"

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

email

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

是

配置版本号

0

connection_status

string

是

连接状态

"<string>"

created_at

string · date-time

是

创建时间

"2026-08-27T10:00:00Z"

created_by_email

string

否

创建人邮箱

"<string>"

created_by_name

string

否

创建人

"<string>"

credential_configured

boolean

是

是否已配置凭据

false

default_seat

boolean

是

新用户默认申请席位

false

deletion_alert_email

string

否

告警邮箱

"<string>"

deletion_alert_enabled

boolean

是

删除告警

false

deletion_alert_threshold

integer · int64

是

删除告警阈值

0

deletion_policy

string

是

离职处理

"<string>"

external_id_field

string

是

第三方用户 ID 映射字段

"<string>"

external_id_field_locked

boolean

是

第三方用户 ID 映射是否已锁定

false

id

string · uuid

是

数据源 ID

"<uuid>"

last_activity_at

string · date-time

否

最近活动时间

"2026-08-27T10:00:00Z"

last_connected_at

string · date-time

否

最近连接时间

"2026-08-27T10:00:00Z"

last_connection_error_code

string

否

最近连接错误码

"<string>"

modified_at

string · date-time

是

更新时间

"2026-08-27T10:00:00Z"

name

string

是

来源名称

"<string>"

next_run_at

string · date-time

否

下次同步时间

"2026-08-27T10:00:00Z"

schedule

string

是

同步频率

"<string>"

schedule_anchor_at

string · date-time

否

同步时间(北京时间)

"2026-08-27T10:00:00Z"

settings

object

是

数据源配置

-

source_type

string

是

数据源类型

"<string>"

status

string

是

状态

"<string>"

updated_by_email

string

否

更新人邮箱

"<string>"

updated_by_name

string

否

更新人

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

email

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 和同步策略不变。 消息回调凭据在管理控制台单独配置,不通过本接口读取或写入。