GetIdentityProviderSyncScope - 查询身份源同步范围-智能体构建和治理平台 AgentCore-阿里云帮助中心

查询身份源同步范围

接口说明

查询身份源下游已保存的同步范围、已选部门有效性和人数预估，不用于未保存选择的实时预估。AllAuthorized 表示应用获授权的通讯录范围，不等于整个企业组织。selectedDepartments 为空不能证明组织没有子部门。只有 estimateStatus=Ready 且返回数量时才能使用预估；缺失数量不表示 0。\n\n 授权信息：RAM 操作 agentcore:GetIdentityProviderSyncScope，访问级别 Read，资源 ARN：acs:agentcore:{regionId}:{accountId}:workspace/{workspaceId}/identityProvider/{identityProviderType}。该资源为必需授权资源。\n\n 幂等与重试：该接口只读，可重复查询。\n\n 调用本 API 本身免费，操作记录支持 ActionTrail 审计。\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 "syncScope": {\n "mode": "SelectedDepartments",\n "departmentIds": [\n "10001"\n ]\n },\n "selectedDepartments": [\n {\n "id": "10001",\n "name": "研发部",\n "exists": true\n }\n ],\n "estimateStatus": "Ready",\n "expandedDepartmentCount": 2,\n "estimatedUserCount": 12\n }\n}\n

调试

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

调试

授权信息

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

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

操作

访问级别

资源类型

条件关键字

关联操作

agentcore:GetIdentityProviderSyncScope

get

*IdentityProvider

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

无

请求语法

GET /workspaces/{workspaceId}/identity-providers/{identityProviderType}/sync-scope 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	本次请求返回的业务数据。	{"syncScope":{"mode":"SelectedDepartments","departmentIds":["10001"]},"selectedDepartments":[{"id":"10001","name":"研发部","exists":true}],"estimateStatus":"Ready","expandedDepartmentCount":2,"estimatedUserCount":12}
syncScope	object	下游已保存的同步范围；AllAuthorized 表示应用获授权的通讯录范围。	{"mode":"SelectedDepartments","departmentIds":["10001"]}
mode	string	AllAuthorized：全部授权范围，受应用通讯录授权限制；SelectedDepartments：选中部门及所有子部门。显式提交 syncScope 时必须提供有效 mode，由后端校验。	SelectedDepartments
departmentIds	array	SelectedDepartments 时至少包含一个非空部门 ID，应取自 ListIdentityProviderDepartments；AllAuthorized 时传空数组或省略。	["10001"]
	string	身份源返回的部门唯一标识，取自 ListIdentityProviderDepartments。	10001
selectedDepartments	array<object>	已保存选择的部门名称和有效性。AllAuthorized 时可为空数组；为空不表示组织没有部门。	[{"id":"10001","name":"研发部","exists":true}]
	object
id	string	身份源返回的部门唯一标识。查询该节点的子部门时，将此值作为 parentDepartmentId。	10001
name	string	身份源返回的部门名称。	研发部
exists	boolean	所选部门当前是否仍存在；false 表示该选择已失效，需重新确认同步范围。	true
estimateStatus	string	同步范围的人数预估状态。仅 Ready 时数量可用；其他状态下缺失数量不能视为 0。	Ready
expandedDepartmentCount	integer	包含子部门的部门数量预估；仅在 estimateStatus=Ready 且下游提供该值时返回。	2
estimatedUserCount	integer	已保存同步范围的用户数量预估；仅在 estimateStatus=Ready 且下游提供该值时返回。不代表已经同步的人数。	12

示例

正常返回示例

JSON格式

{
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "message": "success",
  "httpStatusCode": 200,
  "code": "SUCCESS",
  "success": true,
  "data": {
    "syncScope": {
      "mode": "SelectedDepartments",
      "departmentIds": [
        "10001"
      ]
    },
    "selectedDepartments": [
      {
        "id": "10001",
        "name": "研发部",
        "exists": true
      }
    ],
    "estimateStatus": "Ready",
    "expandedDepartmentCount": 2,
    "estimatedUserCount": 12
  }
}

错误码

HTTP status code	错误码	错误信息
502	IdentityProviderDirectoryUnavailable	Failed to query the identity provider directory.
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.

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

变更历史

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