Conseils pour bien utiliser Azure CLI

  • Article

Azure CLI est un outil en ligne de commande qui vous permet de configurer et de gérer des ressources Azure depuis nombreux environnements shell. Après avoir choisi votre environnement d’interpréteur de commandes préféré et installé Azure CLI, utilisez cet article pour découvrir des conseils utiles sur la façon d’éviter les pièges courants et d’utiliser Azure CLI avec succès.

Pour en savoir plus sur des commandes Azure CLI spécifiques, consultez la liste des informations de référence sur Azure CLI.

Mise en forme de la sortie

Trois formats de sortie courants sont utilisés avec les commandes Azure CLI :

  1. Le format json montre les informations sous la forme d’une chaîne JSON.

    • JSON vous donne les informations les plus complètes.
    • Ce format est le format par défaut, mais vous pouvez utiliser le paramètre --output pour spécifier une autre option.
    • Remplacez le format par défaut global par l’une de vos préférences personnelles en utilisant az config, par exemple az config set core.output=table.
    • Le format JSON conserve les guillemets doubles, ce qui le rend généralement inadapté aux scripts.

  2. Le format table présente la sortie sous la forme d’une table lisible. Vous pouvez spécifier les valeurs qui apparaissent dans la table et utiliser des requêtes pour personnaliser la sortie, comme illustré ici :

    # command
az vm show --resource-group myResourceGroup --name myVMname --query "{name: name, os:storageProfile.imageReference.offer}" --output table

# output
Name    Os
------  ------------
myVMname   UbuntuServer

  3. Le format tsv retourne des valeurs séparées par des tabulations et des sauts de ligne sans mise en forme, clés ou autres symboles supplémentaires.

    • Le format TSV est pratique pour obtenir des sorties concises et des scripts.
    • Le format TSV supprime les guillemets doubles que le format JSON conserve.
    • Pour spécifier le format souhaité pour TSV, utilisez l’argument --query.
    export vm_ids=$(az vm list --show-details --resource-group myResourceGroup --query "[?powerState=='VM running'].id" --output tsv)
az vm stop --ids $vm_ids

Pour en savoir plus sur ces formats et sur d’autres, consultez Formats de sortie pour les commandes Azure CLI.

Passer des valeurs à une autre commande

Si la valeur est utilisée plusieurs fois, affectez-la à une variable. Les variables vous permettent d’utiliser plusieurs fois des valeurs ou de créer des scripts plus généraux. Cet exemple attribue à une variable un ID trouvé par la commande az vm list.

# assign the list of running VMs to a variable
running_vm_ids=$(az vm list --resource-group MyResourceGroup --show-details \
    --query "[?powerState=='VM running'].id" --output tsv)

# verify the value of the variable
echo $running_vm_ids

Si la valeur n’est utilisée qu’une seule fois, envisagez d’utiliser un canal. (Piping transmet la sortie d’une commande en tant qu’entrée à une deuxième commande.)

az vm list --query "[?powerState=='VM running'].name" --output tsv | grep my_vm

Pour les listes à valeurs multiples, considérez les options suivantes :

  1. Si vous avez besoin de davantage de contrôle sur le résultat, utilisez une boucle « for » :

    #!/usr/bin/env bash
for vmList in $(az vm list --resource-group MyResourceGroup --show-details --query "[?powerState=='VM running'].id"   --output tsv); do
    echo stopping $vmList
    az vm stop --ids $vmList
    if [ $? -ne 0 ]; then
        echo "Failed to stop $vmList"
        exit 1
    fi
    echo $vmList stopped
done

  2. Vous pouvez également utiliser xargs et envisager d’utiliser l’indicateur -P pour exécuter les opérations en parallèle afin d’améliorer les performances :

    az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | xargs -I {} -P 10 az vm start --ids "{}"

  3. Enfin, Azure CLI propose une prise en charge intégrée pour traiter les commandes avec plusieurs --ids en parallèle afin d’obtenir le même effet que xargs. @- est utilisé pour récupérer des valeurs à partir du canal :

    az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | az vm start --ids @-

