Partager via

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.

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 langages de script 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 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/

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/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 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

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.

az group create --location eastus2 --name "msdocs-rg-test"
az group update --name "msdocs-rg-test" --tags "company name=Contoso & Sons"

# output
{
  "id": "/subscriptions/3618afcd-ea52-4ceb-bb46-53bb962d4e0b/resourceGroups/msdocs-rg-test",
  "location": "eastus2",
  "managedBy": null,
  "name": "msdocs-rg-test",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": {
    "company name": "Contoso & Sons"
  },
  "type": "Microsoft.Resources/resourceGroups"
}

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 key value ou contient un espace ou un caractère spécial, la syntaxe Bash et PowerShell ne sont pas toujours les mêmes.

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

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

Symbole d’analyse d’arrêt

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.

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