Alibaba Cloud CLI:Control how Alibaba Cloud CLI API calls are executed

Reglas de exclusión mutua

• --pager y --waiter no pueden usarse juntos. La CLI devuelve el siguiente error si los combina: ERROR: flag --pager is exclusive with --waiter.

• --cli-dry-run puede coexistir con --pager o --waiter, pero la solicitud no se envía, por lo que la paginación y el sondeo no se ejecutan.

Uso básico

Agregue --pager a cualquier API de List/Describe paginada. La CLI itera automáticamente por todas las páginas y fusiona los resultados en una sola salida.

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

Dos modos de paginación

La CLI determina automáticamente qué modo usar. No se requiere configuración manual.

• Modo PageNumber: La respuesta de la API contiene los campos PageNumber, PageSize y TotalCount. La CLI incrementa el número de página hasta recuperar todas las páginas.

• Modo NextToken: La respuesta de la API contiene un campo NextToken. La CLI pasa el valor NextToken devuelto como parámetro de la siguiente solicitud hasta que NextToken es una cadena vacía.

Mapeo de campos

Los siguientes subparámetros son opcionales. Solo necesita especificarlos cuando una API utiliza nombres de campo no predeterminados para la información de paginación, con el fin de indicar a la CLI qué nombres de campo usa la API. En la mayoría de los casos, basta con agregar --pager.

Sintaxis: --pager key=value key=value. Los subparámetros múltiples se separan con espacios. El value es el nombre real del campo en la respuesta de la API, no un valor específico. Por ejemplo, PageNumber=CurrentPage significa que la API utiliza el campo CurrentPage para representar el número de página, no que usted esté especificando una página de inicio.

Ejemplos de mapeo de campos personalizados

La matriz de datos está anidada en Vpcs.Vpc[] dentro de la respuesta de la API:

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

La API utiliza Token en lugar de NextToken (xxx y list-yyy son comandos de marcador de posición):

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

Uso básico

La CLI llama repetidamente al comando actual, extrae un valor de cada respuesta mediante la expresión expr y detiene el sondeo cuando el valor extraído coincide con el valor to, devolviendo la última respuesta. Cuando no se especifican timeout e interval, la CLI realiza el sondeo cada 5 segundos durante un máximo de 180 segundos (3 minutos) de forma predeterminada.

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

Subparámetros

• El campo referenciado por expr debe ser de tipo cadena. Si el campo en la respuesta de la API es un número o un booleano JSON (true/false), la CLI devuelve un error inmediatamente.

• El valor to siempre se compara como una cadena. Para estados numéricos, escriba to=1 (no to=1.0). Si la API devuelve un booleano como cadena (por ejemplo, "true"), escriba to=true.

• Si una llamada a la API devuelve un error HTTP durante el sondeo, la CLI se detiene inmediatamente y muestra el error sin reintentar.

• Cuando transcurre el periodo de timeout sin coincidir con el valor objetivo, la CLI finaliza con un código de salida distinto de cero y envía lo siguiente a stderr:

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

  El valor last es el valor real obtenido en el último sondeo.

Control de la frecuencia de sondeo

Acorte el intervalo de sondeo (espere hasta 30 segundos, sondee cada 2 segundos):

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

Extienda el tiempo de espera para recursos que tardan más en iniciarse (espere hasta 10 minutos, sondee cada 10 segundos):

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

Uso básico

Es un modificador booleano que surte efecto al agregarse. No requiere asignación de valor. La CLI construye la solicitud completa e imprime sus detalles, pero no la envía al servidor.

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

Contenido de la salida

La salida incluye: método HTTP, Endpoint, API Action y Query Parameters. Puede usar esto para comprobar si el endpoint es correcto y si la serialización de parámetros es la esperada.

Ejemplo de salida:

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

Escenarios típicos

• Vista previa antes de ejecutar operaciones sensibles (como delete-instance o stop-instance). Tras confirmar que los parámetros son correctos, elimine --cli-dry-run para ejecutar la operación.

• Comprobación de la correcta construcción de comandos en pipelines de CI/CD (sin consumir recursos ni generar costos).

Paso 1: Compruebe el comando de creación con --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

Después de confirmar que el Endpoint y la serialización de parámetros son correctos, elimine --cli-dry-run para ejecutar la operación.

Paso 2: Ejecute la creación y extraiga el ID de la 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')

Paso 3: Espere a que la instancia esté lista con --waiter

La CLI realiza un sondeo cada 5 segundos hasta que el estado cambia a Available o se alcanza el tiempo de espera de 60 segundos:

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

Paso 4: Recupere todas las VPC con --pager

Cuando tiene muchas VPC, sin --pager solo se devuelve la primera página y es posible que la nueva VPC no sea visible. Utilice --pager para confirmar que la VPC recién creada aparece en la lista:

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

Paso 5: Elimine la VPC (opcional)

Elimine la VPC creada anteriormente:

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

¿Se pueden usar juntos --pager y --waiter?

No. Son mutuamente excluyentes. La CLI devuelve el siguiente error: ERROR: flag --pager is exclusive with --waiter. Si necesita esperar a que un recurso esté listo y luego recuperar la lista completa, utilice dos comandos separados.