Alibaba Cloud CLI:Kontrol cara eksekusi panggilan API Alibaba Cloud CLI

Aturan saling eksklusif

• --pager dan --waiter tidak dapat digunakan bersamaan. CLI akan mengembalikan error berikut jika Anda menggabungkannya: ERROR: flag --pager is exclusive with --waiter.

• --cli-dry-run dapat digunakan bersama --pager atau --waiter, tetapi permintaan tidak dikirim sehingga pagination dan polling tidak dieksekusi.

Penggunaan dasar

Tambahkan --pager ke API List/Describe apa pun yang mendukung pagination. CLI secara otomatis melakukan iterasi melalui semua halaman dan menggabungkan hasilnya menjadi satu output.

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

Dua mode paginasi

CLI secara otomatis menentukan mode yang akan digunakan. Tidak diperlukan konfigurasi manual.

• PageNumber mode: Respons API berisi bidang PageNumber, PageSize, dan TotalCount. CLI menambah nomor halaman hingga semua halaman diambil.

• NextToken mode: Respons API berisi bidang NextToken. CLI meneruskan nilai NextToken yang dikembalikan sebagai parameter permintaan berikutnya hingga NextToken berupa string kosong.

Pemetaan bidang

Sub-parameter berikut semuanya opsional. Anda hanya perlu menentukannya ketika API menggunakan nama bidang non-default untuk informasi pagination agar CLI mengetahui nama bidang yang digunakan oleh API tersebut. Dalam kebanyakan kasus, cukup tambahkan --pager.

Sintaksis: --pager key=value key=value. Beberapa sub-parameter dipisahkan dengan spasi. Nilai value adalah nama bidang aktual dalam respons API, bukan nilai tertentu. Misalnya, PageNumber=CurrentPage berarti API menggunakan bidang CurrentPage untuk merepresentasikan nomor halaman, bukan bahwa Anda menentukan halaman awal.

Contoh pemetaan bidang kustom

Array data tersarang di Vpcs.Vpc[] dalam respons API:

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

API menggunakan Token alih-alih NextToken (xxx dan list-yyy adalah perintah placeholder):

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

Penggunaan dasar

CLI berulang kali memanggil perintah saat ini, mengekstrak nilai dari setiap respons menggunakan ekspresi expr, dan berhenti melakukan polling ketika nilai yang diekstrak sama dengan nilai to, lalu mengembalikan respons terakhir. Saat timeout dan interval tidak ditentukan, CLI melakukan polling setiap 5 detik dengan durasi maksimum 180 detik (3 menit) secara default.

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

Sub-parameter

• Bidang yang dirujuk oleh expr harus bertipe string. Jika bidang dalam respons API berupa angka atau boolean JSON (true/false), CLI langsung mengembalikan error.

• Nilai to selalu dibandingkan sebagai string. Untuk status numerik, tulis to=1 (bukan to=1.0). Jika API mengembalikan boolean sebagai string (misalnya, "true"), tulis to=true.

• Jika panggilan API mengembalikan error HTTP selama polling, CLI langsung berhenti dan menampilkan error tanpa mencoba ulang.

• Saat periode timeout habis tanpa mencocokkan nilai target, CLI keluar dengan kode exit non-nol dan menampilkan hal berikut ke stderr:

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

  Nilai last adalah nilai aktual yang diperoleh dari polling terakhir.

Kontrol frekuensi polling

Perpendek interval polling (tunggu maksimal 30 detik, polling setiap 2 detik):

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

Perpanjang waktu tunggu untuk sumber daya yang membutuhkan waktu lebih lama untuk mulai (tunggu hingga 10 menit, polling setiap 10 detik):

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

Penggunaan dasar

Switch boolean yang aktif saat ditambahkan. Tidak perlu memberikan nilai. CLI menyusun permintaan lengkap, mencetak detail permintaan, tetapi tidak mengirimnya ke server.

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

Konten output

Output mencakup: metode HTTP, Endpoint, API Action, dan Query Parameters. Anda dapat menggunakannya untuk memverifikasi apakah endpoint sudah benar dan apakah serialisasi parameter sesuai harapan.

Contoh output:

============================================================
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"
}

Skenario umum

• Pratinjau sebelum mengeksekusi operasi sensitif (seperti delete-instance atau stop-instance). Setelah memastikan parameter sudah benar, hapus --cli-dry-run untuk mengeksekusi.

• Memverifikasi kebenaran penyusunan perintah dalam pipeline CI/CD (tanpa mengonsumsi sumber daya atau menimbulkan biaya).

Langkah 1: Verifikasi perintah pembuatan dengan --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

Setelah memastikan Endpoint dan serialisasi parameter sudah benar, hapus --cli-dry-run untuk mengeksekusi.

Langkah 2: Eksekusi pembuatan dan ekstrak ID VPC

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

Langkah 3: Tunggu instans menjadi siap dengan --waiter

CLI melakukan polling setiap 5 detik hingga status berubah menjadi Available atau timeout 60 detik tercapai:

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

Langkah 4: Ambil semua VPC dengan --pager

Saat Anda memiliki banyak VPC, tanpa --pager hanya halaman pertama yang dikembalikan dan VPC baru mungkin tidak terlihat. Gunakan --pager untuk memastikan VPC yang baru dibuat muncul dalam daftar:

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

Langkah 5: Hapus VPC (opsional)

Hapus VPC yang dibuat sebelumnya:

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

Dapatkah --pager dan --waiter digunakan bersamaan?

Tidak. Keduanya saling eksklusif. CLI akan mengembalikan error berikut: ERROR: flag --pager is exclusive with --waiter. Jika Anda perlu menunggu sumber daya menjadi siap lalu mengambil daftar lengkapnya, gunakan dua perintah terpisah.