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

Règles d'exclusion mutuelle

• Les options --pager et --waiter ne peuvent pas être utilisées simultanément. Si vous les combinez, la CLI renvoie l'erreur suivante : ERROR: flag --pager is exclusive with --waiter.

• L'option --cli-dry-run peut coexister avec --pager ou --waiter, mais comme la requête n'est pas envoyée, la pagination et l'interrogation (polling) ne sont pas exécutées.

Utilisation de base

Ajoutez l'option --pager à toute API de type List/Describe prenant en charge la pagination. La CLI parcourt automatiquement toutes les pages et fusionne les résultats dans une sortie unique.

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

Deux modes de pagination

La CLI détermine automatiquement le mode à utiliser. Aucune configuration manuelle n'est nécessaire.

• Mode PageNumber : La réponse de l'API contient les champs PageNumber, PageSize et TotalCount. La CLI incrémente le numéro de page jusqu'à ce que toutes les pages soient récupérées.

• Mode NextToken : La réponse de l'API contient un champ NextToken. La CLI transmet la valeur NextToken renvoyée comme paramètre de la requête suivante, jusqu'à ce que NextToken soit une chaîne vide.

Mappage des champs

Les sous-paramètres suivants sont tous facultatifs. Vous devez les spécifier uniquement lorsqu'une API utilise des noms de champs non standards pour les informations de pagination, afin d'indiquer à la CLI quels noms de champs l'API utilise. Dans la plupart des cas, il suffit d'ajouter --pager.

Syntaxe : --pager key=value key=value. Plusieurs sous-paramètres sont séparés par des espaces. La value correspond au nom réel du champ dans la réponse de l'API, et non à une valeur spécifique. Par exemple, PageNumber=CurrentPage signifie que l'API utilise le champ CurrentPage pour représenter le numéro de page, et non que vous spécifiez une page de départ.

Exemples de mappage de champs personnalisés

Le tableau de données est imbriqué à l'emplacement Vpcs.Vpc[] dans la réponse de l'API :

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

L'API utilise Token au lieu de NextToken (xxx et list-yyy sont des commandes fictives) :

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

Utilisation de base

La CLI appelle répétitivement la commande actuelle, extrait une valeur de chaque réponse à l'aide de l'expression expr, et arrête l'interrogation (polling) lorsque la valeur extraite correspond à la valeur to, en renvoyant la dernière réponse. Lorsque timeout et interval ne sont pas spécifiés, la CLI interroge toutes les 5 secondes pendant un maximum de 180 secondes (3 minutes) par défaut.

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

Sous-paramètres

• Le champ référencé par expr doit être de type chaîne. Si le champ dans la réponse de l'API est un nombre ou un booléen JSON (true/false), la CLI renvoie immédiatement une erreur.

• La valeur to est toujours comparée en tant que chaîne. Pour les statuts numériques, écrivez to=1 (et non to=1.0). Si l'API renvoie un booléen sous forme de chaîne (par exemple, "true"), écrivez to=true.

• Si un appel d'API renvoie une erreur HTTP pendant l'interrogation, la CLI s'arrête immédiatement et affiche l'erreur sans réessayer.

• Lorsque le délai timeout expire sans que la valeur cible ne soit atteinte, la CLI se termine avec un code de sortie non nul et affiche le message suivant sur stderr :

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

  La valeur last correspond à la valeur réelle obtenue lors de la dernière interrogation.

Contrôler la fréquence d'interrogation

Réduire l'intervalle d'interrogation (attente maximale de 30 secondes, interrogation toutes les 2 secondes) :

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

Augmenter le temps d'attente pour les ressources qui mettent plus de temps à démarrer (attente maximale de 10 minutes, interrogation toutes les 10 secondes) :

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

Utilisation de base

Il s'agit d'un commutateur booléen qui prend effet lorsqu'il est ajouté. Aucune affectation de valeur n'est nécessaire. La CLI construit la requête complète, affiche les détails de la requête, mais ne l'envoie pas au serveur.

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

Contenu de la sortie

La sortie inclut : la méthode HTTP, l'Endpoint, l'API Action et les Query Parameters. Vous pouvez utiliser ces informations pour vérifier si l'endpoint est correct et si la sérialisation des paramètres est conforme aux attentes.

Exemple de sortie :

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

Scénarios typiques

• Prévisualiser avant d'exécuter des opérations sensibles (telles que delete-instance ou stop-instance). Après avoir confirmé que les paramètres sont corrects, supprimez --cli-dry-run pour exécuter la commande.

• Vérifier la justesse de l'assemblage des commandes dans les pipelines CI/CD (sans consommer de ressources ni engendrer de coûts).

Étape 1 : Vérifier la commande de création avec --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

Après avoir confirmé que l'Endpoint et la sérialisation des paramètres sont corrects, supprimez --cli-dry-run pour exécuter la commande.

Étape 2 : Exécuter la création et extraire l'ID du 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')

Étape 3 : Attendre que l'instance soit prête avec --waiter

La CLI interroge toutes les 5 secondes jusqu'à ce que le statut passe à Available ou que le délai d'expiration de 60 secondes soit atteint :

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

Étape 4 : Récupérer tous les VPC avec --pager

Lorsque vous disposez de nombreux VPC, sans l'option --pager, seule la première page est renvoyée et le nouveau VPC peut ne pas être visible. Utilisez --pager pour confirmer que le VPC nouvellement créé apparaît dans la liste :

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

Étape 5 : Supprimer le VPC (facultatif)

Supprimez le VPC créé précédemment :

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

Peut-on utiliser --pager et --waiter ensemble ?

Non. Ces options s'excluent mutuellement. La CLI renvoie l'erreur suivante : ERROR: flag --pager is exclusive with --waiter. Si vous devez attendre qu'une ressource soit prête, puis récupérer la liste complète, utilisez deux commandes distinctes.