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 を比較する	2 つの 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 を使って、ユーザーの意図に合った API を特定します。

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 リクエスト： パラメーターは JSON Schema を使用する paths["/{ActionName}"].post.requestBody.content["application/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.Values.N を指定するには、先に TagFilters.N.Key を設定する必要があります」

ユーザーが設定ミスを避けられるよう、回答ではこれらの依存関係を明示してください。

ページネーションパラメーター

Volcengine API では、Swagger パラメーターから判別できる、次の 2 つの一般的なページネーション方式が使われます。

• トークンベース：MaxResults（ページサイズ）と NextToken（継続トークン）を使用します。レスポンスには NextToken が含まれ、値が空の場合は最後のページです。
• オフセットベース：PageSize と PageNumber（または Offset／Limit）を使用します。レスポンスには TotalCount が含まれます。

API が使用するページネーション方式と、デフォルト値および上限値を明記してください。

レスポンス構造

レスポンススキーマは 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

検索語は中国語または英語で指定できます。キーワード 1 つで適切な結果が得られない場合は、同義語、異なる粒度、または英語の 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. API リストを ApiGroup ごとに整理します
2. 各 API について、Action 名＋中国語名＋1 行の説明を示します
3. API が多い場合は、主要なものやよく使われるものを優先します

API の比較

1. 各 API の機能上の目的を説明します
2. 適用シナリオを比較します
3. パラメーターの違いを比較します（どちらがシンプルか、どちらが柔軟か）
4. 使用方法を推奨します

クエリ効率化のヒント

• API 名が分かっている場合：2d に直接進みます — 1 ステップです
• サービス名が分かっている場合：2b -> 2c -> 2d の順に進むか、2e で並行検索します
• 自然言語の説明しかない場合：階層をたどって閲覧するより速い 2e 検索を推奨します
• まったく分からない場合：2a（サービス一覧）と 2e（キーワード検索）を組み合わせます
• エラーコードを調べる場合：API 名が分かっていれば 2d に進みます。分からない場合は、まずユーザーに状況を確認します

重要な注意事項

• API Explorer エンドポイントから常に最新のデータを取得してください。Volcengine API は頻繁に更新されるため、記憶に頼らないでください
• 回答の言語はユーザーの言語に合わせてください（中国語の質問 -> 中国語の回答、英語の質問 -> 英語の回答）
• ユーザーの説明が曖昧な場合は、推測せずに考えられる選択肢を示して確認してください
• 実行可能な SDK コードが必要な場合は、ユーザーを volcengine-sdk-generator スキルに案内してください
• CLI ベースの操作が必要な場合は、ユーザーを volcengine-cli スキルに案内してください
• パラメーター情報を提示する際、説明フィールドに含まれる列挙値、条件付きルール、値の範囲は特に重要です。省略しないでください
• クエリ中にネットワークエラーが発生した場合は、ユーザーに知らせ、後でもう一度試すよう提案してください