Alibaba Cloud CLI:Controle como as chamadas de API do Alibaba Cloud CLI são executadas

Regras de exclusão mútua

• O --pager e o --waiter não podem ser usados juntos. O CLI retorna o seguinte erro se você combiná-los: ERROR: flag --pager is exclusive with --waiter.

• O --cli-dry-run pode coexistir com o --pager ou o --waiter, mas o CLI não envia a requisição, portanto a paginação e o polling não são executados.

Uso básico

Adicione o --pager a qualquer API paginada do tipo List ou Describe. O CLI itera automaticamente por todas as páginas e mescla os resultados em uma única saída.

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

Dois modos de paginação

O CLI determina automaticamente qual modo usar. Nenhuma configuração manual é necessária.

• Modo PageNumber: A resposta da API contém os campos PageNumber, PageSize e TotalCount. O CLI incrementa o número da página até que todas as páginas sejam recuperadas.

• Modo NextToken: A resposta da API contém um campo NextToken. O CLI passa o valor de NextToken retornado como o próximo parâmetro da requisição até que o NextToken seja uma string vazia.

Mapeamento de campos

Os subparâmetros a seguir são todos opcionais. Especifique estes apenas quando uma API usar nomes de campo não padrão para as informações de paginação, indicando ao CLI quais nomes de campo a API utiliza. Na maioria dos casos, apenas adicionar o --pager é suficiente.

Sintaxe: --pager key=value key=value. Vários subparâmetros são separados por espaços. O value é o nome real do campo na resposta da API, não um valor específico. Por exemplo, PageNumber=CurrentPage significa que a API usa o campo CurrentPage para representar o número da página, e não que você está especificando uma página inicial.

Exemplos de mapeamento de campos personalizados

O array de dados está aninhado em Vpcs.Vpc[] na resposta da API:

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

A API usa Token em vez de NextToken (xxx e list-yyy são comandos de espaço reservado):

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

Uso básico

O CLI chama o comando atual repetidamente, extrai um valor de cada resposta usando a expressão expr e interrompe o polling quando o valor extraído é igual ao valor de to, retornando a última resposta. Quando timeout e interval não são especificados, o CLI faz o polling a cada 5 segundos por no máximo 180 segundos (3 minutos) por padrão.

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

Subparâmetros

• O campo referenciado por expr deve ser do tipo string. Se o campo na resposta da API for um número ou um booleano JSON (true/false), o CLI retornará um erro imediatamente.

• O valor de to é sempre comparado como uma string. Para status numéricos, escreva to=1 (e não to=1.0). Se a API retornar um booleano como string (por exemplo, "true"), escreva to=true.

• Se uma chamada de API retornar um erro HTTP durante o polling, o CLI será interrompido imediatamente e exibirá o erro sem tentar novamente.

• Quando o período de timeout expira sem corresponder ao valor alvo, o CLI encerra com um código de saída diferente de zero e envia o seguinte para o stderr:

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

  O valor last é o valor real obtido na última consulta do polling.

Controle a frequência do polling

Reduza o intervalo de polling (aguarde até 30 segundos, faça polling a 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

Aumente o tempo de espera para recursos que demoram mais para iniciar (aguarde até 10 minutos, faça polling a 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

Um interruptor booleano que entra em vigor quando adicionado. Nenhuma atribuição de valor é necessária. O CLI constrói a requisição completa, imprime os detalhes da requisição, mas não a envia para o servidor.

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

Conteúdo da saída

A saída inclui: método HTTP, Endpoint, API Action e Query Parameters. Você pode usar isso para verificar se o endpoint está correto e se a serialização dos parâmetros está conforme o esperado.

Exemplo de saída:

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

Cenários típicos

• Visualize antes de executar operações sensíveis (como delete-instance ou stop-instance). Confirme que os parâmetros estão corretos, remova o --cli-dry-run e execute.

• Verifique a correção da montagem do comando em pipelines de CI/CD (sem consumir recursos ou gerar custos).

Passo 1: Verifique o comando de criação com o --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

Confirme que o Endpoint e a serialização dos parâmetros estão corretos, remova o --cli-dry-run e execute.

Passo 2: Execute a criação e extraia o ID da 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')

Passo 3: Aguarde a instância ficar pronta com o --waiter**

O CLI faz polling a cada 5 segundos até que o status mude para Available ou o tempo limite de 60 segundos seja atingido:

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

Passo 4: Recupere todas as VPCs com o --pager**

Quando você tem muitas VPCs, sem o --pager, apenas a primeira página é retornada e a nova VPC pode não ficar visível. Use o --pager para confirmar que a VPC recém-criada aparece na lista:

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

Passo 5: Exclua a VPC (opcional)

Exclua a VPC criada anteriormente:

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

O --pager e o --waiter podem ser usados juntos?

Não. Eles são mutuamente exclusivos. O CLI retorna o seguinte erro: ERROR: flag --pager is exclusive with --waiter. Se você precisar aguardar um recurso ficar pronto e, em seguida, recuperar a lista completa, use dois comandos separados.