Considerazioni sull'esecuzione dell'interfaccia della riga di comando di Azure in un ambiente 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 ambiente Bash e PowerShell. Tuttavia, esistono lievi differenze di sintassi nella formattazione dei parametri tra ambienti 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 ambiente PowerShell.

Questo articolo confronta le differenze di sintassi dei comandi dell'interfaccia della riga di comando di Azure eseguiti negli ambienti 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 ambiente 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 gli ambienti usati in questo articolo.

Importante

Quando si dispone di uno script dell'interfaccia della riga di comando di Azure che genera un errore, prendere in considerazione il modo in cui l'ambiente 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 sistemi operativi e ambienti. 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 ambiente PowerShell, viene visualizzato il messaggio di argument --query: invalid jmespath_type value: "[?creationTime >=..."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://learn.microsoft.com/en-us/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 ambiente 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 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

Passare parametri contenenti un carattere speciale di PowerShell

Sono presenti caratteri speciali di PowerShell, ad esempio il simbolo At (@). Per eseguire l'interfaccia della riga di comando di Azure 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

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. Si noti che il simbolo At (@) è un operatore splatting in PowerShell, quindi deve essere racchiuso tra virgolette.

Sono disponibili esempi validi in az ad app create che contengono sia contenuto di file JSON che esempi di comandi. Ecco un frammento di codice:

# Script for a Bash environment

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

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 fornisce esempi per Bash, PowerShell e Cmd per gli scenari di coppia chiave:valore seguenti:

  • Spazi
  • valori vuoti
  • caratteri speciali
  • variables

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 environment

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

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