volcengine-api

Volcengine API 查询助手

通过查询 API Explorer，使用权威且最新的信息回答用户关于 Volcengine API 的问题。

适用场景

场景	示例问题
查找 API	“如何列出 ECS 实例？”，“是否有批量创建标签的 API？”
查询参数	“RunInstances 的必填参数有哪些？”，“ChargeType 接受哪些值？”
响应结构	“DescribeInstances 会返回哪些字段？”，“Status 有哪些状态？”
参数依赖关系	“如果设置了 Ipv6Isp，Ipv6MaskLen 应该如何填写？”，“什么情况下需要填写 SpotPriceLimit？”
分页	“如何对实例查询进行分页？”，“NextToken 如何工作？”
错误码	“InvalidInstanceId.NotFound 是什么意思？”，“CreateVpc 返回 QuotaExceeded”
浏览服务	“ECS 有哪些 API？”，“VPC 支持哪些操作？”
API 对比	“DescribeInstances 和 DescribeInstancesByIds 有什么区别？”

工作流

步骤 1：理解用户意图

判断用户想要了解什么：

意图	特征	查询路径
查找 API	描述某项操作，但不知道 API 名称	搜索（2e）或服务（2a）-> API 列表（2c）-> 详情（2d）
查询参数	知道 API 名称，询问参数、枚举值或必填字段	直接查看详情（2d）
查询响应	询问返回字段或状态值	直接查看详情（2d），重点关注响应架构
查询参数依赖关系	询问“X 在什么情况下必填？”或“X 与 Y 有什么关系？”	直接查看详情（2d），重点关注描述中的条件规则
查询错误码	提供错误码或错误消息	错误码处理（步骤 3）
浏览服务	询问某项服务提供哪些功能	服务（2a）-> API 列表（2c）
对比 API	询问两个 API 的区别	分别查询两者的详情（2d），对比参数和功能

步骤 2：逐步查询 API 信息

根据已知信息，从适当的子步骤开始。当用户用自然语言描述需求时，使用搜索（2e）通常比逐级浏览更快。

2a. 查询服务列表（服务未知时）

GET https://api.volcengine.com/api/common/explorer/services

响应中的每项服务都包含：

• ServiceCode：服务标识符（例如，ecs、vpc）
• ServiceCn：中文名称（例如，“云服务器”、“私有网络”）
• Product：产品标识符（例如，ECS、VPC）
• RegionType：regional 或 global

根据用户的描述，匹配最合适的 ServiceCode。

2b. 查询版本列表（版本未知时）

GET https://api.volcengine.com/api/common/explorer/versions?ServiceCode={ServiceCode}

每个版本都包含：

• Version：版本字符串（例如，2020-04-01）
• IsDefault：1 表示默认版本

优先选择 IsDefault=1 的版本。如果没有标记为默认的版本，则使用最新版本。

2c. 查询 API 列表（具体 API 未知时）

GET https://api.volcengine.com/api/common/explorer/apis?ServiceCode={ServiceCode}&Version={Version}&APIVersion={Version}

响应按类别对 API 进行分组。每个 API 都包含：

• Action：API 名称（例如，DescribeInstances）
• NameCn：中文名称（例如，“查询实例列表”）
• ApiGroup：分组名称（例如，“实例”、“镜像”）
• Description：功能说明
• UsageScenario：使用场景
• Attentions：限制和注意事项

根据 Action、NameCn 和 Description 匹配用户意图。

2d. 查询 API 详情（核心步骤）

GET https://api.volcengine.com/api/common/explorer/api-swagger?ServiceCode={ServiceCode}&Version={Version}&APIVersion={Version}&ActionName={ActionName}

返回该 API 的完整 Swagger/OpenAPI 规范。按以下方式提取关键信息。

HTTP 方法

paths["/{ActionName}"] 下的键（get 或 post）表示 HTTP 方法。

请求参数

参数位置取决于 HTTP 方法：

GET 请求： 参数位于 paths["/{ActionName}"].get.parameters 中。每个参数包括：

• name：参数名称
• required：是否必填
• schema.type：数据类型
• schema.description：参数说明（通常包含枚举值、条件规则和值范围）
• schema.enum：允许的值（如有）
• schema.default：默认值（如有）
• schema.example：示例值（如有）

GET 参数中的数组和嵌套对象遵循以下命名约定：

• 数组：ParamName.N（N 从 1 开始），例如 InstanceIds.1、InstanceIds.2
• 嵌套对象：Parent.Child，例如 TagFilters.N.Key、TagFilters.N.Values.N

