Considérations relatives à l’exécution d’Azure CLI dans un environnement PowerShell

  • Article

Azure CLI est un outil permettant de gérer des ressources Azure via des commandes de référence Azure CLI qui s’exécutent à la fois dans un environnement Bash et PowerShell. Toutefois, il existe de légères différences de syntaxe dans la mise en forme des paramètres entre les environnements 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 environnement PowerShell.

Cet article compare les différences de syntaxe des commandes Azure CLI exécutées dans les environnements 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 environnement peut prêter à confusion. Comment choisir l’outil en ligne de commande approprié fournit une bonne comparaison.

Prérequis

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 environnements utilisés dans cet article.

Important

Lorsque vous disposez d’un script Azure CLI qui génère une erreur, réfléchissez à la façon dont l’environnement 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 environnements. 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 environnement 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/

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 :

https://learn.microsoft.com/en-us/cli/azure/account?view=azure-cli-2020-09-01-hybrid.

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 environnement 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 environment

# 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

Passer des paramètres contenant un caractère spécial PowerShell

Il existe des caractères spéciaux de PowerShell, tels que le symbole At (@). Pour exécuter Azure CLI 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

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. Notez que le symbole At (@) est un opérateur de platissement dans PowerShell. Il doit donc être entre guillemets.

Il existe de bons exemples dans az ad app create qui contiennent à la fois du contenu de fichier JSON et des exemples de commandes. Voici un extrait de code :

# Script for a Bash environment

az ad app create --display-name myTestAppName \
    --is-fallback-public-client \
    --required-resource-accesses @manifest.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.

Consultez Créer des balises pour vous entraîner à citer des différences dans Learn pour utiliser le didacticiel Azure CLI . Cette étape de tutoriel fournit des exemples pour Bash, PowerShell et Cmd pour les scénarios de paire clé :valeur suivants :

  • espaces
  • valeurs vides
  • caractères spéciaux
  • variables

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 environment

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 environment

$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.

Pour plus d’informations sur la gestion des erreurs PowerShell, consultez Tout ce que vous avez toujours voulu savoir sur les exceptions.

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 :

  1. 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.

  2. Ajoutez le code suivant à votre profil PowerShell :

    Register-ArgumentCompleter -Native -CommandName az -ScriptBlock {
    param($commandName, $wordToComplete, $cursorPosition)
    $completion_file = New-TemporaryFile
    $env:ARGCOMPLETE_USE_TEMPFILES = 1
    $env:_ARGCOMPLETE_STDOUT_FILENAME = $completion_file
    $env:COMP_LINE = $wordToComplete
    $env:COMP_POINT = $cursorPosition
    $env:_ARGCOMPLETE = 1
    $env:_ARGCOMPLETE_SUPPRESS_SPACE = 0
    $env:_ARGCOMPLETE_IFS = "`n"
    $env:_ARGCOMPLETE_SHELL = 'powershell'
    az 2>&1 | Out-Null
    Get-Content $completion_file | Sort-Object | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)
    }
    Remove-Item $completion_file, Env:\_ARGCOMPLETE_STDOUT_FILENAME, Env:\ARGCOMPLETE_USE_TEMPFILES, Env:\COMP_LINE, Env:\COMP_POINT, Env:\_ARGCOMPLETE, Env:\_ARGCOMPLETE_SUPPRESS_SPACE, Env:\_ARGCOMPLETE_IFS, Env:\_ARGCOMPLETE_SHELL
}

  3. Pour afficher toutes les options disponibles dans le menu, ajoutez Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete à votre profil PowerShell.

Voir aussi