全部產品
Search

搜尋本產品

    Alibaba Cloud CLI：控制阿里雲 CLI API 呼叫的執行方式

    文件中心

    Alibaba Cloud CLI：控制阿里雲 CLI API 呼叫的執行方式

    更新時間：Jun 05, 2026

    使用阿里雲 CLI 調用 API 時，你可能需要一次性拉取所有分頁資料、等待資源建立完成再繼續、或者先驗證命令是否正確而不實際執行。本文介紹實現這三種情境的全域參數及其配置方法。

    選擇合適的參數

    三者都是全域參數，作用於單次 API 呼叫。根據情境選擇：

    情境

    參數

    列表 API 只返回一頁，要拿全部資料

    --pager

    建立資源後等待狀態就緒

    --waiter

    驗證命令正確性，不實際執行

    --cli-dry-run

    互斥規則

    • --pager和 --waiter不能同時使用。同時指定時 CLI 報錯：ERROR: flag --pager is exclusive with --waiter。

    • --cli-dry-run可與--pager或 --waiter共存，但請求不會發出，因此分頁和輪詢均不會執行。

    自動彙總所有分頁（--pager）

    基本用法

    在任何支援分頁的 List/Describe 類 API 後追加 --pager，CLI 自動逐頁調用併合並為單次輸出返回。

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

    兩種分頁彙總模式

    CLI 自動判斷使用哪種模式，無需手動指定。

    • PageNumber模式：API 返回中含 PageNumber + PageSize + TotalCount 欄位，CLI 遞增頁碼直到取完所有頁。

    • NextToken 模式：API 返回中含 NextToken 欄位，CLI 將上次返回的 NextToken 值作為下次請求參數，直到 NextToken 為空白字串。

    說明

    若響應中存在 NextToken 欄位且值非空，則使用 NextToken 模式，否則使用 PageNumber 模式。

    欄位對應

    以下子參數全部為非必填。僅當 API 使用非預設欄位名返回資料時才需要指定：告訴 CLI 該 API 用什麼欄位名表示分頁資訊。大多數 API 直接加--pager參數即可。

    子參數

    預設值

    何時需要指定

    path

    （無）

    響應中資料數組路徑非頂層時（如Vpcs.Vpc[]）

    PageNumber

    PageNumber

    API 用其他欄位名表示頁碼時

    PageSize

    PageSize

    API 用其他欄位名表示每頁大小時

    TotalCount

    TotalCount

    API 用其他欄位名表示總記錄數時

    NextToken

    NextToken

    API 用其他欄位名表示翻頁標記時

    文法：--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 用 Token 而非 NextToken（xxx、list-yyy為佔位命令）：

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

    等待資源狀態就緒（--waiter）

    基本用法

    CLI 重複調用當前命令，用expr運算式從每次響應中取值，當取到的值等於to時停止輪詢並返回最後一次響應。未指定timeout和interval時，CLI 預設每 5 秒查詢一次，最多等待 180 秒（3 分鐘）。

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

    子參數

    子參數

    必填

    預設值

    取值範圍

    說明

    expr

    是

    —

    —

    通過 JMESPath 運算式指定 JSON 響應中要輪詢的欄位。

    to

    是

    —

    —

    目標值。當expr的求值結果與該值匹配時，停止輪詢並返回資料。

    timeout

    否

    180

    1~600（秒）

    輪詢的最大等待時間。超過該時間仍未匹配目標值時，CLI 報錯並退出。

    interval

    否

    5

    2~10（秒）

    兩次輪詢之間的時間間隔。

    • 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-dry-run）

    基本用法

    布爾開關，加上即生效，無需賦值。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 流水線中驗證命令拼裝正確性（不消耗資源、不產生費用）。

    自動化情境：非同步作業完整流程

    情境：建立 VPC → 等待狀態可用 → 擷取全部 VPC 列表。接下來示範三個參數如何配合完成一個完整的非同步作業。

    步驟 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')

    --cli-query從響應中提取 VPC ID。

    步驟 3：用 --waiter等待執行個體就緒

    CLI 每 5 秒查詢一次，直到狀態變為 Available 或超過 300 秒逾時：

    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只返回第一頁，可能看不到。因此使用--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。如需先等資源就緒再擷取全量列表，應分為兩條命令執行。

    相關文檔