Condividi tramite

Risoluzione dei problemi dell'interfaccia della riga di comando di Azure (CLI)

  • Articolo

Categorie di errore

La maggior parte degli errori restituiti dall'interfaccia della riga di comando di Azure rientra in una di queste categorie:

Categoria di errore Causa generale dell'errore
Argomento non riconosciuto Un parametro è scritto in modo errato o non esiste.
argomento obbligatorio mancante Un parametro obbligatorio non è specificato o viene specificata solo una delle due "coppie di parametri". Un parametro potrebbe anche essere scritto male.
Argomento che si esclude a vicenda Non è possibile specificare due o più parametri insieme.
valore dell'argomento non valido Il valore del parametro non è valido. Questo errore è spesso dovuto alle virgolette, a un carattere di escape o a spaziatura.
Richiesta non valida Un codice di stato HTTP 400 restituisce questo errore. Verificare la presenza di uno spazio mancante, di un trattino di parametro mancante o di una virgoletta singola o doppia in eccesso o mancante. Questo errore si verifica anche quando un valore di parametro non contiene un valore consentito.
risorsa non trovata Non è possibile trovare una risorsa di Azure a cui si fa riferimento in un valore di parametro.
Autenticazione Autenticazione di Microsoft Entra non riuscita.

Parametro --debug

Uno dei modi migliori per vedere cosa esegue Azure CLI per ogni comando specifico è usare il parametro --debug. Ecco alcuni esempi di --debug per un comando non riuscito e uno riuscito:

# Error example: Create a resource group, but omit the quotes around the resource group name.
az group create --location eastus2 --name msdocs-rg-test --debug

Ecco una parte dell'output di debug. Si noti il percorso del log e l'argomento non riconosciuto.

cli.knack.cli: Command arguments: ['group', 'create', '-l', 'eastus2', '-name', 'msdocs-rg-test', '--debug']
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/YYYY-MM-DD.HH-MM-SS.group_create.8912.log'.
...
cli.azure.cli.core.azclierror: unrecognized arguments: msdocs-rg-test
...

Confrontare l'errore --debug output indicato in precedenza con un'esecuzione riuscita:

# Correct example: Because the resource group name contains special characters, enclose it in quotes
az group create --location eastus2 --name "msdocs-rg-test" --debug

Ecco una parte dell'output di debug. Si noti il percorso del log, la chiamata API e il tempo di esecuzione.

cli.knack.cli: Command arguments: ['group', 'create', '-l', 'eastus2', '-n', 'msdocs-rg-test', '--debug']
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/YYYY-MM-DD.HH-MM-SS.group_create.8912.log'.
...
cli.azure.cli.core.sdk.policies: Request URL: 'https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/msdocs-rg-test?api-version=YYYY-MM-DD'
cli.azure.cli.core.sdk.policies: Request method: 'PUT'
cli.azure.cli.core.sdk.policies: Request headers:
cli.azure.cli.core.sdk.policies:     'Content-Type': 'application/json'
cli.azure.cli.core.sdk.policies:     'Content-Length': '23'
cli.azure.cli.core.sdk.policies:     'Accept': 'application/json'
cli.azure.cli.core.sdk.policies:     'x-ms-client-request-id': 'ba7ee6f4-2dcc-11ef-81ce-00155dadc5c8'
cli.azure.cli.core.sdk.policies:     'CommandName': 'group create'
cli.azure.cli.core.sdk.policies:     'ParameterSetName': '-l -n --debug'
cli.azure.cli.core.sdk.policies:     'User-Agent': 'AZURECLI/2.61.0 (RPM) azsdk-python-core/1.28.0 Python/3.9.19 (Linux-5.10.102.2-microsoft-standard-x86_64-with-glibc2.35) cloud-shell/1.0'
cli.azure.cli.core.sdk.policies:     'Authorization': '*****'
cli.azure.cli.core.sdk.policies: Request body:
cli.azure.cli.core.sdk.policies: {"location": "eastus2"}
urllib3.connectionpool: Starting new HTTPS connection (1): management.azure.com:443
urllib3.connectionpool: https://management.azure.com:443 "PUT /subscriptions/3618afcd-ea52-4ceb-bb46-53bb962d4e0b/resourcegroups/msdocs-rg-test?api-version=2022-09-01 HTTP/1.1" 201 226
cli.azure.cli.core.sdk.policies: Response status: 201
...
cli.azure.cli.core.sdk.policies:     'Date': 'Tue, 18 Jun 2024 23:44:41 GMT'
cli.azure.cli.core.sdk.policies: Response content:
cli.azure.cli.core.sdk.policies: {"id":"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-rg-test","name":"msdocs-rg-test","type":"Microsoft.Resources/resourceGroups","location":"eastus2","properties":{"provisioningState":"Succeeded"}}
...
cli.__main__: Command ran in 1.829 seconds (init: 0.111, invoke: 1.718)

