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 de depuração

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

# 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 no exemplo anterior 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 no Bash, no PowerShell e no Prompt de Comando do Windows (cmd.exe), 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 exigem modificação quando copiados entre idiomas. Esse desafio geralmente é revelado em valores de parâmetro, especialmente naqueles atribuídos ao --query parâmetro. Aqui estão algumas mensagens de erro comuns:

• Solicitação incorreta... {something} é inválido: esse erro pode ser causado por um espaço, uma aspa única, uma aspa dupla ou pela falta de uma aspa.

• Token inesperado...: esse erro ocorre quando há um espaço extra ou aspas excessivas.

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

• A referência de variável não é válida: esse erro é recebido 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: esse erro geralmente é causado por um caractere de continuação de linha incorreto ou nome de parâmetro com ortografia incorreta.

• Expressão ausente após operador unário: esse erro é 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:

• 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

Solução de problemas de MFA (autenticação multifator)

Falhas de logon interativas

Se você encontrar erros ao executar comandos da CLI do Azure que criam, modificam ou excluem recursos, o problema pode ser causado por uma política de Acesso Condicional da ID do Microsoft Entra que requer autenticação multifator (MFA).

Esses erros normalmente ocorrem quando a MFA é exigida pela política, mas não é imposta durante o logon.

O recurso não foi permitido pela política

Você pode ver um dos seguintes erros ao usar:

• CLI do Azure versão 2.75.0 ou anterior

Due to a configuration change made by your administrator, or because you moved to a new ___location,
you must enroll in multi-factor authentication. Interactive authentication is needed.

Ou:

Resource was disallowed by policy. Reasons: MFA is required. See error details for policy resource
IDs. RequestDisallowedByPolicy Message: Resource policy resource IDs was disallowed by policy.
Reasons: MFA is required.

Ou:

Unauthorized. RequestDisallowedByPolicy. Resource was disallowed by policy. Reasons: MFA is
required. See error details for policy resource IDs. MFA is required. Users must authenticate with
multi-factor authentication to create or update resources.

Atualize para as seguintes versões ou posteriores para receber mais mensagens de erro informativas e detalhes da política:

• CLI do Azure versão 2.76.0 ou posterior

O erro a seguir ocorre na CLI do Azure 2.76.0+, em que a MFA é exigida pelo Acesso Condicional para operações específicas.

Run the command below to authenticate interactively; additional arguments may be added as needed:
az logout 
az login --tenant "aaaabbbb-0000-cccc-1111-dddd2222eeee" --scope "https://management.core.windows.net//.default" --claims-challenge "<claims-challenge-token>"

(RequestDisallowedByPolicy) Resource was disallowed by policy. Policy identifiers. Users must use
MFA for Create/Update operations. Users must authenticate with multi-factor authentication to create
or update resources. Users must use MFA for Create operation. Users must authenticate with
multi-factor authentication to create or update resources. Users must use MFA for Create/Update
operations. Users must authenticate with multi-factor authentication to create or update resources.
Users must use MFA for Create operation. Users must authenticate with multi-factor authentication to
create or update resources.

Opções de resolução

• Peça ao administrador do Azure para impor a MFA na entrada. Isso permite que sua sessão atenda aos requisitos de Acesso Condicional sem etapas adicionais.

• Se a imposição de MFA na entrada não for possível, use o --claims-challenge parâmetro para autenticar interativamente:

  az logout
  az login --tenant "aaaabbbb-0000-cccc-1111-dddd2222eeee" --scope "https://management.core.windows.net//.default" --claims-challenge "<claims-challenge-token>"
  

Para obter mais informações, consulte Planning for mandatory multifactor authentication for Azure and other admin portals

Erro: valor inválido ou não existe

Esses erros geralmente ocorrem ao tentar usar valores variáveis que contêm um formato incorreto. A saída padrão para a CLI do Azure é JSON. 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. O splatting do PowerShell só tem suporte com arrays e não com hash tables nos comandos da Azure CLI.
• 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 string JSON, a melhor prática é usar a convenção da CLI do Azure para contornar a interpretação do shell. Para obter mais informações, consulte um destes artigos:

Para exemplos de sintaxe JSON para Bash, PowerShell e cmd.exe, consulte o tutorial Diferenças de citação entre linguagens de script — cadeias de caracteres JSON.

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 o nome da assinatura ou a ID incorretamente, 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: Falha na verificação do certificado de handshake incorreto

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