POST 请求： 参数位于 paths["/{ActionName}"].post.requestBody.content["application/json"].schema 中，使用 JSON Schema：

• properties：按名称列出的参数定义
• required：必填参数名称数组

POST 参数通常具有需要递归解析的嵌套结构：

• type: object -> 检查 properties 中的子参数
• type: array -> 检查 items 中的元素结构
• $ref: "#/components/schemas/XxxObject" -> 在 components.schemas 中查找定义并递归展开

以树形结构呈现嵌套参数：

- InstanceId (string, required): instance ID
- DatabasePrivileges (array, optional): database privilege list
  - AccountName (string, required): account name
  - AccountPrivilege (string, required): privilege type — enum: ReadWrite, ReadOnly, ...
  - AccountPrivilegeDetail (string, optional): privilege detail, comma-separated

参数依赖关系

许多参数存在条件依赖关系，通常在 description 字段中说明。请注意：

• 条件必填：例如，“EnableIpv6 为 true 时必填”
• 互斥：例如，“指定 Ipv6CidrBlock 时，将忽略 Ipv6MaskLen”
• 取值约束：例如，“Ipv6Isp 为 BGP 时，仅支持 56”
• 前置条件：例如，“设置 TagFilters.N.Key 后，才能设置 TagFilters.N.Values.N”

请在回答中突出这些依赖关系，帮助用户避免配置错误。

分页参数

Volcengine API 使用两种常见的分页模式，可通过 Swagger 参数识别：

• 基于令牌： 使用 MaxResults（每页大小）+ NextToken（续传令牌）。响应中包含 NextToken；值为空表示最后一页。
• 基于偏移量： 使用 PageSize + PageNumber（或 Offset/Limit）。响应中包含 TotalCount。

请注明 API 使用的分页模式，以及默认值和上限。

响应结构

响应 Schema 定义在 paths["/{ActionName}"].{method}.responses["200"].content["application/json"].schema 中，也可能通过 $ref 引用 components.schemas。

响应关键信息：

• 字段名称、类型和说明
• 枚举字段及其可能的值（例如，Status：RUNNING / STOPPED / CREATING）
• 嵌套对象结构（例如，Instances 数组中每个项目的字段）

info.x-demo 部分也提供了有用的参考信息——responseDemo[0].Code 展示了完整的响应结构及示例值。

请求/响应示例

在 info.x-demo 数组中：

• requestDemo[0].Code：请求示例（展示如何填写参数）
• responseDemo[0].Code：响应示例（展示包含示例值的完整返回结构）

这些是官方示例，参考价值很高。请主动将其纳入回答。

关联错误代码

在 paths["/{ActionName}"].{method}.responses["x-error-code"].content["application/json"].schema.oneOf 中，每个错误代码都包含：

• code：错误代码标识符（例如，InvalidInstanceId.NotFound）
• http_code：HTTP 状态码（例如，400、404、409、429、500）
• message：英文说明
• description：中文说明

2e. 搜索 API（快速查找）

当用户用自然语言描述需求时，搜索通常是最快捷的方式。此方法可与步骤 2a–2c 配合使用。

GET https://api.volcengine.com/api/common/search/all?Query={keyword}&Channel=api

搜索词可以使用中文或英文。如果某个关键词的搜索结果不理想，可以尝试同义词、不同的粒度，或采用英文 Action 名称格式（例如 “DescribeXxx”）。

每条结果包含：

• BizInfo.Action：API 名称
• BizInfo.ServiceCode：服务标识符
• BizInfo.ServiceCn：服务中文名称
• BizInfo.Version：版本
• Highlight：匹配的高亮文本

找到目标 API 后，使用步骤 2d 获取完整详情。

步骤 3：处理错误码查询

错误码查询需要特殊处理，因为同一个错误码（例如 InvalidParameter）可能出现在数十个 API 中，且含义各不相同。

常见错误码类别

类别	常见模式	典型原因
参数错误	InvalidParameter、InvalidParameterValue、MissingParameter	参数名称拼写错误、参数值超出枚举范围、缺少必填参数
资源不存在	InvalidXxx.NotFound、ResourceNotFound	资源 ID 错误、资源位于其他区域、资源已被删除
资源状态	InvalidXxx.InvalidStatus、IncorrectInstanceStatus	当前资源状态不允许此操作（例如，未停止实例就修改配置）
配额/限制	QuotaExceeded、LimitExceeded	超出账户配额或 API 速率限制
权限不足	UnauthorizedOperation、Forbidden	IAM 策略未授权、子账户缺少权限
限流	Throttling、RequestLimitExceeded	API 调用频率过高——降低请求频率或使用指数退避
服务端错误	InternalError、ServiceUnavailable	临时服务端问题，通常可以重试
资源冲突	ResourceInUse、DuplicateXxx、OperationConflict	资源正在使用，或名称已存在