Per esempi di formattazione JSON con --debug, vedere differenze di citazioni tra i linguaggi di scripting - stringhe JSON.

Errori di sintassi comuni

Anche se l'interfaccia della riga di comando di Azure può essere eseguita in Bash, PowerShell e Windows Cmd, esistono differenze di sintassi tra i linguaggi di scripting. Gli script dell'interfaccia della riga di comando di Azure contenenti virgolette singole, virgolette doppie e caratteri di escape devono in genere essere modificati quando vengono copiati tra le lingue. Questa sfida si rivela più spesso nei valori dei parametri, soprattutto nei valori assegnati al parametro --query. Ecco alcuni messaggi di errore comuni:

  • "richiesta non valida ... {something} non è valido" potrebbe essere causato da uno spazio, da virgolette singole o doppie o da una mancanza di virgolette.

  • "token imprevisto..." viene visualizzato quando è presente uno spazio o una virgoletta aggiuntiva.

  • "Errore: valore di jmespath_type non valido" spesso deriva da virgolette non corrette nel parametro --query.

  • "Riferimento variabile non è valido" viene ricevuto quando una stringa non è formattata correttamente spesso a causa della concatenazione o di un carattere di escape mancante.

  • "Argomenti non riconosciuti" è spesso causato da un carattere di continuazione di riga errato o da un nome di parametro sbagliato.

  • "Espressione mancante dopo l'operatore unario" viene visualizzato quando manca un carattere di continuazione di riga.

Sono disponibili diversi articoli di Azure CLI dedicati alla spiegazione degli errori di sintassi e alla fornitura di esempi pratici:

Mancia

Se non è possibile risolvere un errore di comando, provare a usare un linguaggio di scripting diverso. La maggior parte della documentazione di Azure CLI è scritta e testata in Azure Cloud Shell (ACS) nel linguaggio di scripting Bash. Se riesci a far eseguire un esempio di articolo in ACS Bash, ma questo non viene eseguito in Windows PowerShell, esamina l'uso delle virgolette singole e doppie e dei caratteri di escape.

Errore: Valore non valido o non esistente

Questi errori si verificano spesso quando si tenta di usare un valore di variabile che contiene un formato non corretto. L'output predefinito per l'interfaccia della riga di comando di Azure è JSON, quindi se si sta tentando di archiviare un ID per una risorsa di Azure in una variabile, è necessario specificare --output tsv. Ecco un esempio:

# Get a subscription that contains a name or phrase
subscriptionID=$(az account list --query "[?contains(name,'my case sensitive search phrase')].id")
echo $subscriptionID

# output as JSON
[ "00000000-0000-0000-0000-000000000000" ]

# Try to set your subscription to the new ID
az account set --subscription $subscriptionID

# error output
The subscription of '"00000000-0000-0000-0000-000000000000"' doesn't exist in cloud 'AzureCloud'.

Ora usa il tipo di output tsv.

# Get the active subscription
subscriptionID=$(az account list --query "[?contains(name,'my case sensitive search phrase')].id" --output tsv)
echo $subscriptionID

# output as TSV
00000000-0000-0000-0000-000000000000

# Successfully set your subscription to the new ID
az account set --subscription $subscriptionID

Errore: gli argomenti sono previsti o obbligatori

