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 parâmetro --debug

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 parâmetro --debug. Aqui estão exemplos de --debug para um comando com falha e um comando 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 o erro --debug saída fornecida 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 à 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 --debug para formatação JSON, consulte Diferenças de cotação entre linguagens de script – cadeias de 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 que contêm aspas simples, aspas duplas e caracteres de escape geralmente devem ser modificados quando copiados entre idiomas. Esse desafio se revela com mais frequência em valores de parâmetro, especialmente em valores atribuídos ao parâmetro --query. Aqui estão algumas mensagens de erro comuns:

• "Solicitação incorreta... {something} é inválido" pode ser provocado por um espaço, uma aspa simples ou dupla, ou pela ausência de uma aspa.

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

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

• "Referência de variável não é válida" é exibida quando uma string não é formatada corretamente, geralmente devido à concatenação ou à ausência de um caractere de escape.

• "argumentos não reconhecidos" geralmente é causado por um caractere de continuação de linha incorreto ou nome de parâmetro com ortografia incorreta.

• "A mensagem de erro'Expressão ausente após o operador unário' é exibida 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:

• Diferenças de aspas entre linguagens de script
• Diferenças de sintaxe no Bash, PowerShell e Cmd tutorial
• Encontre muitos exemplos de parâmetro --query em como consultar a saída de comando da 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 variável que contém um formato incorreto. A saída padrão da 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. Veja 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 saída 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

Erro: argumentos são esperados ou necessários

Você recebe esse erro quando um comando da CLI do Azure não tem 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 são verdadeiras:

• Um caractere de continuação de linha está ausente ou incorreto.
• Existe um espaço à direita de um caractere de continuação de linha ao trabalhar na linguagem de script do PowerShell. Atualmente, o splatting de não é suportado 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 localizar o nome do recurso ou a ID passada em um valor de parâmetro, geralmente é devido a um destes motivos:

• O nome ou a ID do recurso está escrito incorretamente.
• O nome do recurso contém caracteres especiais e não está cercado 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, diferentes versões do PowerShell podem produzir resultados diferentes. Para parâmetros complexos, como uma cadeia de caracteres JSON, a melhor prática é usar a convenção de @<file> da CLI do 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 Aspas entre linguagens de script – cadeias de caracteres JSON tutorial.

Erro: InvalidTemplateDeployment

Quando você tenta criar um recurso do Azure em um local que não oferece esse recurso, recebe um erro semelhante a esta mensagem: "As SEGUINTEs SKUs falharam em restrições de capacidade: myDesiredSkuName" não está disponível 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: assinatura não encontrada

Supondo que você não digitou incorretamente um nome de assinatura ou ID, 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 provedor de Microsoft.Storage deverá ser registrado. Para registrar um provedor de recursos, consulte provedores de recursos e tipos do Azure.

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

Consulte Trabalhar com um proxy para obter informações sobre como resolver esse erro.

Trabalhar por trá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 do Python usada pela CLI do Azure poderá 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 de ambiente REQUESTS_CA_BUNDLE para o caminho do arquivo de certificado do pacote de AC no formato PEM.

Acrescente o certificado do servidor proxy ao arquivo de certificado do pacote de AC ou copie o conteúdo para outro arquivo de certificado. Em seguida, defina REQUESTS_CA_BUNDLE para o novo local do arquivo. Veja um exemplo:

<Original cacert.pem>

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

Alguns proxies exigem autenticação. O formato das variáveis de ambiente HTTP_PROXY ou HTTPS_PROXY 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.

Entidades 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, arquive um problema no GitHub.

Consulte também

• Dicas para usar a CLI do Azure com êxito