保存目录数据源配置接口

Scope：admin.v1.directory-sync-config.manage
权限项：用户同步配置管理（directory-sync-config）
权限类型：管理
接口：PUT/api/openapi/v1/directory-sync/sources/{sourceId}

认证与请求头

使用应用 API Key 调用。当前接口只校验上方独立 Scope；读取、管理与执行权限互不隐含。

名称	位置	类型	必填	说明	示例
`Authorization`	header	string	是	应用 API Key，使用 Bearer 方式传递。	`Bearer qwk_***`
`X-Request-Id`	header	string	否	可选的调用追踪标识；未传入时由服务端生成。	`req-20260831-001`

请求参数

名称	位置	类型	必填	说明	示例
`sourceId`	path	`string · uuid`	必填	数据源 ID	`"<uuid>"`
`Idempotency-Key`	header	`string`	必填	幂等键，用于避免重复提交	`"<string>"`
`config_revision`	body	`integer · int64`	否	配置版本号	`1`
`credentials`	body	`OpenapifacadeDirectorySourceCredentials`	否	凭据	`-`
`default_seat`	body	`boolean`	必填	新用户默认申请席位	`false`
`deletion_alert_email`	body	`string`	否	告警邮箱	`"<string>"`
`deletion_alert_enabled`	body	`boolean`	必填	删除告警	`false`
`deletion_alert_threshold`	body	`integer · int64`	必填	删除告警阈值	`0`
`deletion_policy`	body	`string`	必填	离职处理	`"delete_user"`
`initial_scim_token`	body	`string`	否	初始 SCIM Token	`"<string>"`
`name`	body	`string`	必填	来源名称	`"<string>"`
`schedule`	body	`string`	必填	同步频率	`"manual"`
`schedule_anchor_at`	body	`string · date-time`	否	同步时间（北京时间）	`"2026-08-27T10:00:00Z"`
`settings`	body	`OpenapifacadeDirectorySourceSettings`	必填	数据源配置	`-`
`source_type`	body	`string`	必填	数据源类型	`"dingtalk"`

credentials 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`agent_id`	`string`	否	应用 Agent ID（仅写入）
`app_id`	`string`	否	应用 ID（仅写入）
`app_secret`	`string`	否	应用密钥（仅写入）
`bind_dn`	`string`	否	LDAP 绑定 DN（仅写入）
`bind_password`	`string`	否	LDAP 绑定密码（仅写入）
`client_id`	`string`	否	客户端 ID（仅写入）
`client_secret`	`string`	否	客户端密钥（仅写入）
`corp_id`	`string`	否	企业 ID（仅写入）
`secret`	`string`	否	认证密钥（仅写入）
`tenant_id`	`string`	否	租户 ID（仅写入）

settings 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`connection`	`object`	是	连接配置
`department_mapping`	`object`	是	部门映射
`mapping`	`object`	是	成员映射
`scope`	`object`	是	同步范围
`wecom`	`object`	否	企业微信部署与地址配置

settings.connection 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`client_name`	`string`	否	SCIM Client
`tls_enabled`	`boolean`	否	启用 TLS
`url`	`string`	否	服务器地址

settings.department_mapping 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`external_id`	`string`	是	第三方部门 ID（来源字段）
`name`	`string`	是	部门名称（来源字段）
`order`	`string`	否	排序（来源字段）
`parent_external_id`	`string`	否	上级第三方部门 ID（来源字段）
`status`	`string`	否	状态（来源字段）

settings.mapping 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`account`	`string`	否	账号（来源字段）
`department_external_id`	`string`	否	所属部门的第三方部门 ID（来源字段）
`email`	`string`	否	邮箱（来源字段）
`employee_no`	`string`	否	工号（来源字段）
`external_id`	`string`	是	第三方用户 ID（来源字段）
`name`	`string`	是	用户姓名（来源字段）
`phone`	`string`	否	手机号（来源字段）
`status`	`string`	否	状态（来源字段）

settings.scope 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`base_dn`	`string`	否	Base DN
`mode`	`string`	是	同步范围类型；可选值：`all`, `departments`, `base_dn`, `administrative_units`
`org_unit_external_ids`	`array<string> ｜ null`	否	范围部门（第三方部门 ID 列表）
`org_unit_filter`	`string`	否	部门过滤器
`user_filter`	`string`	否	用户过滤器

settings.wecom 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`api_base_url`	`string`	否	企业微信 API 基础地址
`authorization_url`	`string`	否	企业微信授权地址
`deployment`	`string`	是	企业微信部署类型；可选值：`standard`, `private`

