Suggerimenti per un uso corretto dell'interfaccia della riga di comando di Azure

  • Articolo

L'interfaccia della riga di comando di Azure è uno strumento da riga di comando che consente di configurare e gestire le risorse di Azure da molti ambienti della shell. Dopo aver scelto l'ambiente shell preferito e aver installato l'interfaccia della riga di comando di Azure, usare questo articolo per scoprire suggerimenti utili su come evitare problemi comuni e usare correttamente l'interfaccia della riga di comando di Azure.

Per altre informazioni sui comandi specifici dell'interfaccia della riga di comando di Azure, vedere l'elenco di riferimento dell'interfaccia della riga di comando di Azure.

Formattazione dell'output

Con i comandi dell'interfaccia della riga di comando di Azure vengono usati tre formati di output comuni:

  1. Il json formato mostra le informazioni come stringa JSON.

    • JSON offre le informazioni più complete.
    • Questo formato è l'impostazione predefinita, ma è possibile usare il --output parametro per specificare un'opzione diversa.
    • Modificare il formato predefinito globale in una delle preferenze personali usando az config , az config set core.output=tablead esempio .
    • Il formato JSON mantiene le virgolette doppie, in genere rendendolo non adatto per scopi di scripting.

  2. Il table formato presenta l'output come tabella leggibile. È possibile specificare i valori visualizzati nella tabella e usare le query per personalizzare l'output, come illustrato di seguito:

    # command
az vm show --resource-group myResourceGroup --name myVMname --query "{name: name, os:storageProfile.imageReference.offer}" --output table

# output
Name    Os
------  ------------
myVMname   UbuntuServer

  3. Il tsv formato restituisce valori delimitati da tabulazioni e delimitati da nuova riga senza formattazione aggiuntiva, chiavi o altri simboli.

    • Il formato TSV è utile per scopi di output e scripting concisi.
    • Le strisce TSV tra virgolette doppie mantenute dal formato JSON.
    • Per specificare il formato desiderato per TSV, usare il --query parametro .
    export vm_ids=$(az vm list --show-details --resource-group myResourceGroup --query "[?powerState=='VM running'].id" --output tsv)
az vm stop --ids $vm_ids

Per altre informazioni su questi e altri formati, vedere Formati di output per i comandi dell'interfaccia della riga di comando di Azure.

Passare valori a un altro comando

Se il valore viene usato più volte, assegnarlo a una variabile. Le variabili consentono di usare più volte i valori o di creare script più generali. Questo esempio assegna un ID trovato dal comando az vm list a una variabile.

# assign the list of running VMs to a variable
running_vm_ids=$(az vm list --resource-group MyResourceGroup --show-details \
    --query "[?powerState=='VM running'].id" --output tsv)

# verify the value of the variable
echo $running_vm_ids

Se il valore viene usato una sola volta, prendere in considerazione il piping. Il piping passa l'output di un comando come input a un secondo comando.

az vm list --query "[?powerState=='VM running'].name" --output tsv | grep my_vm

Per gli elenchi multivalore, considerare le opzioni seguenti:

  1. Se sono necessari altri controlli sul risultato, usare un ciclo "for":

    #!/usr/bin/env bash
for vmList in $(az vm list --resource-group MyResourceGroup --show-details --query "[?powerState=='VM running'].id"   --output tsv); do
    echo stopping $vmList
    az vm stop --ids $vmList
    if [ $? -ne 0 ]; then
        echo "Failed to stop $vmList"
        exit 1
    fi
    echo $vmList stopped
done

  2. In alternativa, usare xargs e valutare se usare il flag -P per eseguire le operazioni in parallelo per migliorare le prestazioni:

    az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | xargs -I {} -P 10 az vm start --ids "{}"

  3. Infine, l'interfaccia della riga di comando di Azure include il supporto predefinito per elaborare i comandi con più --ids in parallelo per ottenere lo stesso effetto di xargs. @- viene usato per ottenere valori dalla pipe:

    az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | az vm start --ids @-

