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

## 所需权限
<table> <thead> <tr> <td><p><b>所需权限</b></p></td> <td><p><b>资源</b></p></td> <td><p><b>Scope</b></p></td> <td><p><b>资源服务</b></p></td> </tr> </thead> <tbody> <tr> <td><p>执行用户同步（执行）</p></td> <td><p>directory-sync-runs</p></td> <td><p>admin.v1.directory-sync-runs.execute</p></td> <td><p>qwenwork-biz-service</p></td> </tr> </tbody> </table>

```
HELPCODEESCAPE-http
POST /api/openapi/v1/directory-sync/runs
```

## 公共请求头
适用《通过 API 配置 QwenWork 管理后台》的"认证与请求头"章节：`Authorization` 必填，`X-Request-Id` 可选；当前接口所需 Scope 见本页。

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

## 请求参数
请求体：必填；Content-Type：application/json。
<table> <thead> <tr> <td><p><b>名称</b></p></td> <td><p><b>位置</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> <td><p><b>示例</b></p></td> </tr> </thead> <tbody> <tr> <td><p>Idempotency-Key</p></td> <td><p>header</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>幂等键，用于避免重复提交</p></td> <td><p>"\&lt;string\&gt;"</p></td> </tr> <tr> <td><p>source_id</p></td> <td><p>body</p></td> <td><p>string · uuid</p></td> <td><p>是</p></td> <td><p>数据源 ID</p></td> <td><p>"\&lt;uuid\&gt;"</p></td> </tr> </tbody> </table>

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

```
HELPCODEESCAPE-curl
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>"
}'
```

## 响应状态表
本表描述业务服务返回；网关自行生成的响应以网关契约为准，本轮未验证部署网关返回。
<table> <thead> <tr> <td><p><b>HTTP 状态码</b></p></td> <td><p><b>触发条件</b></p></td> <td><p><b>响应结构引用</b></p></td> <td><p><b>客户端处理建议</b></p></td> </tr> </thead> <tbody> <tr> <td><p>202</p></td> <td><p>其他未单列的业务服务错误</p></td> <td><p>见本文"响应结果"</p></td> <td><p>保留状态码、code 与请求标识；不要推断已提交或已回滚。</p></td> </tr> <tr> <td><p>default</p></td> <td><p>其他未单列的业务服务错误</p></td> <td><p>见《通过 API 配置 QwenWork 管理后台》的"通用错误"结构</p></td> <td><p>保留状态码、code 与请求标识；不要推断已提交或已回滚。</p></td> </tr> </tbody> </table>

## 响应结果
<table> <thead> <tr> <td><p><b>名称</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> <td><p><b>示例</b></p></td> </tr> </thead> <tbody> <tr> <td><p>provenance</p></td> <td><p>object</p></td> <td><p>否</p></td> <td><p>不可变的执行来源快照；GET 在历史快照存在时返回，旧记录无快照则省略。</p></td> <td><p><code>-</code></p></td> </tr> <tr> <td><p>run</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>同步记录</p></td> <td><p><code>-</code></p></td> </tr> </tbody> </table>

### provenance

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>config_revision</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>捕获的配置版本</p></td> </tr> <tr> <td><p>connection_identifier</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>固定结构的连接标识，不包含凭证</p></td> </tr> <tr> <td><p>department_id_mapping</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>捕获的外部部门 ID 映射</p></td> </tr> <tr> <td><p>user_id_mapping</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>捕获的外部用户 ID 映射</p></td> </tr> </tbody> </table>

