Condividi tramite

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

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 di Azure CLI

Nell'Azure CLI, quando è necessario passare un valore di parametro contenente uno spazio, ci sono differenze di quotazione tra sistemi operativi e 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, osserva come il testo sia racchiuso 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 racchiude il valore del parametro --query tra virgolette doppie ("...") e utilizza un carattere di escape con una 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 Impara a usare l'interfaccia a riga di comando di Azure:

/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 si concateni 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 "&"

Se ti trovi in uno scenario in cui devi includere un ampersand in un valore di parametro, ricorda che il simbolo ampersand (&) 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 utilizzi lo stesso test per aggiungere un tag a un gruppo di risorse, il simbolo & nel valore del tag non causa 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 il simbolo & 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, come il simbolo at (@), che funge da splatting operator 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:

  • nomeParametro @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'Azure CLI @<file> per caricare da un file ed evitare l'interpretazione della shell. Per esempi di sintassi JSON per Bash, PowerShell e Cmd.exe, consultare 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 esercitarsi nelle differenze di utilizzo delle virgolette nell'esercitazione per imparare a usare l'interfaccia della riga di comando di Azure. Questo passaggio dell'esercitazione offre esempi per gli scenari delle 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 Azure CLI 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 tal caso, assicurati di comprendere come gestire gli errori di Azure CLI in PowerShell. In particolare, l'interfaccia della riga di comando di Azure non crea eccezioni che PowerShell possa gestire.

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 $? è falsa e segnala 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, $ErrorActionPreference viene ripristinato al suo valore predefinito.

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

Abilitare il completamento tramite Tab in PowerShell

Il completamento tramite tabulazione, noto anche come "completer CLI di Azure", fornisce il completamento sugli input per offrire suggerimenti, consentire l'individuazione e velocizzare l'inserimento 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. Segui questi passaggi:

  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.

Vedere anche