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 é usar o --debug parâmetro. Aqui estão exemplos de um --debug de 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. Preste atenção ao local do log e ao 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 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 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 --debug para formatação JSON, consulte Citando diferenças entre linguagens de script - cadeias de caracteres JSON.

Erros comuns de sintaxe

Embora a CLI do Azure possa ser executada em Bash, 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 contendo aspas simples, aspas duplas e caracteres de escape geralmente exigem modificação quando copiados entre idiomas. Este desafio é mais frequentemente revelado em valores de parâmetros, particularmente naqueles atribuídos ao --query parâmetro. Aqui estão algumas mensagens de erro comuns:

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

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

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

• A referência de variável não é válida: este erro é recebido quando uma cadeia de caracteres não está formatada corretamente, geralmente devido a concatenação ou a um caractere de escape ausente.

• Argumentos não reconhecidos: Este erro geralmente é causado 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: Este erro é visto quando um caractere de continuação de linha está faltando.

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 em Bash, PowerShell e Cmd no tutorial
• Encontre muitos exemplos de parâmetros --query em como consultar a saída de comandos do Azure CLI 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 autenticação multifator (MFA)

Falhas de login interativo

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 do Microsoft Entra ID que requer autenticação multifator (MFA).

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

O recurso não foi permitido pela política

Poderá ver um dos seguintes erros ao utilizar:

• Azure CLI 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 mensagens de erro mais informativas e detalhes da política:

• Azure CLI versão 2.76.0 ou posterior

O seguinte erro ocorre na CLI do Azure 2.76.0+, onde 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 no início de sessão. Isso permite que sua sessão atenda aos requisitos de Acesso Condicional sem etapas adicionais.

• Se a imposição de MFA no início de sessão não for possível, utilize 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 Planejando a autenticação multifator obrigatória para o Azure e outros portais de administração

Falha no carregamento da DLL ao importar o win32file

Você pode enfrentar o seguinte erro ao tentar usar a CLI do Azure:

DLL load failed while importing win32file: The specified module could not be found.
The command failed with an unexpected error. Here is the traceback:
DLL load failed while importing win32file: The specified module could not be found.
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/__main__.py", line 13, in <module>
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/core/telemetry.py", line 19, in <module>
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/telemetry/__init__.py", line 9, in <module>
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\portalocker/__init__.py", line 4, in <module>
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\portalocker/portalocker.py", line 11, in <module>
ImportError: DLL load failed while importing win32file: The specified module could not be found.
PS C:\Users\dsevilla>

Esse problema pode ocorrer devido a uma instalação corrompida. Para resolver o problema:

1. Desinstale a CLI do Azure.
2. Reinstale a CLI do Azure usando seu método de instalação preferido.

Para obter mais informações, consulte a edição #32045 do GitHub.

Erro: Valor inválido ou não existe

Esses erros geralmente ocorrem ao tentar usar valores de 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. Aqui está 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: 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 de um caractere de continuação de linha ao trabalhar na linguagem de script do PowerShell. Splatting no PowerShell é suportado apenas com matrizes e não com tabelas de hash ao usar 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

Existem diferenças de citação 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 mais recomendada é usar a convenção da CLI Azure para contornar a interpretação do 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 digitou o nome ou ID da assinatura 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 deve estar registrado. Para registrar um provedor de recursos, consulte Tipos e provedores de recursos do Azure.

Erro: Falha na verificação do certificado de handshake

Consulte Trabalhar atrás de um proxy para obter informações sobre a resolução deste erro.

Trabalhar atravé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 de 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 este erro, defina a variável de ambiente REQUESTS_CA_BUNDLE com o caminho do ficheiro de certificado de conjunto CA no formato PEM.

Anexe o certificado do servidor proxy ao ficheiro do conjunto de certificados da autoridade de certificação ou copie o conteúdo para outro ficheiro de certificado. Em seguida, defina REQUESTS_CA_BUNDLE para o novo local do arquivo. Aqui está um exemplo:

<Original cacert.pem>

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

Alguns proxies requerem 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.

Outras questões

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

Ver também

• Dicas para usar a CLI do Azure com êxito