Per altre informazioni sull'uso di costrutti Bash con l'interfaccia della riga di comando di Azure, inclusi cicli, istruzioni case, if.. Poi.. altrimenti e la gestione degli errori, vedere Informazioni sull'uso di Bash con l'interfaccia della riga di comando di Azure.

Usare le virgolette nei parametri

Quando si usano i comandi dell'interfaccia della riga di comando di Azure, tenere presente come la shell usa le virgolette e i caratteri di escape. Se si supportano gli script usati in shell diverse, comprendere le differenze.

Nota

A causa di un problema noto in PowerShell, si applicano alcune regole di escape aggiuntive. Per altre informazioni, vedere Problemi di virgolette con PowerShell.

Ecco alcuni suggerimenti per evitare risultati imprevisti:

  • Se si specifica un parametro contenente spazi vuoti, racchiuderlo tra virgolette.

  • In Bash o PowerShell le virgolette singole e doppie vengono interpretate correttamente. Nel prompt dei comandi di Windows vengono interpretate correttamente solo le virgolette doppie. Le virgolette singole vengono considerate come parte del valore.

  • Se il comando verrà eseguito solo in Bash (o Zsh), usare virgolette singole per mantenere il contenuto all'interno della stringa JSON. Le virgolette singole sono necessarie quando si specificano valori JSON inline. Ad esempio, questo codice JSON è corretto in Bash: '{"key": "value"}'.

  • Se il comando viene eseguito al prompt dei comandi di Windows, è necessario usare virgolette doppie. Se il valore contiene virgolette doppie, è necessario eseguirne l'escape. L'equivalente della stringa JSON precedente è "{\"key\": \"value\"}"

  • In PowerShell, se il valore è una stringa vuota, usare '""'.

  • In Bash o PowerShell, se il valore è una stringa ''di virgolette vuote, usare "''".

  • Usare la convenzione dell'interfaccia della riga di comando di @<file> Azure per caricare da un file e ignorare i meccanismi di interpretazione della shell.

    az ad app create --display-name myName --native-app --required-resource-accesses @manifest.json

  • Bash valuta le virgolette doppie nelle variabili esportate. Se questo comportamento non è quello desiderato, eseguire l'escape della variabile : "\$variable".

  • Alcuni comandi dell'interfaccia della riga di comando di Azure accettano un elenco di valori separati da spazi.

    • Se il nome o il valore della chiave contiene spazi, eseguire il wrapping dell'intera coppia: "my key=my value". Ad esempio:

      az web app config app settings set --resource-group myResourceGroup --name myWebAppName --settings "client id=id1" "my name=john"

    • Quando un parametro dell'interfaccia della riga di comando indica che accetta un elenco separato da spazi, è previsto uno dei due formati seguenti:

      1. Elenco senza virgoole, delimitato da spazi --parameterName firstValue secondValue
      2. Elenco delimitato da spazi delimitati da virgolette --parameterName "firstValue" "secondValue"

      Questo esempio è una stringa con uno spazio in esso contenuto. Non è un elenco separato da spazi: --parameterName "firstValue secondValue"

  • Esistono caratteri speciali di PowerShell, ad esempio in @. Per eseguire l'interfaccia della riga di comando di Azure in PowerShell, aggiungere ` prima del carattere speciale per eseguirne l'escape. È anche possibile racchiudere il valore tra virgolette "/"singole o doppie.

    # The following three examples will work in PowerShell