Questo errore viene visualizzato quando a un comando dell'interfaccia della riga di comando di Azure manca un parametro obbligatorio, oppure si verifica un errore tipografico che provoca un'interpretazione errata del comando di riferimento. Quando si usa uno script, questo errore viene visualizzato anche quando una o più condizioni sono vere:

  • Carattere di continuazione di riga mancante o errato.
  • Esiste uno spazio finale sul lato destro di un carattere di continuazione di riga quando si lavora nel linguaggio di scripting di PowerShell. Al momento, lo splatting di non è supportato con i comandi Azure CLI.
  • Un nome di variabile contiene un carattere speciale, ad esempio un trattino (-).

Errore: Risorsa non trovata

Quando l'interfaccia della riga di comando di Azure non riesce a trovare il nome o l'ID della risorsa passato in un valore di parametro, è in genere dovuto a uno dei motivi seguenti:

  • Il nome o l'ID della risorsa viene digitato in modo non corretto.
  • Il nome della risorsa contiene caratteri speciali e non è racchiuso tra virgolette singole o doppie.
  • Il valore passato a una variabile ha spazi invisibili all'inizio o alla fine.
  • La risorsa esiste, ma si trova in una sottoscrizione diversa.

Errore: Impossibile analizzare la stringa come JSON

Esistono differenze tra Bash, PowerShell in Linux e PowerShell in Windows. Inoltre, versioni diverse di PowerShell possono produrre risultati diversi. Per i parametri complessi, ad esempio una stringa JSON, la procedura consigliata consiste nell'usare la convenzione di @<file> dell'interfaccia della riga di comando di Azure per ignorare l'interpretazione di una shell. Per altre informazioni, vedere uno di questi articoli:

Per esempi di sintassi JSON per Bash, PowerShell e Cmd.exe, consultare la guida sulle differenze tra linguaggi di scripting - esercitazione sulle stringhe JSON.

Errore: InvalidTemplateDeployment

Quando si tenta di creare una risorsa di Azure in un percorso che non offre tale risorsa, viene visualizzato un errore simile al seguente: "Gli SKU seguenti non sono riusciti per restrizioni di capacità: myDesiredSkuName" non è attualmente disponibile nel percorso "mySpecifiedLocation".

Ecco un esempio di errore completo per una macchina virtuale che non può essere creata nella posizione westus.

{"error":{"code":"InvalidTemplateDeployment","message":"The template deployment 'vm_deploy_<32 character ID>'
is not valid according to the validation procedure. The tracking id is '<36 character ID>'.
See inner errors for details.","details":[{"code":"SkuNotAvailable","message":"The requested VM size for resource
'Following SKUs have failed for Capacity Restrictions: Standard_DS1_v2' is currently not available
in location 'westus'. Please try another size or deploy to a different location
or different zone. See https://aka.ms/azureskunotavailable for details."}]}}

La soluzione consiste nel modificare una proprietà della risorsa di Azure richiesta o provare un'ubicazione diversa.

Errore: Sottoscrizione non trovata

Supponendo che non sia stato digitato in modo errato un nome o un ID sottoscrizione, questo errore si verifica quando un provider di risorse non è registrato nella sottoscrizione attiva. Ad esempio, se si vuole eseguire az storage account create, è necessario registrare il provider Microsoft.Storage. Per registrare un provider di risorse, vedere i provider di risorse e i tipi di Azure.

Errore: Handshake non valido... verifica del certificato non riuscita

Per informazioni su come risolvere questo errore, vedere Work behind a proxy.

Lavorare dietro 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 di Python usata dall'interfaccia della riga di comando di Azure potrebbe causare l'errore seguente: SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",). Per risolvere questo errore, impostare la variabile di ambiente REQUESTS_CA_BUNDLE sul percorso del file del 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 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 Stream/RHEL/SUSE Linux /usr/lib64/az/lib/python<version>/site-packages/certifi/cacert.pem
macOS Modelli Intel: /usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem

Modelli di silicio: /opt/homebrew/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. Impostare quindi REQUESTS_CA_BUNDLE 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 ambiente HTTP_PROXY 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 Azure SDK per Python.

Principali del servizio

Per informazioni sulla risoluzione dei problemi delle entità servizio, vedere Cleanup and Troubleshooting nell'esercitazione Usare le entità servizio.

Altri problemi

Se riscontri un problema con Azure CLI non elencato in questo articolo, segnalalo su GitHub.

Vedere anche