Alibaba Cloud CLI:Alibaba Cloud CLI の API 呼び出しの実行制御

相互排他のルール

• --pager と --waiter は併用できません。これらを組み合わせると、CLI は次のエラーを返します： ERROR: flag --pager is exclusive with --waiter

• --cli-dry-run は --pager または --waiter と共存できますが、リクエストは送信されないため、ページネーションとポーリングは実行されません。

基本的な使用方法

ページ分割に対応した任意の List/Describe API に --pager を追加します。CLI は自動的にすべてのページを反復処理し、結果を単一の出力にマージします。

aliyun ecs describe-instances --biz-region-id cn-hangzhou --pager

2 つのページングモード

CLI は使用するモードを自動的に決定します。手動での設定は不要です。

• PageNumber モード： API レスポンスに PageNumber、PageSize、TotalCount フィールドが含まれます。CLI は、すべてのページが取得されるまでページ番号をインクリメントします。

• NextToken モード： API レスポンスに NextToken フィールドが含まれます。CLI は、NextToken が空文字列になるまで、返された NextToken の値を次のリクエストパラメーターとして渡します。

フィールドマッピング

以下のサブパラメーターはすべてオプションです。API がページネーション情報にデフォルト以外のフィールド名を使用している場合にのみ、そのフィールド名を CLI に伝えるために指定する必要があります。ほとんどの場合、--pager を追加するだけで十分です。

構文： --pager key=value key=value。複数のサブパラメーターはスペースで区切ります。value は、API レスポンス内の実際のフィールド名であり、特定の値ではありません。たとえば、PageNumber=CurrentPage は、開始ページを指定しているのではなく、API がページ番号を表すために CurrentPage フィールドを使用していることを意味します。

カスタムフィールドマッピングの例

データ配列が API レスポンスの Vpcs.Vpc[] にネストされている場合：

aliyun vpc describe-vpcs --biz-region-id cn-hangzhou --pager path=Vpcs.Vpc[]

API が NextToken の代わりに Token を使用している場合 (xxx と list-yyy はコマンドのプレースホルダーです)：

aliyun xxx list-yyy --biz-region-id cn-hangzhou --pager NextToken=Token

基本的な使用方法

CLI は現在のコマンドを繰り返し呼び出し、expr 式を使用して各レスポンスから値を抽出します。抽出された値が to の値と等しくなるとポーリングを停止し、最後のレスポンスを返します。timeout と interval が指定されていない場合、CLI はデフォルトで最大 180 秒 (3 分間)、5 秒ごとにポーリングします。

aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --instance-ids '["i-bp1xxxxx"]' \
  --waiter expr='Instances.Instance[0].Status' to=Running

サブパラメーター

• expr によって参照されるフィールドは、文字列型である必要があります。API レスポンス内のフィールドが数値または JSON ブール値 (true/false) である場合、CLI は直ちにエラーを返します。

• to の値は、常に文字列として比較されます。ステータスが数値の場合、to=1 と記述します (to=1.0 ではありません)。API がブール値を文字列として返す場合 (例： "true")、to=true と記述します。

• ポーリング中に API 呼び出しが HTTP エラーを返した場合、CLI は直ちに停止し、再試行せずにエラーを出力します。

• timeout で指定した期間が経過してもターゲット値に一致しない場合、CLI はゼロ以外の終了コードで終了し、stderr に以下の内容を出力します：

  wait 'Instances.Instance[0].Status' to 'Running' timeout(180seconds), last='Pending'

  last の値は、最後のポーリングで取得された実際の値を示します。

ポーリング頻度の制御

ポーリング間隔を短縮する (最大 30 秒待機し、2 秒ごとにポーリング)：

aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --instance-ids '["i-bp1xxxxx"]' \
  --waiter expr='Instances.Instance[0].Status' to=Running timeout=30 interval=2

起動に時間がかかるリソースの待機時間を延長する (最大 10 分待機し、10 秒ごとにポーリング)：

aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --instance-ids '["i-bp1xxxxx"]' \
  --waiter expr='Instances.Instance[0].Status' to=Running timeout=600 interval=10

基本的な使用方法

コマンドに追加すると有効になるブール型のスイッチで、値を割り当てる必要はありません。CLI はリクエストを完全に構築してその詳細を出力しますが、サーバーには送信しません。

aliyun ecs describe-instances --biz-region-id cn-hangzhou --cli-dry-run

出力内容

出力には、HTTP メソッド、Endpoint、API Action、Query Parameters が含まれます。これにより、Endpoint が正しいか、パラメーターのシリアル化が期待どおりかを確認できます。

出力例：

============================================================
DRY-RUN MODE: Request Details (No actual API call)
============================================================
Method: POST
URL:
Endpoint: ecs.cn-hangzhou.aliyuncs.com
API Version: 2014-05-26
API Action: DescribeInstances
Protocol: HTTPS
Style: RPC
Query Parameters:
RegionId: cn-hangzhou
============================================================
Request NOT sent (dry-run mode)
============================================================
{
   "message": "dry-run mode - no request sent"
}

典型的なシナリオ

• 機密性の高い操作 (delete-instance や stop-instance など) を実行する前のプレビュー。パラメーターが正しいことを確認した後、--cli-dry-run を削除してコマンドを実行します。

• CI/CD パイプラインにおけるコマンド構成の正しさの検証 (リソースの消費やコストの発生なし)。

ステップ 1： --cli-dry-run で作成コマンドを検証

aliyun vpc create-vpc \
    --biz-region-id cn-hangzhou \
    --cidr-block 172.16.0.0/12 \
    --vpc-name test-vpc \
    --cli-dry-run

Endpoint とパラメーターのシリアル化が正しいことを確認した後、--cli-dry-run を削除してコマンドを実行します。

ステップ 2： 作成コマンドを実行し、VPC ID を抽出

VPC_ID=$(aliyun vpc create-vpc \
    --biz-region-id cn-hangzhou \
    --cidr-block 172.16.0.0/12 \
    --vpc-name test-vpc \
    --cli-query 'VpcId')

ステップ 3： --waiter で VPC が利用可能になるまで待機

CLI は、ステータスが Available に変わるか、60 秒のタイムアウトに達するまで、5 秒ごとにポーリングします：

aliyun vpc describe-vpcs \
    --biz-region-id cn-hangzhou \
    --vpc-id "$VPC_ID" \
    --waiter expr='Vpcs.Vpc[0].Status' to=Available timeout=60

ステップ 4： --pager ですべての VPC を取得

VPC が多数存在する場合、--pager を使用しないと最初のページしか返されず、新規作成した VPC が表示されないことがあります。--pager を使用して、新しく作成された VPC がリストに含まれていることを確認します：

aliyun vpc describe-vpcs --biz-region-id cn-hangzhou --pager

ステップ 5： VPC の削除 (オプション)

先ほど作成した VPC を削除します：

aliyun vpc delete-vpc --vpc-id $VPC_ID 

--pager と --waiter は併用できますか？

いいえ、併用できません。これらは相互排他的です。CLI は次のエラーを返します： ERROR: flag --pager is exclusive with --waiter。リソースが利用可能になるのを待ってから完全なリストを取得する必要がある場合は、2 つのコマンドを別々に使用してください。