volcengine-sdk-generator

Volcengine SDK ジェネレーター

デフォルトでは、一般的な Volcengine API 呼び出しのサンプルを生成します。デフォルトの出力は、API 呼び出し自体に焦点を当て、認証の設定、リクエストオブジェクト／パラメーター、呼び出し、レスポンスの出力を含めてください。ユーザーから明示的に求められない限り、リトライ、プロキシ、接続プール、デバッグログなどの高度な SDK 設定は追加しないでください。

高度な SDK 設定に関する質問には、references/ にある言語別ファイルを使用してください。これらのリファレンスファイルは自己完結しているため、そこから直接回答してください。

トピック	リファレンス
Go SDK の設定	references/sdk-integration-go.md
Python SDK の設定	references/sdk-integration-python.md
Java SDK の設定	references/sdk-integration-java.md
Node.js SDK の設定	references/sdk-integration-nodejs.md
PHP SDK の設定	references/sdk-integration-php.md

基本ルール

• API の検索には scripts/rg_rank.py を使用します。このスクリプトは Channel=service と Channel=api の両方を指定して API Explorer を検索します。具体的な API を選択した後、--service-code、--api-version、--action を指定し、ダイレクトモードで scripts/make_code.py を呼び出します。
• API の検索はオンラインのみで行います。検索エンドポイントでは、Cookie、ログイン状態、UID、DID、UUID、ブラウザー固有のヘッダーは不要です。スクリプトは、クエリパラメーターとして Query、Channel、Limit、Offset のみを送信します。
• rg_rank.py は、バージョン選択を除き、Channel=api の順序を維持します。同じ service_code + action に複数のバージョンがあり、ユーザーがバージョンを指定していない場合は、そのグループ内で IsRecommended=1 の結果をほかのバージョンより前に移動します。また、Channel=service の結果もサービスのメタデータとして別途含めます。
• オンライン検索に失敗した場合は、返された検索エラーを報告します。API を推測したり、同梱カタログにフォールバックしたりしないでください。
• --query にはユーザーの元のリクエストを使用してください。推測した API 名や SDK メソッド名に書き換えないでください。
• ユーザーが 等等、不对、重新来、我改主意、其实想要、其实是想要、应该是、改成 などの言葉を使って明確に訂正した場合に限り、より短い --query を抽出します。抽出するクエリは、推測した API 名ではなく、ユーザーのリクエストに含まれる連続した部分文字列でなければなりません。
• 明確な自己訂正がなく、複数のリソースやサービスが出てくる場合は、元のリクエストで rg_rank.py を一度だけ実行します。返された候補が依然として曖昧な場合は、簡潔に列挙し、ユーザーに選択を求めます。
• api、sdk、demo などの一般的すぎるクエリもオンラインに送信しますが、曖昧な結果になりやすいため、具体的なリソース名やアクションを表す語を加えて絞り込んでください。
• ServiceCode は大文字と小文字を区別します。make_code.py を呼び出す際は、選択した API レコードの service_code の値をそのまま使用してください。たとえば、Kafka は kafka とは異なります。
• 同じ service_code + action が複数の API バージョンにあり、ユーザーがバージョンを指定していない場合は、remote_rank が低くても is_recommended=true の結果を選択します。ユーザーがバージョンを指定した場合は、そのバージョンを使用します。
• api-swagger は、具体的な API を選択した後にのみ取得します。
• api-swagger の取得時には、エンドポイントが両方を必要とする場合、Version と APIVersion の両方を含めることができます。make-code のペイロードには Version を含めないでください。
• make-code は ApiAction、ServiceCode、APIVersion、Region、Params を指定して呼び出します。
• make-code に Version を送信しないでください。
• Params にはユーザーから渡された値を使用してください。Swagger のデモから自動入力しないでください。
• Swagger は、API のメタデータ、必須パラメーターのヒント、簡易的な検証に使用します。make-code 用にクエリ配列、フォーム配列、.N パラメーターをシリアライズしないでください。ユーザーの JSON オブジェクトを Params として渡してください。
• ユーザーが必須のトップレベルパラメーターを省略した場合は、それらのトップレベル必須パラメーターのみをモックし、モック値であることを明記してください。任意パラメーターはモックしないでください。必須のトップレベルパラメーターがオブジェクトまたは配列の場合は、必須の子フィールドや要素のみを再帰的に補完してください。
• モック値は、まず取得した Swagger から導出してください。example、examples、default、enum の順に優先し、その後に型や制約に応じたフォールバック値を使用します。Swagger の例が **** や XX などのマスク済み値の場合は使用せず、有効なフォールバック値を使用してください。
• モックのコメントは、デフォルトで中国語にし、対象言語が行コメントをサポートする場合はモックした代入行の近くに配置してください。返却コードの先頭に重複するモックのバナーを追加しないでください。
• 返却する SDK コードでは、API レスポンスの値を出力してください。スクリプトは、Python、Go、Java、PHP 用の固定 make-code テンプレートを後処理し、レスポンスを代入して出力します。
• scripts/make_code.py が生成したコードを、SDK の主要なサンプルとして返してください。ユーザーが明示的に求めない限り、SDK リクエストの構築、認証の設定、レスポンス処理を、独自のアプリケーション向けに書き換えないでください。任意の整形処理や利便性のためのロジックを追加する場合も、print(resp)、fmt.Println(resp)、System.out.println(resp)、print_r($response)、console.log(response) など、生成されたレスポンス出力を有効なまま残してください。
• 言語が指定されていない場合は、DemoSdk に含まれるすべての言語を返してください。
• SDK のインストール情報や依存関係情報は、必要に応じて個別に提供する機能です。ユーザーが SDK のインストール方法、または使用するパッケージやバージョンを明示的に尋ねた場合（依赖、安装、install、版本、包、maven、go get、pip、composer、npm などのキーワードが含まれる場合）に限り、選択した API の値を再利用して --service-code と --api-version を指定し、scripts/sdk_info.py を実行してください。1 つの言語に絞り込む場合は、--language に go/python/java/php/nodejs のいずれかを指定します。このスクリプトは、言語ごとに現在のインストールコマンド（RunCommand）、パッケージ、バージョンを返します。通常のコード生成時には実行しないでください。
• API の候補が曖昧な場合は、簡潔に候補を示して、いずれかを選ぶようユーザーに尋ねてください。ユーザーが選択した後に Swagger を取得し、必須パラメーターをモックして make-code を呼び出す、といった後続処理の説明は付け加えないでください。