Pour plus d’informations sur l’utilisation de constructions Bash avec Azure CLI, notamment des boucles, des instructions case, if..then..else, et la gestion des erreurs, consultez Découvrir comment utiliser Bash avec Azure CLI.

Utiliser des guillemets dans les paramètres

Quand vous utilisez des commandes Azure CLI, gardez à l’esprit la façon dont votre interpréteur de commandes utilise les guillemets et les caractères d’échappement. Si vous prenez en charge les scripts utilisés dans différents interpréteurs de commandes, comprenez comment ils diffèrent.

Notes

En raison d’un problème connu dans PowerShell, certaines règles d’échappement supplémentaires s’appliquent. Pour plus d’informations, consultez Problèmes liés aux guillemets avec PowerShell.

Pour éviter des résultats imprévus, voici quelques suggestions :

  • Si vous fournissez à un paramètre qui contient des espaces, placez-le entre des guillemets.

  • Dans Bash ou PowerShell, les guillemets simples et doubles sont interprétés correctement. Dans l’invite de commandes Windows, seuls les guillemets doubles sont interprétés correctement ; les guillemets simples sont traités comme faisant partie de la valeur.

  • Si votre commande va s’exécuter seulement sur Bash (ou Zsh), utilisez des guillemets simples pour préserver le contenu à l’intérieur de la chaîne JSON. Les guillemets simples sont nécessaires lors de la spécification de valeurs JSON incluses. Par exemple, ce JSON est correct dans Bash : '{"key": "value"}'.

  • Si votre commande s’exécute sur l’invite de commandes Windows, vous devez utiliser des guillemets doubles. Si la valeur contient des guillemets doubles, vous devez la placer en échappement. L’équivalent de la chaîne JSON ci-dessus est "{\"key\": \"value\"}"

  • Dans PowerShell, si la valeur est une chaîne vide, utilisez '""'.

  • Dans Bash ou PowerShell, si la valeur est une chaîne de guillemets vides '', utilisez "''".

  • Utilisez la convention @<file> d’Azure CLI pour charger depuis un fichier et contourner les mécanismes d’interprétation du shell.

    az ad app create --display-name myName --native-app --required-resource-accesses @manifest.json

  • Bash évalue les guillemets doubles dans les variables exportées. Si ce comportement n’est pas celui que vous souhaitez, placez la variable dans une séquence d’échappement : "\$variable".

  • Certaines commandes Azure CLI prennent une liste de valeurs séparées par des espaces.

    • Si le nom de la clé ou la valeur contient des espaces, placez la paire entière entre guillemets : "my key=my value". Par exemple :

      az web app config app settings set --resource-group myResourceGroup --name myWebAppName --settings "client id=id1" "my name=john"

    • Quand un paramètre CLI indique qu’il accepte une liste séparée par des espaces, un des deux formats est attendu :

      1. Liste de valeurs séparées par des espaces, sans guillemets : --parameterName firstValue secondValue
      2. Liste de valeurs séparées par des espaces, avec des guillemets : --parameterName "firstValue" "secondValue"

      Cet exemple est une chaîne contenant un espace. Il ne s’agit pas d’une liste de valeurs séparées par des espaces : --parameterName "firstValue secondValue"

  • PowerShell comporte des caractères spéciaux, tels que @ (at). Pour exécuter Azure CLI dans PowerShell, ajoutez ` avant le caractère spécial afin de le placer dans une séquence d’échappement. Vous pouvez aussi placer la valeur entre des guillemets simples ou doubles "/".

    # The following three examples will work in PowerShell
--parameterName `@parameters.json
--parameterName '@parameters.json'
--parameterName "@parameters.json"

# This example will not work in PowerShell
--parameterName @parameters.json

  • Quand vous utilisez le paramètre --query avec une commande, certains caractères de JMESPath doivent être placés dans une séquence d’échappement dans l’interpréteur de commandes.

    Ces trois commandes sont correctes et équivalentes dans Bash :

    az version --query '"azure-cli"'
az version --query \"azure-cli\"
az version --query "\"azure-cli\""

    Voici deux exemples de commandes incorrectes dans Bash :

    # Wrong, as the dash needs to be quoted in a JMESPath query
