Considerazioni sull'esecuzione dell'interfaccia della riga di comando di Azure in un linguaggio di scripting di PowerShell

  • Articolo

L'interfaccia della riga di comando di Azure è uno strumento per gestire le risorse di Azure tramite i comandi di riferimento dell'interfaccia della riga di comando di Azure eseguiti in un linguaggio di scripting Bash e PowerShell. Tuttavia, esistono lievi differenze di sintassi nella formattazione dei parametri tra i linguaggi di scripting che possono comportare risultati imprevisti. Lo scopo di questo articolo è risolvere gli errori di sintassi dell'interfaccia della riga di comando di Azure quando si lavora in un linguaggio di scripting di PowerShell.

Questo articolo confronta le differenze di sintassi dei comandi dell'interfaccia della riga di comando di Azure eseguiti nei linguaggi di scripting seguenti:

  • Bash in esecuzione in un sistema operativo Linux con Azure Cloud Shell.
  • PowerShell in esecuzione in un sistema operativo Linux con Azure Cloud Shell.
  • Windows PowerShell in esecuzione in Windows 11 usando il terminale di PowerShell 5.
  • PowerShell in esecuzione in windows 11 usando il terminale di PowerShell 7.

Se non si ha familiarità con l'interfaccia della riga di comando, la differenziazione tra uno strumento e un linguaggio di scripting potrebbe generare confusione. La procedura per scegliere lo strumento da riga di comando corretto offre un buon confronto.

Prerequisiti

Questo articolo è destinato alla lettura e all'apprendimento. Tuttavia, se si desidera eseguire gli esempi, selezionare la Prepare your environments scheda per installare i linguaggi di scripting usati in questo articolo.

Importante

Quando si dispone di uno script dell'interfaccia della riga di comando di Azure che genera un errore, considerare il modo in cui il linguaggio di scripting in uso sta analizzando la sintassi dei comandi dell'interfaccia della riga di comando di Azure.

Passare spazi nei parametri dell'interfaccia della riga di comando di Azure

Nell'interfaccia della riga di comando di Azure, quando è necessario passare un valore di parametro contenente uno spazio, esistono differenze tra i sistemi operativi e i linguaggi di scripting. In questo esempio usare az storage account list e rinominare le colonne di output con una parola contenente uno spazio.

In questo esempio si noti il wrapper tra virgolette singole ('...') con virgolette doppie incorporate ("..."). Questo esempio funziona anche in PowerShell in Linux.

az storage account list --query '[].{"SA Name":name, "Primary endpoint":primaryEndpoints.blob}' --output table

Se si desidera aggiungere un filtro, la sintassi cambia. Si noti che questo esempio esegue il wrapping del valore del --query parametro tra virgolette doppie ("...") e usa un carattere di escape barra rovesciata (\). Questo script non viene eseguito in PowerShell.

 az storage account list --query "[?creationTime >='2024-02-01'].{\"SA Name\":name,\"Primary endpoint\":primaryEndpoints.blob}" --output table

Se si è appena provato a eseguire la sintassi del filtro in un linguaggio di scripting di PowerShell, viene visualizzato il messaggio argument --query: invalid jmespath_type value: "[?creationTime >=..."di errore . Tuttavia, in Bash all'interno di un ambiente Linux, l'output è simile al seguente:

SA Name           Primary Endpoint
-----------       -----------------
msdocssa00000000  https://msdocssa000000000.blob.core.windows.net/

Passare parametri in un URL contenente una stringa di query

I punti interrogativi negli URL indicano la fine dell'URL e l'inizio di una stringa di query. Ecco un esempio che apre il passaggio 3 in Learn per usare l'interfaccia della riga di comando di Azure:

https://video2.skills-academy.com/cli/azure/account?view=azure-cli-2020-09-01-hybrid.

Il ?view=azure-cli-2020-09-01-hybrid risultato è la versione desiderata del contenuto di riferimento dell'interfaccia della riga di comando di Azure.

Quando si eseguono comandi dell'interfaccia della riga di comando di Azure in un linguaggio di scripting di PowerShell, PowerShell consente ai punti interrogativi di far parte di un nome di variabile. Questo potrebbe creare confusione nei valori dei parametri dell'interfaccia della riga di comando di Azure.

Ecco un esempio dell'articolo Usare l'API REST di Azure:

Si noti come $containerRegistryName?api-version concatenare insieme senza errori in 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

Passare parametri contenenti il simbolo di e commerciale

Se si ha uno scenario in cui è necessario passare una e commerciale in un valore di parametro, tenere presente che il simbolo e commerciale (&) viene interpretato da PowerShell. È possibile osservare che ciò avviene usando il --debug parametro :

az "a&b" --debug

# output
'a' is misspelled or not recognized by the system.
'b' is not recognized as an internal or external command

Tuttavia, se si usa lo stesso test per aggiungere un tag a un gruppo di risorse, l'e commerciale nel valore del tag non genera un errore.

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

Se si ha uno scenario in cui l'e commerciale in un valore di parametro causa un errore, ecco alcune soluzioni:

# 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']

Passare parametri contenenti un simbolo at (@)