### run

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>created_at</p></td> <td><p>string · date-time</p></td> <td><p>是</p></td> <td><p>创建时间</p></td> </tr> <tr> <td><p>error_code</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>错误码</p></td> </tr> <tr> <td><p>error_summary</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>错误摘要</p></td> </tr> <tr> <td><p>finished_at</p></td> <td><p>string · date-time</p></td> <td><p>否</p></td> <td><p>结束时间</p></td> </tr> <tr> <td><p>id</p></td> <td><p>string · uuid</p></td> <td><p>是</p></td> <td><p>同步记录 ID</p></td> </tr> <tr> <td><p>requested_by_email</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>发起人邮箱</p></td> </tr> <tr> <td><p>requested_by_name</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>发起人</p></td> </tr> <tr> <td><p>resource_type</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>资源类型</p></td> </tr> <tr> <td><p>result</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>操作结果；可选值：success, partial_success, failure 取值："failure"、"partial_success"、"success"</p></td> </tr> <tr> <td><p>source_id</p></td> <td><p>string · uuid</p></td> <td><p>是</p></td> <td><p>数据源 ID</p></td> </tr> <tr> <td><p>source_name</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>来源名称</p></td> </tr> <tr> <td><p>source_type</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>数据源类型</p></td> </tr> <tr> <td><p>started_at</p></td> <td><p>string · date-time</p></td> <td><p>否</p></td> <td><p>开始时间</p></td> </tr> <tr> <td><p>stats</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>同步统计</p></td> </tr> <tr> <td><p>status</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>状态；可选值：pending, running, succeeded, failed, cancelled 取值："cancelled"、"failed"、"pending"、"running"、"succeeded"</p></td> </tr> <tr> <td><p>trigger_type</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>触发方式；可选值：manual, scheduled, scim 取值："manual"、"scheduled"、"scim"</p></td> </tr> </tbody> </table>

### provenance.connection_identifier

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>agent_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>来源快照标识 agent_id；按来源类型返回，不包含密钥。</p></td> </tr> <tr> <td><p>api_base_url</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>来源快照标识 api_base_url；按来源类型返回，不包含密钥。</p></td> </tr> <tr> <td><p>app_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>来源快照标识 app_id；按来源类型返回，不包含密钥。</p></td> </tr> <tr> <td><p>base_dn</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>来源快照标识 base_dn；按来源类型返回，不包含密钥。</p></td> </tr> <tr> <td><p>bind_dn</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>来源快照标识 bind_dn；按来源类型返回，不包含密钥。</p></td> </tr> <tr> <td><p>client_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>来源快照标识 client_id；按来源类型返回，不包含密钥。</p></td> </tr> <tr> <td><p>corp_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>来源快照标识 corp_id；按来源类型返回，不包含密钥。</p></td> </tr> <tr> <td><p>tenant_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>来源快照标识 tenant_id；按来源类型返回，不包含密钥。</p></td> </tr> <tr> <td><p>url</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>来源快照标识 url；按来源类型返回，不包含密钥。</p></td> </tr> </tbody> </table>

### run.stats

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>departments</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>部门统计</p></td> </tr> <tr> <td><p>failed</p></td> <td><p>integer · int64</p></td> <td><p>否</p></td> <td><p>失败数量</p></td> </tr> <tr> <td><p>processed</p></td> <td><p>integer · int64</p></td> <td><p>否</p></td> <td><p>已处理数量</p></td> </tr> <tr> <td><p>relationships</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>成员关系统计</p></td> </tr> <tr> <td><p>seats</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>席位统计</p></td> </tr> <tr> <td><p>succeeded</p></td> <td><p>integer · int64</p></td> <td><p>否</p></td> <td><p>成功数量</p></td> </tr> <tr> <td><p>users</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>用户统计</p></td> </tr> </tbody> </table>

#### run.stats.departments

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>created</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>部门新增数量</p></td> </tr> <tr> <td><p>deactivated</p></td> <td><p>integer · int64</p></td> <td><p>否</p></td> <td><p>部门停用数量</p></td> </tr> <tr> <td><p>deleted</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>部门删除数量</p></td> </tr> <tr> <td><p>updated</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>部门更新数量</p></td> </tr> </tbody> </table>

#### run.stats.relationships

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>added</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>成员关系新增数量</p></td> </tr> <tr> <td><p>removed</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>成员关系移除数量</p></td> </tr> <tr> <td><p>returned_to_root</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>成员关系移回根部门数量</p></td> </tr> </tbody> </table>

#### run.stats.seats

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>granted</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>席位授权数量</p></td> </tr> <tr> <td><p>reclaimed</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>席位回收数量</p></td> </tr> </tbody> </table>

#### run.stats.users

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>created</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>用户新增数量</p></td> </tr> <tr> <td><p>deactivated</p></td> <td><p>integer · int64</p></td> <td><p>否</p></td> <td><p>用户停用数量</p></td> </tr> <tr> <td><p>deleted</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>用户删除数量</p></td> </tr> <tr> <td><p>updated</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>用户更新数量</p></td> </tr> </tbody> </table>

## 响应示例
`202`

```
HELPCODEESCAPE-json
{
  "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"
  }
}
```