az version --query azure-cli
az version: error: argument --query: invalid jmespath_type value: 'azure-cli'

# Wrong, as the dash needs to be quoted in a JMESPath query, but quotes are interpreted by Bash
az version --query "azure-cli"
az version: error: argument --query: invalid jmespath_type value: 'azure-cli'

    Pour obtenir d’autres exemples de comparaisons entre Bash, PowerShell et Cmd, consultez Sortie des commandes de requête Azure CLI

  • La meilleure façon de résoudre un problème lié aux guillemets est d’exécuter la commande avec l’indicateur --debug. Cet indicateur montre les arguments réels reçus par Azure CLI dans la syntaxe Python.

    # Correct
$ az '{"key":"value"}' --debug
Command arguments: ['{"key":"value"}', '--debug']

# Correct
$ az "{\"key\":\"value\"}" --debug
Command arguments: ['{"key":"value"}', '--debug']

# Wrong, as quotes and spaces are interpreted by Bash
$ az {"key": "value"} --debug
Command arguments: ['{key:', 'value}', '--debug']

# Wrong, as quotes are interpreted by Bash
$ az {"key":"value"} --debug
Command arguments: ['{key:value}', '--debug']

Utiliser des traits d’union dans les paramètres

Si la valeur d’un paramètre commence par un trait d’union, Azure CLI tente de l’analyser comme nom de paramètre. Pour l’analyser comme valeur, utilisez = pour concaténer le nom et la valeur du paramètre : --password="-VerySecret".

Opérations asynchrones

Les opérations dans Azure peuvent prendre un certain temps. Par exemple, la configuration d’une machine virtuelle dans un centre de données n’est pas instantanée. Azure CLI attend la fin de l’exécution de la commande pour accepter d’autres commandes. De nombreuses commandes offrent donc un paramètre --no-wait comme indiqué ici :

az group delete --name MyResourceGroup --no-wait

Quand vous supprimez un groupe de ressources, toutes les ressources qui lui appartiennent sont également supprimées. La suppression de ces ressources peut prendre beaucoup de temps. Quand vous exécutez la commande avec le paramètre --no-wait, la console accepte de nouvelles commandes sans interrompre la suppression.

De nombreuses commandes offrent une option wait, qui interrompt la console jusqu’à ce qu’une condition soit remplie. L’exemple suivant utilise la commande az vm wait pour prendre en charge la création de ressources indépendantes en parallèle :

az vm create --resource-group VMResources --name virtual-machine-01 --image centos --no-wait
az vm create --resource-group VMResources --name virtual-machine-02 --image centos --no-wait

subscription=$(az account show --query "id" -o tsv)
vm1_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-01"
vm2_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-02"
az vm wait --created --ids $vm1_id $vm2_id

Une fois les deux ID créés, vous pouvez réutiliser la console.

Travail derrière un proxy

Si vous utilisez Azure CLI sur un serveur proxy qui utilise des certificats auto-signés, la bibliothèque de requêtes Python utilisée par Azure CLI peut provoquer l’erreur suivante : SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",). Pour résoudre cette erreur, définissez la variable d’environnement REQUESTS_CA_BUNDLE sur le chemin du fichier de certificat du bundle de l’autorité de certification au format PEM.

Système d’exploitation Bundle par défaut de l’autorité de certification
Windows 32 bits C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem
Windows 64 bits C:\Program Files\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem
Ubuntu/Debian Linux /opt/az/lib/python<version>/site-packages/certifi/cacert.pem
CentOS/RHEL/SUSE Linux /usr/lib64/az/lib/python<version>/site-packages/certifi/cacert.pem
macOS /usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem

Ajoutez le certificat du serveur proxy au fichier de certificat du bundle de l’autorité de certification ou copiez le contenu dans un autre fichier de certificat. Ensuite, définissez REQUESTS_CA_BUNDLE sur l’emplacement du nouveau fichier. Voici un exemple :

<Original cacert.pem>

-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----

Certains proxys nécessitent une authentification. Le format des variables d’environnement HTTP_PROXY ou HTTPS_PROXY doit inclure l’authentification, par exemple HTTPS_PROXY="https://username:password@proxy-server:port". Pour obtenir des détails, consultez Guide pratique pour configurer des proxys pour les bibliothèques Azure.

