同来源已有未完成任务时,本接口返回该任务,包括本地处理完成、正在等待账号与席位初始化的任务。新的 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"
}
}