用户提供了具体 API 名称时

通过步骤 2d 查询 API Swagger，并在 x-error-code 中查找错误码。这是最准确的方式，因为同一个错误码在不同 API 中可能有不同含义。

结合 description（中文）和 message（英文）字段，提供：

1. 错误含义
2. 此 API 中的具体触发条件
3. 故障排查步骤和解决建议

用户只提供错误码时

1. 先询问上下文：询问是哪个 API 触发了错误，以便进行准确诊断。同一个 InvalidParameter 在 RunInstances 和 CreateVpc 中的含义完全不同。
2. 用户提供了服务名称，但未提供 API 名称时：根据错误模式和上下文推断最可能的 API，然后查询其 Swagger 进行确认。
3. 备用搜索：如果用户无法提供更多上下文，请使用错误码搜索端点：

GET https://api.volcengine.com/api/common/search/all?Query={error_code}&Channel=error_code

每条结果包含：

• Type：error_code
• BizInfo.ServiceCode：服务标识符
• BizInfo.ServiceCn：服务中文名称
• BizInfo.Version：版本
• URL：错误码文档链接
• Highlight：匹配的高亮文本

由于同一个错误码会出现在多个服务中，搜索结果可能很多。请根据用户提供的上下文（服务名称、操作类型、场景）进行筛选。

步骤 4：组织回答

根据问题类型组织清晰、专业的回答。核心原则：围绕用户的问题展开——提取用户需要的信息，而不是倾倒整个 Swagger 的内容。

查找 API

1. 推荐 API 并说明原因
2. 简要介绍其功能和使用场景
3. 列出核心必填参数
4. 如果有多个候选项，比较其使用场景并让用户选择

查询参数

1. 说明 HTTP 方法（GET/POST）
2. 先列出必填参数：包括类型、描述和枚举值
3. 对嵌套参数使用树形结构，并在每一层标明必填/可选
4. 参数依赖关系：突出显示条件必填项、互斥项和值约束
5. 单独描述分页模式和默认值
6. 展示请求示例（来自 x-demo）
7. 按功能对可选参数分组（筛选、排序、高级配置），并简要列出

查询响应结构

1. 列出关键返回字段及其类型和描述
2. 展示枚举字段的所有可能值
3. 对嵌套对象使用树形结构
4. 展示响应示例（来自 x-demo responseDemo）

查询错误码

1. 错误含义（中文和英文描述）
2. 错误类别（参数错误/资源未找到/权限不足等）
3. 常见原因
4. 具体排查步骤和解决建议
5. 对于限流错误，建议重试策略

浏览服务能力

1. 按 ApiGroup 整理 API 列表
2. 为每个 API 展示 Action 名称 + 中文名称 + 一句话描述
3. 如果 API 较多，优先展示核心/常用 API

比较 API

1. 描述每个 API 的功能用途
2. 比较适用场景
3. 比较参数差异（哪个更简单、哪个更灵活）
4. 提供使用建议

查询效率提示

• 已知 API 名称：直接进入 2d，一步完成
• 已知服务名称：依次执行 2b -> 2c -> 2d，或通过 2e 并行搜索
• 只有自然语言描述：优先使用 2e 搜索，比逐级浏览更快
• 完全不确定：结合使用 2a（服务列表）+ 2e（关键词搜索）
• 查询错误码：如果知道 API 名称，进入 2d；否则先向用户询问上下文

重要说明

• 始终从 API Explorer 端点获取最新数据——Volcengine API 更新频繁，因此不要依赖记忆
• 回答语言应与用户的语言一致（中文问题 -> 中文回答，英文问题 -> 英文回答）
• 如果用户的描述有歧义，应列出可能的选项并请用户确认，不要猜测
• 如果用户需要可运行的 SDK 代码，请引导其使用 volcengine-sdk-generator skill
• 如果用户需要基于 CLI 的操作，请引导其使用 volcengine-cli skill
• 展示参数信息时，描述字段中的枚举值、条件规则和值范围最有价值——不要省略
• 如果查询过程中出现网络错误，应告知用户并建议稍后重试