API 概览 - Agent Studio

Connector API 提供数据导入能力：管理连接器、组织类目、上传文件、批量从 OSS 导入，并管理文件全生命周期。所有接口均通过 DashScope 网关提供服务。

调用 API 前，请先获取 API Key。

服务地址

{workspaceId} 是业务空间 ID，格式如 llm-xxxxxxxxxxxx，在控制台 业务空间管理 页面查看或创建。所有接口使用统一服务地址：

https://{workspaceId}.cn-beijing.maas.aliyuncs.com

所有接口路径前缀均为 /api/v1/connector/dash/，方法统一为 POST，参数通过 Request Body 传递。

协议约定

通过 HTTPS 访问，不支持 HTTP。
请求体和响应体均为 JSON 格式，字符集 UTF-8。
所有接口使用 POST 方法，参数通过 Request Body 传递。

通用请求头

Header	必填	说明
`Authorization`	是	`Bearer <API-Key>`，在控制台 API Key 页获取。详见鉴权说明。
`Content-Type`	是	`application/json`。

通用响应格式

所有接口返回统一的 JSON 结构。 成功响应：

{
  "code": "Success",
  "status_code": 200,
  "data": { },
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

失败响应：

{
  "code": "InvalidParameter",
  "status_code": 400,
  "message": "Required parameter missing or invalid.",
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

排查问题时，请提供 requestId。完整错误码见错误码参考。

文件上传流程

向数据中心上传文件分三步：

1. 申请租约        2. PUT 到 OSS           3. 注册文件
applyFileUploadLease  ──>  HTTP PUT 直传  ──>  addFile
返回 leaseId + 预签名 URL   返回 HTTP 200       返回 fileId

步骤	接口	关键入参	关键出参
1. 申请租约	applyFileUploadLease	`category`、`fileName`、`sizeBytes`、`contentMd5`	`leaseId`、`param.url`、`param.headers`
2. PUT 上传	（HTTP PUT，非本服务接口）	URL 和 Headers 来自步骤 1	HTTP 200
3. 注册文件	addFile	`leaseId`、`category`、`parser`	`fileId`

如需批量导入 OSS 中已有的文件，可跳过三步上传，直接调用 addFilesFromAuthorizedOss。

文件状态机

注册文件后，文件按以下状态流转：

INIT  ──>  PARSING  ──>  PARSE_SUCCESS
              │
              └──>  FAIL

通过 describeFile 或 listFile 查询当前状态。FAIL 时响应包含 parseErrorMessage。

​服务地址

​协议约定

​通用请求头

​通用响应格式

​文件上传流程

​文件状态机

服务地址

协议约定

通用请求头

通用响应格式

文件上传流程

文件状态机