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:
| Categoria do erro | Causa geral do erro |
|---|---|
| Argumento não reconhecido | Um parâmetro está escrito incorretamente ou não existe. |
| Argumento necessário ausente | Um parâmetro necessário não é especificado ou apenas um dos dois "pares de parâmetros" é especificado. Um parâmetro também pode estar incorreto. |
| Argumento mutuamente exclusivo | Dois ou mais parâmetros não podem ser especificados juntos. |
| Valor de argumento inválido | O valor do parâmetro não é válido. Este erro é muitas vezes devido a citação, um caractere de escape ou espaçamento. |
| Solicitação incorreta | Um código de status HTTP de 400 retorna esse erro. Verifique se há espaço ausente, traço de parâmetro ausente ou aspas simples ou duplas extras ou ausentes. Esse erro também acontece quando um valor de parâmetro não contém um valor permitido. |
| Recurso não encontrado | Não é possível encontrar um recurso do Azure referenciado em um valor de parâmetro. |
| Autenticação | Falha na autenticação do Microsoft Entra. |
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 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 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 no 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 mais frequentemente em valores de parâmetros, especialmente em valores atribuídos ao --query parâmetro. Aqui estão algumas mensagens de erro comuns:
"Pedido ruim... {algo} é inválido" pode ser causado por um espaço, aspas simples ou duplas, ou falta de uma citação.
"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
--queryparâmetro."A referência de variável não é válida" é recebida quando uma cadeia de caracteres não é formatada corretamente, muitas vezes devido à concatenação ou a um caractere de escape ausente.
"Argumentos não reconhecidos" geralmente é causado por um caractere de continuação de linha incorreto ou nome de parâmetro escrito incorretamente.
"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
- Tutorial de diferenças de sintaxe no Bash, PowerShell e Cmd
- Encontre muitos
--queryexemplos de parâmetros em Como consultar a saída do 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
Dica
Se você não conseguir resolver um erro de comando, tente usar uma linguagem de script diferente. A maioria da documentação da CLI do Azure é escrita e testada no Azure Cloud Shell (ACS) com uma linguagem de script Bash. Se você puder obter um exemplo de artigo para executar no ACS Bash, mas ele não for executado no Windows PowerShell, revise o uso de aspas simples e duplas e escape characters.
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 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 tsv tipo de 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, a distribuição não é suportada com os 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 ID do recurso está escrito incorretamente.
- O nome do recurso contém caracteres especiais e não é 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 o Bash, o PowerShell no Linux e o 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 prática recomendada é usar a convenção da CLI @<file> 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 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: SSLError "handshake ruim... falha na verificação do certificado" (Proxy bloqueia a conexão)
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 de ambiente REQUESTS_CA_BUNDLE como o caminho do arquivo de certificado do pacote da AC no formato PEM.
| Sistema operacional | Pacote da autoridade de certificação padrão |
|---|---|
| Windows 32 bits | C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem |
| Windows 64 bits | C:\Program Files\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem |
| Ubuntu/Debian do 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 | /usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem |
Acrescente o certificado do servidor proxy a esse arquivo de certificado de pacote da AC ou copie o conteúdo em outro arquivo de certificado. Depois, defina REQUESTS_CA_BUNDLE como o novo local do arquivo. Veja um exemplo:
<Original cacert.pem>
-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----
Alguns proxies exigem a 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.
Erro: Assinatura não encontrada
Supondo que você não tenha digitado 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ê deseja executar az storage account create, o Microsoft.Storage provedor deve ser registrado. Para registrar um provedor de recursos, consulte Provedores e tipos de recursos do Azure.
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 listado neste artigo, registre um problema no GitHub.
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de