CreateIdentityProviderSyncJob - 创建身份源同步任务-智能体构建和治理平台 AgentCore-阿里云帮助中心

发起身份源手动同步

接口说明

按已保存范围发起一次用户同步，不保存配置，也不要求 syncEnabled=true。前置条件为身份源 READY 或 SYNC_FAILED、已有用户池且没有其他未完成的身份源操作。返回 taskId 只表示已受理，请调用 GetIdentityProviderSyncJob 轮询至 SUCCESS、FAILED 或 CANCELED；失败时查看 failureReason。沿用工作空间人数上限，不因范围缩小主动删除已同步用户。\n\n 授权信息：RAM 操作 agentcore:CreateIdentityProviderSyncJob，访问级别 Write，资源 ARN：acs:agentcore:{regionId}:{accountId}:workspace/{workspaceId}/identityProvider/{identityProviderType}。该资源为必需授权资源。\n\n 幂等与重试：该接口未提供 ClientToken 条件幂等参数。重复提交不保证返回同一任务；已有操作进行中会返回操作冲突，任务结束后再次提交会创建新同步任务。提交超时时先查询身份源状态，避免盲目重复发起。\n\n 调用本 API 本身免费，操作记录支持 ActionTrail 审计。\n\n 首次选择性同步流程：CreateIdentityProvider(syncOnBind=false，建议先保持 syncEnabled=false) → GetIdentityProvider 等待 READY → ListIdentityProviderDepartments 选择部门 → UpdateIdentityProvider 保存 syncScope 并等待 READY → CreateIdentityProviderSyncJob → GetIdentityProviderSyncJob 查询终态。需要增量同步时，配置回调及事件订阅后更新 syncEnabled=true。\n\n 响应示例：\njson\n{\n "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",\n "message": "success",\n "httpStatusCode": 200,\n "code": "SUCCESS",\n "success": true,\n "data": {\n "taskId": "12345678-1234-4234-8234-123456789abc",\n "status": "PENDING"\n }\n}\n

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

agentcore:CreateIdentityProviderSyncJob

create

*IdentityProvider

acs:agentcore:{#regionId}:{#accountId}:workspace/{#workspaceId}/identityProvider/{#identityProviderType}

无

请求语法

POST /workspaces/{workspaceId}/identity-providers/{identityProviderType}/sync-jobs HTTP/1.1

路径参数

名称	类型	必填	描述	示例值
workspaceId	string	是	身份源所属的 AgentCore 工作空间 ID。	ws-0123456789abcdef01234
identityProviderType	string	是	身份源类型。DingTalk 表示钉钉，Feishu 表示飞书。	DingTalk

请求参数

名称

类型

必填

描述

示例值

当前API无需请求参数

返回参数

名称	类型	描述	示例值
	object
requestId	string	请求的唯一标识。排查问题时请提供该值。	01234567-89AB-CDEF-0123-456789ABCDEF
message	string	本次 API 请求的响应消息。	success
httpStatusCode	integer	本次 API 请求的 HTTP 状态码，不表示异步任务的执行结果。	200
code	string	本次 API 请求的业务状态码。SUCCESS 表示本次请求成功，不表示异步同步任务已经完成。	SUCCESS
success	boolean	本次 API 请求是否成功。异步任务是否完成应查询任务状态。	true
data	object	本次请求返回的业务数据。	{"taskId":"12345678-1234-4234-8234-123456789abc","status":"PENDING"}
taskId	string	CreateIdentityProviderSyncJob 返回的 AgentCore 本地任务 ID，不是 AgentIdentity 的 synchronizationJobId。查询时须使用同一工作空间和身份源。	12345678-1234-4234-8234-123456789abc
status	string	PENDING：待执行；RUNNING：执行中；PAUSED：暂停；SUCCESS：成功；FAILED：失败；CANCELED：已取消。前三者为非终态，后三者为终态；应查询至终态后判断结果。	SUCCESS
currentStep	string	AgentCore 异步任务当前执行阶段；任务尚未开始执行时可能不返回。	SYNC
synchronizationJobId	string	AgentIdentity 下游同步任务 ID，尚未创建时不返回；不能代替 taskId 调用 GetIdentityProviderSyncJob。	syncjob_0123456789abcdef0123456789abcdef
syncedUserCount	integer	本地已读取并写入或更新的用户条目数，包含已有用户；不代表新增人数或同步百分比。尚无统计时不返回。	12
failureReason	string	异步任务的失败摘要；无失败信息时不返回。可结合 taskId 和 requestId 排查。	The identity provider synchronization job failed.

示例

正常返回示例

JSON格式

{
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "message": "success",
  "httpStatusCode": 200,
  "code": "SUCCESS",
  "success": true,
  "data": {
    "taskId": "12345678-1234-4234-8234-123456789abc",
    "status": "SUCCESS",
    "currentStep": "SYNC",
    "synchronizationJobId": "syncjob_0123456789abcdef0123456789abcdef",
    "syncedUserCount": 12,
    "failureReason": "The identity provider synchronization job failed."
  }
}

错误码

HTTP status code	错误码	错误信息
404	Workspace.NotFound	The specified workspace does not exist.
404	IdentityProviderNotFound	The specified identity provider does not exist in the workspace.
409	IdentityProviderOperationConflict	The identity provider is not ready for the requested operation.

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。