--parameterName `@parameters.json
--parameterName '@parameters.json'
--parameterName "@parameters.json"

# This example will not work in PowerShell
--parameterName @parameters.json

  • Quando si usa il --query parametro con un comando, alcuni caratteri di JMESPath devono essere preceduti da un carattere di escape nella shell.

    Questi tre comandi sono corretti ed equivalenti in Bash:

    az version --query '"azure-cli"'
az version --query \"azure-cli\"
az version --query "\"azure-cli\""

    Ecco due esempi di comandi non corretti in Bash:

    # Wrong, as the dash needs to be quoted in a JMESPath query
az version --query azure-cli
az version: error: argument --query: invalid jmespath_type value: 'azure-cli'

# Wrong, as the dash needs to be quoted in a JMESPath query, but quotes are interpreted by Bash
az version --query "azure-cli"
az version: error: argument --query: invalid jmespath_type value: 'azure-cli'

    Per altri confronti di esempio tra Bash, PowerShell e Cmd, vedere Eseguire query nell'output dei comandi dell'interfaccia della riga di comando di Azure

  • Il modo migliore per risolvere un problema di virgolette consiste nell'eseguire il comando con il --debug flag . Questo flag rivela gli argomenti effettivi ricevuti dall'interfaccia della riga di comando di Azure nella sintassi di Python.

    # Correct
$ az '{"key":"value"}' --debug
Command arguments: ['{"key":"value"}', '--debug']

# Correct
$ az "{\"key\":\"value\"}" --debug
Command arguments: ['{"key":"value"}', '--debug']

# Wrong, as quotes and spaces are interpreted by Bash
$ az {"key": "value"} --debug
Command arguments: ['{key:', 'value}', '--debug']

# Wrong, as quotes are interpreted by Bash
$ az {"key":"value"} --debug
Command arguments: ['{key:value}', '--debug']

Usare caratteri trattini nei parametri

Se il valore di un parametro inizia con un trattino, l'interfaccia della riga di comando di Azure tenta di analizzarla come nome di parametro. Per analizzarlo come valore, usare = per concatenare il nome e il valore del parametro: --password="-VerySecret".

Operazioni asincrone

Le operazioni in Azure possono richiedere una notevole quantità di tempo. Ad esempio, la configurazione di una macchina virtuale in un data center non è istantanea. L'interfaccia della riga di comando di Azure attende il completamento del comando per accettare altri comandi. Molti comandi offrono quindi un --no-wait parametro come illustrato di seguito:

az group delete --name MyResourceGroup --no-wait

Quando si elimina un gruppo di risorse, vengono rimosse anche tutte le risorse che appartengono. La rimozione di queste risorse può richiedere molto tempo. Quando si esegue il comando con il --no-wait parametro , la console accetta nuovi comandi senza interrompere la rimozione.

Molti comandi offrono un'opzione di attesa, sospendo la console fino a quando non viene soddisfatta una condizione. L'esempio seguente usa il comando az vm wait per supportare la creazione di risorse indipendenti in parallelo:

az vm create --resource-group VMResources --name virtual-machine-01 --image centos --no-wait
az vm create --resource-group VMResources --name virtual-machine-02 --image centos --no-wait

subscription=$(az account show --query "id" -o tsv)
vm1_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-01"
vm2_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-02"
az vm wait --created --ids $vm1_id $vm2_id

Dopo aver creato entrambi gli ID, è possibile usare di nuovo la console.

Uso di un proxy

Se si usa l'interfaccia della riga di comando di Azure su un server proxy che usa certificati autofirmato, la libreria delle richieste Python usata dall'interfaccia della riga di comando di Azure può causare l'errore seguente: SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",). Per risolvere questo errore, impostare la variabile REQUESTS_CA_BUNDLE di ambiente sul percorso del file di certificato del bundle CA in formato PEM.

Sistema operativo Bundle predefinito dell'autorità di certificazione
Windows a 32 bit C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem
Windows a 64 bit C:\Program Files\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem
Ubuntu/Debian Linux /opt/az/lib/python<version>/site-packages/certifi/cacert.pem
CentOS/RHEL/SU edizione Standard Linux /usr/lib64/az/lib/python<version>/site-packages/certifi/cacert.pem
macOS /usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem

Aggiungere il certificato del server proxy al file del certificato del bundle CA o copiare il contenuto in un altro file di certificato. REQUESTS_CA_BUNDLE Impostare quindi sul nuovo percorso del file. Ecco un esempio:

<Original cacert.pem>

-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----

Alcuni proxy richiedono l'autenticazione. Il formato delle variabili di HTTP_PROXY ambiente o HTTPS_PROXY deve includere l'autenticazione, ad esempio HTTPS_PROXY="https://username:password@proxy-server:port". Per informazioni dettagliate, vedere Come configurare i proxy per le librerie di Azure.

Esecuzione simultanea

Se si eseguono i comandi dell'interfaccia della riga di comando di Azure contemporaneamente nello stesso computer, è possibile che si verifichino conflitti di scrittura se più comandi dell'interfaccia della riga di comando di Azure scrivono nella stessa cache dei token MSAL.

Per evitare potenziali errori, è possibile isolare la cartella di configurazione dell'interfaccia della riga di comando di Azure per ogni script impostando la variabile AZURE_CONFIG_DIR di ambiente per ogni script in una directory separata. I comandi dell'interfaccia della riga di comando di Azure in tale script salvano la configurazione e la cache dei token nel percorso configurato anziché nella cartella predefinita ~/.azure .

export AZURE_CONFIG_DIR=/my/config/dir

Parametri di aggiornamento generici

I gruppi di comandi dell'interfaccia della riga di comando di Azure spesso includono un comando di aggiornamento. Ad esempio, Azure Macchine virtuali include il comando az vm update. La maggior parte dei comandi di aggiornamento offre i tre parametri generici: --add, --sete --remove.

I --set parametri e --add accettano un elenco di coppie chiave-valore separate da spazi: key1=value1 key2=value2. Per visualizzare le proprietà che è possibile aggiornare, usare un comando show, ad esempio az vm show.

az vm show --resource-group VMResources --name virtual-machine-01

Per semplificare il comando, prendere in considerazione l'uso di una stringa JSON. Ad esempio, per collegare un nuovo disco dati a una macchina virtuale, usare il valore seguente:

az vm update --resource-group VMResources --name virtual-machine-01 \
--add storageProfile.dataDisks "{\"createOption\": \"Attach\", \"managedDisk\":
   {\"id\":
   \"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/yg/providers/Microsoft.Compute/disks/yg-disk\"},
   \"lun\": 1}"

Comandi di risorsa generici (az resource)

Un servizio che si vuole usare potrebbe non avere il supporto dell'interfaccia della riga di comando di Azure. È possibile usare i comandi az resource per usare queste risorse.

Se sono necessari solo comandi di creazione o aggiornamento, usare il comando az deployment group create. Per esempi di lavoro, vedere Modelli di avvio rapido di Azure.

Comandi dell'API REST (az rest)

Se i parametri di aggiornamento generico e az resource non soddisfano le proprie esigenze, è possibile usare il comando az rest per chiamare l'API REST. Il comando esegue automaticamente l'autenticazione usando le credenziali registrate e imposta l'intestazione Content-Type: application/json. Per altre informazioni, vedere Informazioni di riferimento sull'API REST di Azure.

Questo esempio funziona con l'API Microsoft Graph. Per aggiornare gli URI di reindirizzamento per un'applicazione, chiamare l'API REST dell'applicazione Di aggiornamento, come nel codice seguente:

# Get the application
az rest --method GET \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001'

# Update `redirectUris` for `web` property
az rest --method PATCH \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001' \
    --body '{"web":{"redirectUris":["https://myapp.com"]}}'

Quando si usa --uri-parameters per le richieste sotto forma di OData, assicurarsi di eseguire l'escape $ in ambienti diversi: in Bash, escape $ come \$ e in PowerShell, escape $ come `$

Script di esempio

Di seguito sono riportati esempi per l'uso di variabili e il ciclo di un elenco quando si usa Azure Macchine virtuali. Per esempi approfonditi sull'uso di costrutti Bash con l'interfaccia della riga di comando di Azure, inclusi cicli, istruzioni case, if.. Poi.. altrimenti e la gestione degli errori, vedere Informazioni sull'uso di Bash con l'interfaccia della riga di comando di Azure.

Usare questi script per salvare gli ID nelle variabili:

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
   `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    SET "vm_ids=%%F %vm_ids%"  :: construct the id list
)
az vm stop --ids %vm_ids% :: CLI stops all VMs in parallel

Usare questi script per scorrere un elenco:

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
    `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    ECHO Stopping %%F
    az vm stop --ids %%F
)

Vedi anche