Exécution simultanée

Si vous exécutez des commandes Azure CLI simultanément sur la même machine, des conflits d’écriture peuvent se produire si plusieurs commandes Azure CLI écrivent dans le même cache de jeton MSAL.

Pour éviter les défaillances potentielles, vous pouvez isoler le dossier de configuration Azure CLI pour chaque script en définissant une variable d’environnement AZURE_CONFIG_DIR pour chaque script dans un répertoire distinct. Les commandes Azure CLI de ce script enregistrent la configuration et le cache de jetons à l’emplacement configuré au lieu du dossier par défaut ~/.azure.

export AZURE_CONFIG_DIR=/my/config/dir

Paramètres de mise à jour génériques

Les groupes de commandes Azure CLI sont souvent dotés d’une commande de mise à jour. Par exemple, Machines virtuelles Azure comprend la commande az vm update. La plupart des commandes de mise à jour proposent les trois paramètres génériques suivants : --add, --set et --remove.

Les paramètres --set et --add acceptent une liste de paires clé-valeur séparées par des espaces : key1=value1 key2=value2. Pour voir les propriétés que vous pouvez mettre à jour, utilisez une commande show, telle que az vm show.

az vm show --resource-group VMResources --name virtual-machine-01

Pour simplifier la commande, envisagez d’utiliser une chaîne JSON. Par exemple, pour attacher un nouveau disque de données à une machine virtuelle, utilisez la valeur suivante :

az vm update --resource-group VMResources --name virtual-machine-01 \
--add storageProfile.dataDisks "{\"createOption\": \"Attach\", \"managedDisk\":
   {\"id\":
   \"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/yg/providers/Microsoft.Compute/disks/yg-disk\"},
   \"lun\": 1}"

Commandes de ressources génériques (az resource)

Il se peut qu’un service que vous voulez utiliser ne prenne pas en charge Azure CLI. Vous pouvez employer les commandes az resource pour utiliser ces ressources.

Si vous avez uniquement besoin de créer ou de mettre à jour des commandes, utilisez la commande az deployment group create. Pour obtenir des exemples fonctionnels, mettez à profit les modèles de démarrage rapide Azure.

Commandes de l’API REST (az rest)

Si les paramètres de mise à jour génériques et az resource ne répondent pas à vos besoins, vous pouvez utiliser la commande az rest pour appeler l’API REST. La commande s’authentifie automatiquement à l’aide des informations d’identification de connexion et définit l’en-tête Content-Type: application/json. Pour plus d’informations, consultez les informations de référence sur l’API REST Azure.

Cet exemple fonctionne avec l’API Microsoft Graph. Afin de mettre à jour les URI de redirection pour une application, appelez l’API REST de mise à jour d’application, comme dans ce code :

# Get the application
az rest --method GET \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001'

# Update `redirectUris` for `web` property
az rest --method PATCH \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001' \
    --body '{"web":{"redirectUris":["https://myapp.com"]}}'

Quand vous utilisez --uri-parameters pour les demandes sous la forme OData, veillez à placer $ avec une séquence d’échappement dans différents environnements : dans Bash, placez $ avec la séquence d’échappement \$ et dans PowerShell, placez $ avec la séquence `$

Exemples de scripts

Voici des exemples d’utilisation de variables et de boucles dans une liste lors de l’utilisation de Machines virtuelles Azure. Pour des exemples plus avancés d’utilisation de constructions Bash avec Azure CLI, notamment des boucles, des instructions case, if..then..else, et la gestion des erreurs, consultez Découvrir comment utiliser Bash avec Azure CLI.

Utilisez ces scripts pour enregistrer des ID dans des variables :

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
   `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    SET "vm_ids=%%F %vm_ids%"  :: construct the id list
)
az vm stop --ids %vm_ids% :: CLI stops all VMs in parallel

Utilisez ces scripts pour boucler dans une liste :

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
    `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    ECHO Stopping %%F
    az vm stop --ids %%F
)

Voir aussi