ワークフロー

1. ユーザーのリクエストを解析します。

   • API のヒント：アクション、中国語名、サービスコード、または自然言語による説明。
   • 言語：Python、Go、Java、PHP、cURL、Node.js、または指定なし。
   • パラメーター：ユーザーが指定した JSON オブジェクト。
   • リージョン：ユーザーが指定した値、またはデフォルトの cn-beijing。

2. リクエストごとに API を一度特定または検証します。ユーザーがすでに service_code、api_version、action を指定している場合は、ダイレクトモードでそれらの値をそのまま使用します。make_code.py がオンラインの api-swagger レスポンスを通じて検証します。自然言語によるリクエストの場合は、まず scripts/rg_rank.py を --query とともに呼び出します。後の対象を示す明確な自己修正キーワードがある場合を除き、元のリクエスト全体を使用します。その場合は、最後の対象部分文字列を使用します。

3. service_code、api_version、action を選択した後、--service-code、--api-version、--action を指定して、ダイレクト API モードで scripts/make_code.py を呼び出します。トップレベルの必須パラメーターが不足している場合、スクリプトは Swagger から取得したモック値で必須のトップレベルパラメーターのみを補い、返されるコードに中国語で注記します。オンラインの結果で API の選択が本当に曖昧な場合に限り、確認を求めます。その際は候補のみを提示し、ユーザーに選択を求めてください。

4. パラメーターが揃ったら、スクリプトを通じて make-code を呼び出し、公式のコードを返します。生成されたサンプルを手書きのユーティリティに変換しないでください。カスタムの書式設定を行う場合は補足的なものにとどめ、アクティブなレスポンス出力を維持してください。

コマンド

オンライン候補を検索する：

python3 scripts/rg_rank.py \
  --query '角色扮演' \
  --limit 10 \
  --format text

ダイレクト API モード：

TRN の例では、<account-id> は Volcengine アカウント ID のセグメントです。マスクされた 2134xxxyyy などが該当します。

python3 scripts/make_code.py \
  --service-code sts \
  --api-version 2018-01-01 \
  --action AssumeRole \
  --language python \
  --params-json '{"DurationSeconds":3600,"RoleSessionName":"demo","RoleTrn":"trn:iam::<account-id>:role/demo"}'

API Explorer のメタデータが変更された直後、または生成コードが古いように見える場合は、--refresh-swagger を使用します。

python3 scripts/make_code.py \
  --service-code sts \
  --api-version 2018-01-01 \
  --action AssumeRole \
  --refresh-swagger \
  --params-json '{}'

必要に応じて SDK のインストール／依存関係情報を取得します（ユーザーがインストール、パッケージ、またはバージョンについて尋ねた場合のみ）。

python3 scripts/sdk_info.py \
  --service-code sts \
  --api-version 2018-01-01 \
  --language go