启动用户同步接口

更新时间:
复制 MD 格式

同来源已有未完成任务时,本接口返回该任务,包括本地处理完成、正在等待账号与席位初始化的任务。新的 Idempotency-Key 此时也不会另建任务。请使用响应中的 run.id 查询状态;原任务结束后,使用新键才会开始新一轮读取,旧键仍返回原任务。执行默认最长六小时,从首次开始处理计算;本地提交后,账号和席位初始化默认最多等待 24 小时。等待超时返回部分成功,未完成的账号仍由后台继续修复。重复调用不刷新这些期限。SCIM 来源通过入站请求同步,不能通过本接口启动。

所需权限

所需权限

资源

Scope

资源服务

执行用户同步(执行)

directory-sync-runs

admin.v1.directory-sync-runs.execute

qwenwork-biz-service

POST /api/openapi/v1/directory-sync/runs

公共请求头

适用《通过 API 配置 QwenWork 管理后台》的“认证与请求头”章节:Authorization 必填,X-Request-Id 可选;当前接口所需 Scope 见本页。

Idempotency-Key 是否适用及必填性以本页请求参数为准,不能用追踪标识替代幂等键。

请求参数

请求体:必填;Content-Type:application/json。

名称

位置

类型

必填

说明

示例

Idempotency-Key

header

string

是

幂等键,用于避免重复提交

"<string>"

source_id

body

string · uuid

是

数据源 ID

"<uuid>"

请求示例

将 <BASE_URL> 替换为企业部署的千问办公 API 服务地址,并填写实际参数。示例中的占位值不能直接用于请求。

curl --request POST \
  --url '<BASE_URL>/api/openapi/v1/directory-sync/runs' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: <UNIQUE_REQUEST_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "source_id": "<uuid>"
}'

响应状态表

本表描述业务服务返回;网关自行生成的响应以网关契约为准,本轮未验证部署网关返回。

HTTP 状态码

触发条件

响应结构引用

客户端处理建议

202

其他未单列的业务服务错误

见本文“响应结果”

保留状态码、code 与请求标识;不要推断已提交或已回滚。

default

其他未单列的业务服务错误

见《通过 API 配置 QwenWork 管理后台》的“通用错误”结构

保留状态码、code 与请求标识;不要推断已提交或已回滚。

响应结果

名称

类型

必填

说明

示例

provenance

object

否

不可变的执行来源快照;GET 在历史快照存在时返回,旧记录无快照则省略。

-

run

object

是

同步记录

-

provenance

字段

类型

必填

说明

config_revision

integer · int64

是

捕获的配置版本

connection_identifier

object

是

固定结构的连接标识,不包含凭证

department_id_mapping

string

是

捕获的外部部门 ID 映射

user_id_mapping

string

是

捕获的外部用户 ID 映射

run

字段

类型

必填

说明

created_at

string · date-time

是

创建时间

error_code

string

否

错误码

error_summary

string

否

错误摘要

finished_at

string · date-time

否

结束时间

id

string · uuid

是

同步记录 ID

requested_by_email

string

否

发起人邮箱

requested_by_name

string

否

发起人

resource_type

string

是

资源类型

result

string

否

操作结果;可选值:success, partial_success, failure 取值:"failure"、"partial_success"、"success"

source_id

string · uuid

是

数据源 ID

source_name

string

是

来源名称

source_type

string

是

数据源类型

started_at

string · date-time

否

开始时间

stats

object

是

同步统计

status

string

是

状态;可选值:pending, running, succeeded, failed, cancelled 取值:"cancelled"、"failed"、"pending"、"running"、"succeeded"

trigger_type

string

是

触发方式;可选值:manual, scheduled, scim 取值:"manual"、"scheduled"、"scim"

provenance.connection_identifier

字段

类型

必填

说明

agent_id

string

否

来源快照标识 agent_id;按来源类型返回,不包含密钥。

api_base_url

string

否

来源快照标识 api_base_url;按来源类型返回,不包含密钥。

app_id

string

否

来源快照标识 app_id;按来源类型返回,不包含密钥。

base_dn

string

否

来源快照标识 base_dn;按来源类型返回,不包含密钥。

bind_dn

string

否

来源快照标识 bind_dn;按来源类型返回,不包含密钥。

client_id

string

否

来源快照标识 client_id;按来源类型返回,不包含密钥。

corp_id

string

否

来源快照标识 corp_id;按来源类型返回,不包含密钥。

tenant_id

string

否

来源快照标识 tenant_id;按来源类型返回,不包含密钥。

url

string

否

来源快照标识 url;按来源类型返回,不包含密钥。

run.stats

字段

类型

必填

说明

departments

object

是

部门统计

failed

integer · int64

否

失败数量

processed

integer · int64

否

已处理数量

relationships

object

是

成员关系统计

seats

object

是

席位统计

succeeded

integer · int64

否

成功数量

users

object

是

用户统计

run.stats.departments

字段

类型

必填

说明

created

integer · int64

是

部门新增数量

deactivated

integer · int64

否

部门停用数量

deleted

integer · int64

是

部门删除数量

updated

integer · int64

是

部门更新数量

run.stats.relationships

字段

类型

必填

说明

added

integer · int64

是

成员关系新增数量

removed

integer · int64

是

成员关系移除数量

returned_to_root

integer · int64

是

成员关系移回根部门数量

run.stats.seats

字段

类型

必填

说明

granted

integer · int64

是

席位授权数量

reclaimed

integer · int64

是

席位回收数量

run.stats.users

字段

类型

必填

说明

created

integer · int64

是

用户新增数量

deactivated

integer · int64

否

用户停用数量

deleted

integer · int64

是

用户删除数量

updated

integer · int64

是

用户更新数量

响应示例

202

{
  "run": {
    "created_at": "2026-08-27T10:00:00Z",
    "error_code": "<string>",
    "error_summary": "<string>",
    "finished_at": "2026-08-27T10:00:00Z",
    "id": "<uuid>",
    "requested_by_email": "<string>",
    "requested_by_name": "<string>",
    "resource_type": "<string>",
    "result": "success",
    "source_id": "<uuid>",
    "source_name": "<string>",
    "source_type": "<string>",
    "started_at": "2026-08-27T10:00:00Z",
    "stats": {
      "departments": {
        "created": 0,
        "deactivated": 0,
        "deleted": 0,
        "updated": 0
      },
      "failed": 0,
      "processed": 0,
      "relationships": {
        "added": 0,
        "removed": 0,
        "returned_to_root": 0
      },
      "seats": {
        "granted": 0,
        "reclaimed": 0
      },
      "succeeded": 0,
      "users": {
        "created": 0,
        "deactivated": 0,
        "deleted": 0,
        "updated": 0
      }
    },
    "status": "pending",
    "trigger_type": "manual"
  }
}