本文为您介绍了 OpenAPI 调用的整体流程、接口调用限制以及公共错误码。

调用方式 #

当前，智能分析 Agent 支持通过 Token 和火山引擎 TOP 网关两种方式调用，两种方式的差异说明如下：

使用流程 #

使用 Token 调用 #

整体流程说明如下，具体使用说明请参见下文方式一：使用 JWT Token 调用。

1. 为每一个 OpenAPI 调用方生成一个 ClientID 和 ClientSecret，这是调用接口的凭证。
2. 用户使用 ClientID/ ClientSecret 调用接口交换包含用户身份信息的 JWT token。
3. 用户在调用业务接口时在请求头部带上 JWT token，例如：Authorization: Bearer jwt_token 。
4. DataAgent 在接口被调用时，使用公钥校验 JWT token，完成限流检查、审计。
5. 在调用任意一个 DataAgent 接口时，为了便于后续问题的排查，建议在请求的 headers 中添加 x-request-id 和 request-id(保证唯一字符串即可)，需要两个 header 是因为 DataAgent 整体组件比较多，各个组件之间使用的标记可能不同。这两个参数会被输入到 DataAgent 的后端日志中，为您在遇到问题时进行分析和定位提供有力的支持，从而更高效地解决可能出现的故障。
6. 返回业务结果。

使用 TOP 网关调用 #

整体流程说明如下，具体使用说明请参见下文方式二：使用 TOP 网关调用。

1. 获取您使用的火山引擎账号的 Access Key ID（AK） 和 Secret Access Key（SK）。
2. 请求火山引擎 TOP 网关，网关会校验 AK/SK 的合法性，并将用户身份信息透传给下游业务服务。
3. DataAgent 在接口被调用时，需携带 AK/SK 并完成签名，再请求 TOP 网关。
4. 在调用任意一个 DataAgent 接口时，为了便于后续问题的排查，建议在请求的 headers 中添加 x-request-id 和 request-id（保证唯一字符串即可）， 需要两个 header 是因为 DataAgent 整体组件比较多，各个组件之间使用的标记可能不同。这两个参数会被输入到 DataAgent 的后端日志中，为您在遇到问题时进行分析和定位提供有力的支持，从而更高效地解决可能出现的故障。
5. 接口返回业务结果。

获取 ClientID 与 ClientSecret #

1. 在智能分析 Agent 服务中，单击顶部开放平台，进入开发者后台，单击左侧凭证管理页签。
   
2. 单击创建凭证，选择凭证类型，支持设置用户或系统（仅支持系统管理员）。
   
3. 创建完成后，复制申请得到的ClientID 和 ClientSecret。
   

   注意

   务必妥善保密管理 ClientID与ClientSecret，这是调用接口的凭证，暴露给其他用户将导致数据泄露风险。

请求说明 #

请求地址：不同环境调用接口使用的接口地址不同。
对于火山引擎 SaaS 环境，访问地址为https://console.volcengine.com/bi/datawind，则接口地址前缀为https://console.volcengine.com/bi/datawind/aeolus。

请求示例 #

# 替换clientId和clientSecret
curl --location --request POST 'https://console.volcengine.com/bi/datawind/aeolus/api/v3/openapi/jwtToken' \
-H 'Content-Type: application/json' \
# 注意这里的 region 应与账号所在区域保持一致，可选值为：cn-shanghai、cn-beijing
-H "x-vedi-region: cn-shanghai" \
-d '{
  "metadata": {
    "clientId": "{clientId}",
    "clientSecret": "{clientSecret}",
    "proxyUser": "abc****@21**********",
    "expire": 3600
  }
}'

请求参数 #

返回参数 #

返回示例 #

{
    "code": "aeolus/ok",
    "data": {
        "jwtToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.ey*****************************************************************************************************************************************************************************.********************-*************************************************************************************-****************************************************************************************************************************-***-********************************************-******************************************************-*************************-****************************************************************************-************-*************************************-*********************************************************************************************************************************************************-****************-******************5sus",
        "proxyUser": "user_1"
    },
    "msg": "成功"
}

使用 Token 调用 #

您在调用接口时，需要在请求头部带上 jwtToken 的内容，例如：Authorization: Bearer jwt_token
使用 curl 的调用 current user 接口示例如下：

curl -X GET 'https://{domain}/aeolus/api/v3/open/misc/current_user' \
-H 'Authorization: Bearer jwt_token'
# 注意这里的 region 应与账号所在区域保持一致，可选值为：cn-shanghai、cn-beijing
-H "x-vedi-region: cn-shanghai" \

获取访问秘钥 #

使用 TOP 网关调用 API 前，需获取您账号的 Access Key ID 和 Secret Access Key，获取方式请参见Access Key（密钥）管理。

API 签名配置 #

API 签名用于验证请求者身份并防止请求被篡改，调用前，请按照火山引擎签名机制配置操作，具体方法请参见签名方法。

使用 TOP 网关调用 #

您可按需使用调用工具调用 API 接口，推荐 SDK 方式调用。
GET 和 POST 请求示例如下：

# 智能问数
POST https://open.volcengineapi.com?Action=InnerDataAgentDataQueryAdaQuery&Version=2025-05-13
# 获取智能体列表
GET https://open.volcengineapi.com?Action=InnerDataAgentGetAgentList&Version=2025-05-13

调用时必须在 Header 中携带地域信息，二选一即可：

# 北京地域
x-vedi-region: cn-beijing
# 上海地域
x-vedi-region: cn-shanghai 

为了保障服务稳定性与阻挡恶意攻击，DataAgent 后端采用以下方法限制请求：

1. 限流（目前接口对外服务承载能力已达到较高水平，如仍不满足需求，可联系火山引擎技术支持团队申请修改）；
2. 封禁，用于保留一些不开放的 API 或者临时封禁用户的异常请求；
3. 审计，每一次 OpenAPI 调用均会被记录，包括调用方、接口、参数、调用时间。

详情可查看参考：公共错误码。