请求示例

curl --request PUT \
  --url 'https://example.invalid/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"
}'

响应

200 OK

名称	类型	必填	说明	示例
`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`	`OpenapifacadeDirectorySourceSettings`	是	数据源配置	`-`
`source_type`	`string`	是	数据源类型	`"<string>"`
`status`	`string`	是	状态	`"<string>"`
`updated_by_email`	`string`	否	更新人邮箱	`"<string>"`
`updated_by_name`	`string`	否	更新人	`"<string>"`

settings 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`connection`	`object`	是	连接配置
`department_mapping`	`object`	是	部门映射
`mapping`	`object`	是	成员映射
`scope`	`object`	是	同步范围
`wecom`	`object`	否	企业微信部署与地址配置

settings.connection 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`client_name`	`string`	否	SCIM Client
`tls_enabled`	`boolean`	否	启用 TLS
`url`	`string`	否	服务器地址

settings.department_mapping 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`external_id`	`string`	是	第三方部门 ID（来源字段）
`name`	`string`	是	部门名称（来源字段）
`order`	`string`	否	排序（来源字段）
`parent_external_id`	`string`	否	上级第三方部门 ID（来源字段）
`status`	`string`	否	状态（来源字段）

settings.mapping 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`account`	`string`	否	账号（来源字段）
`department_external_id`	`string`	否	所属部门的第三方部门 ID（来源字段）
`email`	`string`	否	邮箱（来源字段）
`employee_no`	`string`	否	工号（来源字段）
`external_id`	`string`	是	第三方用户 ID（来源字段）
`name`	`string`	是	用户姓名（来源字段）
`phone`	`string`	否	手机号（来源字段）
`status`	`string`	否	状态（来源字段）

settings.scope 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`base_dn`	`string`	否	Base DN
`mode`	`string`	是	同步范围类型；可选值：`all`, `departments`, `base_dn`, `administrative_units`
`org_unit_external_ids`	`array<string> ｜ null`	否	范围部门（第三方部门 ID 列表）
`org_unit_filter`	`string`	否	部门过滤器
`user_filter`	`string`	否	用户过滤器

settings.wecom 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`api_base_url`	`string`	否	企业微信 API 基础地址
`authorization_url`	`string`	否	企业微信授权地址
`deployment`	`string`	是	企业微信部署类型；可选值：`standard`, `private`

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

default Flat business error

名称	类型	必填	说明	示例
`code`	`string`	否	Stable business error code	`"<string>"`
`detail`	`string`	是	Human-readable error description	`"<string>"`
`details`	`OpenapiErrorDetails`	否	错误详情	`-`
`error`	`string`	是	Stable HTTP error type	`"<string>"`

details 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。

字段	类型	必填	说明
`field`	`string`	否	校验失败的请求字段
`reason`	`string`	否	校验失败的原因代码
`suggestion`	`string`	否	建议使用的规范化值

{
  "code": "<string>",
  "detail": "<string>",
  "details": {
    "field": "<string>",
    "reason": "<string>",
    "suggestion": "<string>"
  },
  "error": "<string>"
}

企业微信私有化配置

企业微信保持 source_type: "wecom"。settings.wecom 为可选对象：deployment 为 standard 或 private， api_base_url 为私有化企微的 HTTPS API 基础地址；authorization_url 为可选授权地址。未配置时使用标准版固定地址；更新省略 settings.wecom 时保留原配置。私有化服务须兼容企微协议且能由服务端直接访问，禁止明文 HTTP、跳过证书校验或失败时回退公网地址。连接测试、部门读取和同步复用该地址；原属性映射、Scope 和同步策略不变。消息回调凭据在管理控制台单独配置，不通过本接口读取或写入。

​认证与请求头

​请求参数

​credentials 字段

​settings 字段

​settings.connection 字段

​settings.department_mapping 字段

​settings.mapping 字段

​settings.scope 字段

​settings.wecom 字段

​请求示例

​响应

​200 OK

​settings 字段

​settings.connection 字段

​settings.department_mapping 字段

​settings.mapping 字段

​settings.scope 字段

​settings.wecom 字段

​default Flat business error

​details 字段

​企业微信私有化配置

认证与请求头

请求参数

credentials 字段

settings 字段

settings.connection 字段

settings.department_mapping 字段

settings.mapping 字段

settings.scope 字段

settings.wecom 字段

请求示例

响应

200 OK

settings 字段

settings.connection 字段

settings.department_mapping 字段

settings.mapping 字段

settings.scope 字段

settings.wecom 字段

default Flat business error

details 字段

企业微信私有化配置