Solução de problemas da CLI do Azure

Categorias de erro

A maioria dos erros retornados pela CLI do Azure se enquadra em uma destas categorias:

O --debug parâmetro

Uma das melhores maneiras de ver o que a CLI do Azure está executando para cada comando de referência da CLI do Azure é usar o --debug parâmetro. Veja exemplos de --debug um comando com falha e bem-sucedido:

# 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

Aqui está uma parte da saída de depuração. Observe o local do log e o argumento não reconhecido.

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

Compare a saída de erro --debug dada acima com uma execução bem-sucedida:

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

Aqui está uma parte da saída de depuração. Observe o local do log, a chamada da API e o tempo de execução.

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)

Para obter exemplos de formatação JSON, consulte Citando diferenças entre linguagens de script - cadeias de --debug caracteres JSON.

Erros comuns de sintaxe

Embora a CLI do Azure possa ser executada em Bash, PowerShell e Windows Cmd, há diferenças de sintaxe entre linguagens de script. Os scripts da CLI do Azure contendo aspas simples, aspas duplas e caracteres de escape geralmente devem ser modificados quando copiados entre idiomas. Este desafio revela-se mais frequentemente em valores de parâmetros, especialmente em valores atribuídos ao --query parâmetro. Aqui estão algumas mensagens de erro comuns:

• "Mau pedido... {algo} é inválido" pode ser causado por um espaço, aspas simples ou duplas, ou falta de aspas.

• "Token inesperado..." é visto quando há um espaço extra ou citação.

• O erro "Valor de jmespath_type inválido" geralmente vem de citações incorretas no --query parâmetro.

• "A referência de variável não é válida" é recebida quando uma cadeia de caracteres não é formatada corretamente, muitas vezes devido a concatenação ou a um caractere de escape ausente.

• "Argumentos não reconhecidos" geralmente são causados por um caractere de continuação de linha incorreto ou nome de parâmetro com erros ortográficos.

• "Expressão ausente após operador unário" é visto quando um caractere de continuação de linha está ausente.

Há vários artigos da CLI do Azure dedicados a explicar erros de sintaxe e fornecer exemplos de trabalho:

• Citando diferenças entre linguagens de script
• Diferenças de sintaxe no tutorial Bash, PowerShell e Cmd
• Encontre muitos --query exemplos de parâmetros em Como consultar a saída do comando CLI do Azure usando uma consulta JMESPath
• Como usar a CLI do Azure em uma linguagem de script Bash
• Considerações para executar a CLI do Azure em uma linguagem de script do PowerShell

Erro: Valor inválido ou não existe

Esses erros geralmente ocorrem ao tentar usar um valor de variável que contém um formato incorreto. A saída padrão para a CLI do Azure é JSON, portanto, se você estiver tentando armazenar uma ID para um recurso do Azure em uma variável, deverá especificar --output tsv. Eis um exemplo:

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

Agora use o tipo de tsv saída.

# 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

Erro: Os argumentos são esperados ou necessários

Você recebe esse erro quando um comando da CLI do Azure está faltando um parâmetro necessário ou há um erro tipográfico que faz com que a CLI do Azure analise incorretamente o comando de referência. Ao trabalhar com um script, você também recebe esse erro quando uma ou mais condições forem verdadeiras:

• Um caractere de continuação de linha está ausente ou incorreto.
• Existe um espaço à direita no lado direito de um caractere de continuação de linha ao trabalhar na linguagem de script do PowerShell. No momento, não há suporte para splatting com comandos da CLI do Azure.
• Um nome de variável contém um caractere especial, como um traço (-).

Erro: Recurso não encontrado

Quando a CLI do Azure não consegue encontrar o nome do recurso ou a ID passada em um valor de parâmetro, geralmente é devido a um destes motivos:

• O nome ou ID do recurso está escrito incorretamente.
• O nome do recurso contém caracteres especiais e não está rodeado por aspas simples ou duplas.
• O valor que está sendo passado para uma variável tem espaços à esquerda ou à direita invisíveis.
• O recurso existe, mas está em uma assinatura diferente.

Erro: Falha ao analisar a cadeia de caracteres como JSON

Há diferenças entre Bash, PowerShell no Linux e PowerShell no Windows. Além disso, versões diferentes do PowerShell podem produzir resultados diferentes. Para parâmetros complexos, como uma cadeia de caracteres JSON, a prática recomendada é usar a convenção da CLI do @<file> Azure para ignorar a interpretação de um shell. Para obter mais informações, consulte um destes artigos:

Para obter exemplos de sintaxe JSON para Bash, PowerShell e Cmd.exe, consulte Citando diferenças entre linguagens de script - tutorial de cadeias de caracteres JSON.

Erro: InvalidTemplateDeployment

Quando você tenta criar um recurso do Azure em um local que não oferece esse recurso, você recebe um erro semelhante a esta mensagem: "As seguintes SKUs falharam para restrições de capacidade: myDesiredSkuName' não está disponível no momento no local 'mySpecifiedLocation'."

Aqui está um exemplo de erro completo para uma VM que não pode ser criada no westus local:

{"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."}]}}

A solução é alterar uma propriedade do recurso do Azure solicitado ou tentar um local diferente.

Erro: Subscrição não encontrada

Supondo que você não tenha digitado incorretamente um nome ou ID de assinatura, esse erro ocorre quando um provedor de recursos não está registrado na assinatura ativa. Por exemplo, se você quiser executar az storage account create, o Microsoft.Storage provedor deve estar registrado. Para registrar um provedor de recursos, consulte Tipos e provedores de recursos do Azure.

Erro: Aperto de mão ruim... falha na verificação do certificado

Consulte Trabalhar atrás de um proxy para obter informações sobre como resolver esse erro.

Trabalhar atrás de um proxy

Se você estiver usando a CLI do Azure em um servidor proxy que usa certificados autoassinados, a biblioteca de solicitações Python usada pela CLI do Azure pode causar o seguinte erro: SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",). Para resolver esse erro, defina a variável REQUESTS_CA_BUNDLE de ambiente como o caminho do arquivo de certificado do pacote da autoridade de certificação no formato PEM.

Anexe o certificado do servidor proxy ao arquivo de certificado do pacote da autoridade de certificação ou copie o conteúdo para outro arquivo de certificado. Em seguida, defina REQUESTS_CA_BUNDLE para o novo local do arquivo. Eis um exemplo:

<Original cacert.pem>

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

Alguns proxies requerem autenticação. O formato das HTTP_PROXY variáveis ou HTTPS_PROXY de ambiente deve incluir a autenticação, como HTTPS_PROXY="https://username:password@proxy-server:port". Para obter detalhes, consulte Como configurar proxies para o SDK do Azure para Python.

Principais de serviço

Para obter informações sobre como solucionar problemas de entidades de serviço, consulte Limpeza e solução de problemas no tutorial Trabalhar com entidades de serviço.

Outros problemas

Se você tiver um problema de produto com a CLI do Azure não listada neste artigo, registre um problema no GitHub.

Consulte também

• Sugestões para utilizar a CLI do Azure com sucesso