Considérations relatives à l’exécution d’Azure CLI dans un langage de script PowerShell
Article
Azure CLI est un outil permettant de gérer les ressources Azure via des commandes de référence Azure CLI qui s’exécutent à la fois dans un langage de script Bash et PowerShell. Toutefois, il existe de légères différences de syntaxe dans la mise en forme des paramètres entre les langages de script qui peuvent entraîner des résultats inattendus. L’objectif de cet article est de vous aider à résoudre les erreurs de syntaxe Azure CLI lors de l’utilisation d’un langage de script PowerShell.
Cet article compare les différences de syntaxe des commandes Azure CLI exécutées dans les langages de script suivants :
Bash s’exécutant dans un système d’exploitation Linux à l’aide d’Azure Cloud Shell.
PowerShell s’exécutant dans un système d’exploitation Linux à l’aide d’Azure Cloud Shell.
Windows PowerShell s’exécutant dans Windows 11 à l’aide du terminal PowerShell 5.
PowerShell s’exécutant dans windows 11 à l’aide du terminal PowerShell 7.
Si vous débutez avec l’interface CLI, la différenciation entre un outil et un langage de script peut prêter à confusion. Comment choisir l’outil en ligne de commande approprié fournit une bonne comparaison.
Cet article est destiné à vous permettre de lire et d’apprendre. Toutefois, si vous souhaitez exécuter les exemples, sélectionnez l’onglet Prepare your environments pour installer les langages de script utilisés dans cet article.
Pour exécuter les cas de test donnés dans cet article, installez ou ouvrez ces langages de script :
Environnements Linux
Dans votre application Internet de choix ou dans Terminal Windows, ouvrez deux onglets à l’aide des liens fournis.
Instance d’Azure Cloud Shell exécutée avec Bash.
Si Azure Cloud Shell s’ouvre dans un langage de script PowerShell, sélectionnez l’option Bash dans la barre de menus Cloud Shell.
Deuxième instance d’Azure Cloud Shell exécutée avec PowerShell. Si Azure Cloud Shell s’ouvre dans un langage de script Bash, sélectionnez l’option Basculer vers PowerShell dans la barre de menus Cloud Shell.
Environnements Microsoft Windows
Installation locale d’Azure CLI dans un environnement Windows.
Installation locale de Windows PowerShell 5.1 préinstallée dans la plupart des systèmes d’exploitation Windows.
Installation locale de PowerShell 7 dans un environnement Windows.
Cet article a été testé dans Windows 11 Entreprise version 23H2.
Testez pour voir quelle version d’Azure CLI et PowerShell vous utilisez.
az version
$PSVersionTable
Voici la sortie d’Azure Cloud Shell, qui est la version la plus récente d’Azure CLI et de PowerShell :
Voici la sortie d’un terminal Windows PowerShell 5, qui est la version d’Azure CLI et de PowerShell installée sur votre ordinateur. Dans cet exemple de sortie, Azure CLI version 2.57.0 et Windows PowerShell 5.1.22621 sont installés sur l’ordinateur local.
Si vous exécutez $PSVersionTable un terminal PowerShell 7, votre version PowerShell est PSVersion 7 ou ultérieure en fonction de ce qui est installé sur votre ordinateur local.
Si vous avez besoin d’un compte de stockage Azure pour exécuter ces scripts de test, créez-en un maintenant.
# Bash syntax example
# Variable block
let "randomIdentifier=$RANDOM*$RANDOM"
location=eastus
resourceGroup="msdocs-test-rg-$randomIdentifier"
storageAccount="msdocssa$randomIdentifier"
# Create a resource group.
az group create --name $resourceGroup --location $location
# Create a storage account.
echo "Creating storage account $storageAccount in resource group $resourceGroup"
az storage account create --name $storageAccount \
--resource-group $resourceGroup \
--location $location \
--sku Standard_RAGRS \
--kind StorageV2 \
--output json
# PowerShell syntax example
# Variable block
$randomIdentifier = $(Get-Random)
$location="eastus"
$resourceGroup="msdocs-test-rg-$randomIdentifier"
$storageAccount="msdocssa$randomIdentifier"
# Create a resource group.
az group create --name $resourceGroup --location $location
# Create a storage account.
echo "Creating storage account $storageAccount in resource group $resourceGroup"
az storage account create --name $storageAccount `
--resource-group $resourceGroup `
--location $location `
--sku Standard_RAGRS `
--kind StorageV2 `
--output json
Azure CLI retourne plus de 100 lignes de sortie JSON lorsqu’un nouveau compte de stockage est créé. Le dictionnaire JSON suivant contient des champs omis pour la concision.
Lorsque vous disposez d’un script Azure CLI qui génère une erreur, réfléchissez à la façon dont le langage de script dans lequel vous travaillez consiste à analyser la syntaxe de commande Azure CLI.
Passer des espaces dans les paramètres Azure CLI
Dans Azure CLI, lorsque vous devez passer une valeur de paramètre contenant un espace, il existe des différences entre les systèmes d’exploitation et les langages de script. Dans cet exemple, utilisez az storage account list et renommez les colonnes de sortie avec un mot contenant un espace.
Dans cet exemple, notez le wrapper de guillemets simples ('...') avec des guillemets doubles incorporés ("...").
Cet exemple fonctionne également dans PowerShell dans Linux.
az storage account list --query '[].{"SA Name":name, "Primary endpoint":primaryEndpoints.blob}' --output table
Si vous souhaitez ajouter un filtre, la syntaxe change. Notez comment cet exemple encapsule la valeur du --query paramètre entre guillemets doubles ("...") et utilise une barre oblique inverse (\) caractère d’échappement. Ce script ne s’exécute pas dans PowerShell.
az storage account list --query "[?creationTime >='2024-02-01'].{\"SA Name\":name,\"Primary endpoint\":primaryEndpoints.blob}" --output table
Si vous venez d’essayer d’exécuter la syntaxe de filtre dans un langage de script PowerShell, vous avez reçu un message argument --query: invalid jmespath_type value: "[?creationTime >=..."d’erreur . Toutefois, dans Bash dans un environnement Linux, votre sortie est similaire à ceci :
SA Name Primary Endpoint
----------- -----------------
msdocssa00000000 https://msdocssa000000000.blob.core.windows.net/
Dans cet exemple, notez le wrapper de guillemets doubles ("...") avec guillemets doubles incorporés et le caractère d’échappement backtick ` .
az storage account list --query "[].{`"SA Name`":name, `"Primary endpoint`":primaryEndpoints.blob}" --output table
Si vous exécutez cette syntaxe dans Windows PowerShell ou PowerShell 7 installé sur l’ordinateur d’une fenêtre, vous recevez une erreur argument --query: invalid jmespath_type value: '[].{SA'. Notez comment le message d’erreur s’interrompt sur l’espace entre SA et Name. Dans Bash dans un environnement Linux, votre message d’erreur est argument --query: invalid jmespath_type value: '[].{:name,'.
Ajoutez maintenant un filtre. Contrairement au script Bash, l’ajout d’un filtre de date ne nécessite pas de remaniement de la chaîne entière --query .
az storage account list --query "[?creationTime >='2024-02-01'].{`"SA Name`":name, `"Primary endpoint`":primaryEndpoints.blob}" --output table
Dans cet exemple, notez les guillemets simples ('...') wrapper avec des guillemets doubles incorporés (""..."") et une barre oblique inverse des caractères d’échappement (\).
az storage account list --query '[].{\"SA Name\":name,\"Primary endpoint\":primaryEndpoints.blob}' --output table
Notez les guillemets simples ('...') wrapper avec des paires de guillemets doubles incorporées (""...""). Ce script s’exécute également correctement dans Windows PowerShell 5.
az storage account list --query '[].{""SA Name"":name,""Primary endpoint"":primaryEndpoints.blob}' --output table
Appliquez un creationTime filtre et notez que le wrapper à guillemet unique reste, mais une paire de guillemets'...' unique incorporée (''...'') est utilisée pour entourer la valeur de date. Ce script s’exécute également correctement dans Windows PowerShell 5.
az storage account list --query '[?creationTime >=''2024-02-01''].{""SA Name"":name,""Primary endpoint"":primaryEndpoints.blob}' --output table
Dans cet exemple, notez le wrapper de guillemets simples ('...') avec des paires guillemets doubles incorporées (""...""). Ce script s’exécute également correctement dans PowerShell 7 dans un environnement Windows.
az storage account list --query '[].{""SA Name"":name,""Primary endpoint"":primaryEndpoints.blob}' --output table
Appliquez un creationTime filtre et notez que le wrapper à guillemet unique reste, mais une paire de guillemets'...' unique incorporée (''...'') est utilisée pour entourer la valeur de date. Ce script s’exécute également correctement dans PowerShell 7 dans un environnement Windows.
az storage account list --query '[?creationTime >=''2024-02-01''].{""SA Name"":name,""Primary endpoint"":primaryEndpoints.blob}' --output table
Avez-vous reçu une argument --query: invalid jmespath_type value:... erreur des scripts de cet onglet ? Cette erreur est retournée lors de l’exécution de ces scripts Windows dans Bash ou PowerShell 7 dans un environnement Linux.
Transmettre des paramètres dans une URL contenant une chaîne de requête
Les points d’interrogation dans les URL indiquent la fin de l’URL et le début d’une chaîne de requête. Voici un exemple qui ouvre l’étape 3 dans Learn pour utiliser Azure CLI :
Les ?view=azure-cli-2020-09-01-hybrid résultats de la version souhaitée du contenu de référence Azure CLI.
Lorsque vous exécutez des commandes Azure CLI dans un langage de script PowerShell, PowerShell permet aux points d’interrogation de faire partie d’un nom de variable. Cela peut créer une confusion dans les valeurs des paramètres Azure CLI.
Voici un exemple de l’article Utiliser l’API REST Azure :
Notez comment $containerRegistryName?api-version concatène sans erreur dans Bash.
# Script for a Bash scripting language
# Variable block
let "randomIdentifier=$RANDOM*$RANDOM"
subscriptionId="00000000-0000-0000-0000-000000000000"
resourceGroup="msdocs-app-rg$randomIdentifier"
containerRegistryName="msdocscr$randomIdentifier"
# prior to this GET example, the resource group and container registry were created in the article.
az rest --method get --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview
Notez les crochets {} nécessaires dans PowerShell pour ${containerRegistryName}?api-version. Sans crochets, PowerShell interprète un point d’interrogation (?) comme faisant partie du nom $containerRegistryNamedu paramètre.
Ce comportement est le même dans PowerShell 5 et PowerShell 7 s’exécutant sous Linux ou Windows.
# Script for a PowerShell scripting language
# Variable block
$randomIdentifier = (New-Guid).ToString().Substring(0,8)
$subscriptionId="00000000-0000-0000-0000-000000000000"
$resourceGroup="msdocs-app-rg$randomIdentifier"
$containerRegistryName="msdocscr$randomIdentifier"
# prior to this GET example, the resource group and container registry were created in the article.
az rest --method get --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/${containerRegistryName}?api-version=2023-01-01-preview
Passer les paramètres contenant le symbole d’ampersand
Si vous avez un scénario où vous devez passer un ampersand dans une valeur de paramètre, sachez que le symbole ampersand (&) est interprété par PowerShell. Vous pouvez voir que cela se produit à l’aide du --debug paramètre :
az "a&b" --debug
# output
'a' is misspelled or not recognized by the system.
'b' is not recognized as an internal or external command
Toutefois, si vous utilisez ce même test pour ajouter une balise à un groupe de ressources, l’ampersand dans la valeur de la balise n’entraîne pas d’erreur.
Si vous avez un scénario où l’ampersand dans une valeur de paramètre provoque une erreur, voici quelques solutions :
# When quoted by single quotes ('), double quotes (") are preserved by PowerShell and sent
# to Command Prompt, so that ampersand (&) is treated as a literal character
> az '"a&b"' --debug
Command arguments: ['a&b', '--debug']
# Escape double quotes (") with backticks (`) as required by PowerShell
> az "`"a&b`"" --debug
Command arguments: ['a&b', '--debug']
# Escape double quotes (") by repeating them
> az """a&b""" --debug
Command arguments: ['a&b', '--debug']
# With a whitespace in the argument, double quotes (") are preserved by PowerShell and
# sent to Command Prompt
> az "a&b " --debug
Command arguments: ['a&b ', '--debug']
# Use --% to stop PowerShell from parsing the argument
> az --% "a&b" --debug
Command arguments: ['a&b', '--debug']
Passer des paramètres contenant un symbole à (@)
Il existe des caractères spéciaux de PowerShell, tels que le symbole at (@) qui est un opérateur de platissement dans PowerShell. Ajoutez un backtick ` avant le caractère spécial pour l’échapper. Vous pouvez également placer la valeur entre guillemets simples (') ou doubles (").
Les trois exemples suivants fonctionnent dans PowerShell :
parameterName '@parameters.json
parameterName '@parameters.json'
parameterName « @parameters.json »
Cet exemple ne fonctionnera pas dans PowerShell :
parameterName @parameters.json
Voici un autre exemple de la az ad app create commande : notez les guillemets doubles ("...") autour du nom de fichier JSON nécessaire dans un langage de script PowerShell.
# Script for a PowerShell scripting language
az ad app create --display-name myTestAppName `
--is-fallback-public-client `
--required-resource-accesses "@manifest.json"
Passer des paramètres contenant JSON
Pour les arguments complexes comme une chaîne JSON, la meilleure pratique consiste à utiliser la convention d’Azure @<file> CLI pour charger à partir d’un fichier afin de contourner l’interprétation de l’interpréteur de commandes. Pour obtenir des exemples de syntaxe JSON pour Bash, PowerShell et Cmd.exe, consultez les différences entre les langages de script - chaînes JSON.
Passer des paramètres contenant des paires clé :valeur
Certaines valeurs de paramètre Azure CLI, telles que les étiquettes de ressources Azure, nécessitent des paires clé :valeur. Si votre keyvalue ou contient un espace ou un caractère spécial, la syntaxe Bash et PowerShell ne sont pas toujours les mêmes.
Le symbole d’analyse d’arrêt (--%), introduit dans PowerShell 3.0, dirige PowerShell pour s’abstenir d’interpréter l’entrée en tant que commandes ou expressions PowerShell. Lorsqu’il rencontre un symbole d’analyse d’arrêt, PowerShell traite les caractères restants de la ligne comme un littéral.
az --% vm create --name xxx
Gestion des erreurs pour Azure CLI dans PowerShell
Vous pouvez exécuter des commandes Azure CLI dans PowerShell, comme décrit dans Choisir le bon outil en ligne de commande Azure.
Si vous le faites, assurez-vous de bien comprendre la gestion des erreurs Azure CLI dans PowerShell. Plus précisément, Azure CLI ne crée pas d’exceptions que PowerShell intercepte.
Une alternative consiste à utiliser la variable automatique $?. Cette variable contient l’état de la commande la plus récente. Si la commande précédente échoue, $? a la valeur de $False. Pour plus d’informations, consultez about_Automatic_Variables.
L’exemple suivant montre comment cette variable automatique peut fonctionner pour la gestion des erreurs :
# Script for a PowerShell scripting language
az group create --name MyResourceGroup
if ($? -eq $false) {
Write-Error "Error creating resource group."
}
La commande az échoue, car le paramètre obligatoire --location est manquant. L’instruction conditionnelle trouve que $? est false et écrit une erreur.
Si vous souhaitez utiliser les mots clés try et catch, vous pouvez utiliser throw pour créer une exception pour que le bloc try intercepte :
# Script for a PowerShell scripting language
$ErrorActionPreference = "Stop"
try {
az group create --name MyResourceGroup
if ($? -eq $false) {
throw 'Group create failed.'
}
}
catch {
Write-Error "Error creating the resource group."
}
$ErrorActionPreference = "Continue"
Par défaut, PowerShell intercepte uniquement les erreurs d’arrêt. Cet exemple affecte à la variable globale $ErrorActionPreference la valeur Stop pour que PowerShell puisse gérer l’erreur.
L’instruction conditionnelle teste la variable $? pour voir si la commande précédente a échoué. Si c’est le cas, le mot clé throw crée une exception à intercepter. Le bloc catch peut être utilisé pour écrire un message d’erreur ou gérer l’erreur.
L’exemple restaure $ErrorActionPreference à sa valeur par défaut.
Activer la saisie semi-automatique via la touche Tab dans PowerShell
La saisie semi-automatique via la touche Tab, également connue comme « compléteurs Azure CLI », propose une saisie-automatique des entrées pour obtenir des indicateurs, activer la détection et accélérer la saisie. Les noms de commandes, les noms de groupes de commandes, les paramètres et certaines valeurs de paramètres peuvent être automatiquement saisis dans la ligne de commande en appuyant sur la touche Tab.
La saisie semi-automatique via la touche Tab est activée par défaut dans Azure Cloud Shell et dans la plupart des distributions Linux. À partir de la version 2.49 d’Azure CLI, vous pouvez activer la saisie semi-automatique via la touche Tab pour Azure CLI dans PowerShell. Suivez ces étapes :
Créez ou modifiez le profil stocké dans la variable $PROFILE. Le plus simple consiste à exécuter notepad $PROFILE dans PowerShell. Pour plus d’informations, consultez Création de votre profil et Profils et stratégie d’exécution.
Ajoutez le code suivant à votre profil PowerShell :
La source de ce contenu se trouve sur GitHub, où vous pouvez également créer et examiner les problèmes et les demandes de tirage. Pour plus d’informations, consultez notre guide du contributeur.
Commentaires sur Azure CLI
Azure CLI est un projet open source. Sélectionnez un lien pour fournir des commentaires :
Ce module traite de la structure et des paramètres de cmdlet pour l’utilisation des cmdlets Windows PowerShell. Il explique également comment utiliser la saisie semi-automatique via la touche Tab, et afficher des informations sur le contenu À propos des fichiers.