GetAgenticAgentByInstallToken - 查询 install token 关联的 Agent-数据管理 DMS-阿里云帮助中心

根据 install token 查询其兑换后关联的 Agent 信息。尚未完成兑换时，Data 为空。

接口说明

传入 IssueAgenticInstallToken 签发的 install token，查询该令牌完成兑换后生成或复用的 Agent。install token 不存在时请求失败；令牌尚未完成兑换，或关联的凭证、Agent 不存在时，接口调用成功但 Data 为空。

调试

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

调试

授权信息

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

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

操作

访问级别

资源类型

条件关键字

关联操作

dms:GetAgenticAgentByInstallToken

get

*全部资源

*

无

请求参数

名称	类型	必填	描述	示例值
InstallToken	string	是	IssueAgenticInstallToken 签发的一次性安装令牌。令牌以 dit_ 开头，后跟 40 位 URL-safe Base64 字符，总长度为 44 个字符。	dit_0123456789abcdefghijklmnopqrstuvwxyzABCD

返回参数

名称	类型	描述	示例值
	object	Schema of Response
RequestId	string	本次请求的唯一标识，用于问题排查与日志关联。	1AD222E9-E606-4A42-BF6C-2C4DD51BD5E7
Success	boolean	本次请求是否成功。true 表示查询成功；false 表示失败，此时可结合 ErrorCode 与 ErrorMessage 定位原因。
ErrorCode	string	请求失败时返回的错误码，用于程序判断失败类型；请求成功时为空。	INSTALL_TOKEN_INVALID
ErrorMessage	string	请求失败时返回的错误描述信息，便于人工定位问题；请求成功时为空。	install_token not found
Data	object	install token 已完成兑换时返回关联的 Agent 信息。令牌尚未完成兑换，或关联的凭证、Agent 不存在时为空。
AgentId	string	Agent 的唯一标识。	agent-7f3c9a2b
AgentName	string	Agent 的名称。	my-data-agent
Description	string	Agent 的描述信息；未设置时为空。	用于数据分析的 Agent
OwnerId	string	Agent 归属用户的 ID。	27400000000000001
AgentType	string	Agent 的权限类型。取值包括 HUMAN_BOUND（继承用户权限）、PERMISSION_NARROW（在用户权限基础上收窄）、和 STANDALONE（独立权限）。install token 兑换链路生成的 Agent 类型为 HUMAN_BOUND。	HUMAN_BOUND
CreationType	string	Agent 的创建方式。auto 表示系统自动创建，manual 表示用户手动创建；install token 兑换链路生成的 Agent 为 auto。	auto
Status	string	Agent 的状态。active 表示已启用，disabled 表示已停用。	active
CreatedAt	string	Agent 的创建时间，格式为 yyyy-MM-dd HH:mm:ss。	2026-07-13 10:30:00
ActiveApiKeyPrefixes	array	Agent 名下未吊销且未过期的 Access Token 可见前缀列表；未返回或没有符合条件的 Access Token 时为空。前缀仅用于识别凭证，不包含完整 Secret。
	string	一个未吊销且未过期的 Access Token 的可见前缀。	dms_sk_3f9a

示例

正常返回示例

JSON格式

{
  "RequestId": "1AD222E9-E606-4A42-BF6C-2C4DD51BD5E7",
  "Success": true,
  "ErrorCode": "INSTALL_TOKEN_INVALID",
  "ErrorMessage": "install_token not found",
  "Data": {
    "AgentId": "agent-7f3c9a2b",
    "AgentName": "my-data-agent",
    "Description": "用于数据分析的 Agent",
    "OwnerId": "27400000000000001",
    "AgentType": "HUMAN_BOUND",
    "CreationType": "auto",
    "Status": "active",
    "CreatedAt": "2026-07-13 10:30:00",
    "ActiveApiKeyPrefixes": [
      "dms_sk_3f9a"
    ]
  }
}

错误码

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

变更历史

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