Esistono caratteri speciali di PowerShell, ad esempio il simbolo at (@) che è un operatore splatting in PowerShell. Aggiungere un backtick ` prima del carattere speciale per eseguirne l'escape. È anche possibile racchiudere il valore tra virgolette singole (') o doppie (").

I tre esempi seguenti funzioneranno in PowerShell:

  • parameterName '@parameters.json
  • parameterName '@parameters.json'
  • parameterName "@parameters.json"

Questo esempio non funzionerà in PowerShell:

  • parameterName @parameters.json

Ecco un altro esempio nel az ad app create comando: si notino le virgolette doppie ("...") intorno al nome del file JSON necessario in un linguaggio di scripting di PowerShell.

# Script for a PowerShell scripting language

az ad app create --display-name myTestAppName `
    --is-fallback-public-client `
    --required-resource-accesses "@manifest.json"

Passare parametri contenenti JSON

Per argomenti complessi come una stringa JSON, la procedura consigliata consiste nell'usare la convenzione dell'interfaccia della riga di comando di @<file> Azure per caricare da un file per ignorare l'interpretazione della shell. Per esempi di sintassi JSON per Bash, PowerShell e Cmd.exe, vedere Differenze tra linguaggi di scripting - stringhe JSON.

Passare parametri contenenti coppie chiave:valore

Alcuni valori dei parametri dell'interfaccia della riga di comando di Azure, ad esempio i tag delle risorse di Azure, richiedono coppie chiave:valore. Se l'oggetto key o value contiene uno spazio o un carattere speciale, la sintassi Bash e PowerShell non sono sempre uguali.

Per esempi di sintassi per Bash, PowerShell e Cmd, vedere Creare tag per praticare le differenze tra virgolette nell'esercitazione Su come usare l'interfaccia della riga di comando di Azure . Questo passaggio dell'esercitazione offre esempi per gli scenari di coppie chiave:valore seguenti:

  • Spazi
  • valori vuoti
  • caratteri speciali
  • variabili

Simbolo di interruzione dell'analisi

Il simbolo di interruzione dell'analisi (--%), introdotto in PowerShell 3.0, indica a PowerShell di non interpretare l'input come comandi o espressioni di PowerShell. Quando rileva un simbolo di interruzione dell'analisi, PowerShell considera i caratteri rimanenti nella riga come valore letterale.

az --% vm create --name xxx

Gestione degli errori per l'interfaccia della riga di comando di Azure in PowerShell

È possibile eseguire i comandi dell'interfaccia della riga di comando di Azure in PowerShell, come descritto in Scegliere lo strumento da riga di comando di Azure corretto. In questo caso, assicurarsi di comprendere la gestione degli errori dell'interfaccia della riga di comando di Azure in PowerShell. In particolare, l'interfaccia della riga di comando di Azure non crea eccezioni che PowerShell intercetta.

Un'alternativa consiste nell'usare la $? variabile automatica. Questa variabile contiene lo stato del comando più recente. Se il comando precedente ha esito negativo, $? ha il valore di $False. Per altre informazioni, vedere about_Automatic_Variables.

L'esempio seguente illustra il funzionamento di questa variabile automatica per la gestione degli errori:

# Script for a PowerShell scripting language

az group create --name MyResourceGroup
if ($? -eq $false) {
    Write-Error "Error creating resource group."
}

Il az comando ha esito negativo perché manca il parametro obbligatorio --location . L'istruzione condizionale rileva che $? è false e scrive un errore.

Se si vogliono usare le try parole chiave e catch , è possibile usare throw per creare un'eccezione per il try blocco da intercettare:

# 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"

Per impostazione predefinita, PowerShell rileva solo gli errori irreversibili. Questo esempio imposta la $ErrorActionPreference variabile globale su Stop in modo che PowerShell possa gestire l'errore.

L'istruzione condizionale verifica la $? variabile per verificare se il comando precedente non è riuscito. In tal caso, la throw parola chiave crea un'eccezione da intercettare. Il catch blocco può essere usato per scrivere un messaggio di errore o gestire l'errore.

Nell'esempio viene ripristinato $ErrorActionPreference il valore predefinito.

Per altre informazioni sulla gestione degli errori di PowerShell, vedere Tutto ciò che si desidera conoscere sulle eccezioni.

Abilitare il completamento tramite tabulazione in PowerShell

Il completamento tramite tabulazione, noto anche come "completer dell'interfaccia della riga di comando di Azure", fornisce il completamento sugli input per fornire suggerimenti, abilitare l'individuazione e velocizzare la voce di input. I nomi dei comandi, i nomi dei gruppi di comandi, i parametri e determinati valori di parametro possono essere inseriti automaticamente nella riga di comando premendo TAB.

Il completamento tramite tabulazione è abilitato per impostazione predefinita in Azure Cloud Shell e nella maggior parte delle distribuzioni Linux. A partire dalla versione 2.49 dell'interfaccia della riga di comando di Azure, è possibile abilitare il completamento della scheda per l'interfaccia della riga di comando di Azure in PowerShell. Seguire questa procedura:

  1. Creare o modificare il profilo archiviato nella variabile $PROFILE. Il modo più semplice consiste nell'eseguire notepad $PROFILE in PowerShell. Per altre informazioni, vedere How to create your profile (Come creare un profilo) e Profiles and execution policy (Profili e criteri di esecuzione).

  2. Aggiungere il codice seguente al profilo di 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. Per visualizzare tutte le opzioni disponibili nel menu, aggiungere Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete al profilo di PowerShell.

Vedi anche