千问办公官方帮助中心（阿里云）

读取指定同步任务的状态、处理结果、用户和部门变更统计以及错误摘要。用于在提交同步任务后确认是否完成、是否出现部分成功或失败。

所需权限

所需权限	资源	Scope	资源服务
用户同步任务读取（读取）	directory-sync-runs	admin.v1.directory-sync-runs.read	qwenwork-biz-service

HELPCODEESCAPE-http
GET /api/openapi/v1/directory-sync/runs/{runId}

认证与请求头

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

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

请求参数

名称	位置	类型	必填	说明	示例
runId	path	string · uuid	必填	需要操作的同步任务标识。	"\<uuid\>"

请求示例

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

HELPCODEESCAPE-text
curl --request GET \
  --url '<BASE_URL>/api/openapi/v1/directory-sync/runs/<runId>' \
  --header 'Authorization: Bearer <API_KEY>'

响应

200 请求成功，返回当前或更新后的数据。

名称	类型	必填	说明	示例
run	OpenapifacadeDirectorySyncRun	是	本次同步任务的状态和结果。	\{"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"\}
run.created_at	string · date-time	是	此记录的创建时间。	"2026-08-27T10:00:00Z"
run.error_code	string	否	同步失败时返回的错误码。	"\<string\>"
run.error_summary	string	否	同步错误的简要说明。	"\<string\>"
run.finished_at	string · date-time	否	同步任务执行结束的时间。	"2026-08-27T10:00:00Z"
run.id	string · uuid	是	此记录的唯一标识，查询、更新或删除对应记录时使用。	"\<uuid\>"
run.requested_by_email	string	否	发起本次同步的操作者邮箱。	"\<string\>"
run.requested_by_name	string	否	发起本次同步的操作者名称。	"\<string\>"
run.resource_type	string	是	此次记录涉及的资源类型。	"\<string\>"
run.result	string	否	同步处理结果：success 全部成功，partial_success 部分成功，failure 失败。	"success"
run.source_id	string · uuid	是	本次同步使用的数据源标识。	"\<uuid\>"
run.source_name	string	是	本次同步所用数据源的名称。	"\<string\>"
run.source_type	string	是	通讯录来源类型，用于选择钉钉、飞书、企业微信、AD、LDAP、Entra ID 或 SCIM 的接入方式。	"\<string\>"
run.started_at	string · date-time	否	同步任务开始执行的时间。	"2026-08-27T10:00:00Z"
run.stats	OpenapifacadeDirectorySyncRunStats	是	本次同步的用户、部门、关系及席位变更统计。	\{"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}}
run.stats.departments	OpenapifacadeDirectorySyncChangeCounts	是	本次同步中部门变更的数量。	\{"created":0,"deactivated":0,"deleted":0,"updated":0\}
run.stats.departments.created	integer · int64	是	本次同步新增的对象数量。	0
run.stats.departments.deactivated	integer · int64	否	本次同步停用的用户数量。	0
run.stats.departments.deleted	integer · int64	是	本次同步删除的对象数量。	0
run.stats.departments.updated	integer · int64	是	本次同步更新的对象数量。	0
run.stats.failed	integer · int64	否	本次任务处理失败的对象数量。	0
run.stats.processed	integer · int64	否	本次任务已处理的对象数量。	0
run.stats.relationships	OpenapifacadeDirectorySyncRelationshipCounts	是	本次同步中部门归属关系的变更数量。	\{"added":0,"removed":0,"returned_to_root":0\}
run.stats.relationships.added	integer · int64	是	本次同步新增的部门归属关系数量。	0
run.stats.relationships.removed	integer · int64	是	本次同步移除的部门归属关系数量。	0
run.stats.relationships.returned_to_root	integer · int64	是	本次同步后回到根部门的用户数量。	0
run.stats.seats	OpenapifacadeDirectorySyncSeatCounts	是	本次同步中席位分配和回收的数量。	\{"granted":0,"reclaimed":0\}
run.stats.seats.granted	integer · int64	是	本次同步分配的席位数量。	0
run.stats.seats.reclaimed	integer · int64	是	本次同步回收的席位数量。	0
run.stats.succeeded	integer · int64	否	本次任务处理成功的对象数量。	0
run.stats.users	OpenapifacadeDirectorySyncChangeCounts	是	本次同步中用户新增、更新、停用和删除的数量。	\{"created":0,"deactivated":0,"deleted":0,"updated":0\}
run.stats.users.created	integer · int64	是	本次同步新增的对象数量。	0
run.stats.users.deactivated	integer · int64	否	本次同步停用的用户数量。	0
run.stats.users.deleted	integer · int64	是	本次同步删除的对象数量。	0
run.stats.users.updated	integer · int64	是	本次同步更新的对象数量。	0
run.status	string	是	同步任务状态：pending 等待执行，running 执行中，succeeded 执行成功，failed 执行失败，cancelled 已取消。	"pending"
run.trigger_type	string	是	触发方式：manual 为手动，scheduled 为定时，scim 为 SCIM 请求。	"manual"

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

default 请求失败，返回错误码和错误详情。

名称	类型	必填	说明	示例
code	string	否	用于程序判断错误原因的稳定业务错误码。	"\<string\>"
detail	string	是	便于阅读的错误说明。	"\<string\>"
details	OpenapiErrorDetails	否	字段校验失败时的详细信息。	\{"field":"\<string\>","reason":"\<string\>","suggestion":"\<string\>"\}
details.field	string	否	未通过校验的请求字段。	"\<string\>"
details.reason	string	否	稳定的校验失败原因，用于判断字段为何不合法。	"\<string\>"
details.suggestion	string	否	建议采用的规范化字段值。	"\<string\>"
error	string	是	稳定的 HTTP 错误类型。	"\<string\>"

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