Dicas para usar a CLI do Azure com êxito

5 minutos

Neste módulo, você aprendeu a escolher um ambiente, instalar a CLI do Azure, executar comandos da CLI do Azure interativamente e criar um script Bash . Vamos levar nosso aprendizado um passo adiante e nos concentrar em como usar a CLI do Azure com êxito. Esta unidade ensina como a CLI do Azure funciona por trás da linha de comando e fornece dicas para solução de problemas.

Sugestão

Este módulo é um curso de nível avançado e esta unidade leva você a se aprofundar na CLI do Azure. Se você é novo na programação de linha de comando, concentre-se nos conceitos. Os detalhes tornam-se mais fáceis de entender à medida que você ganha experiência. Não desista!

Compreender as chamadas da API da CLI do Azure

Por trás da interface gráfica do portal do Azure e da linha de comando do Azure CLI, acontecem chamadas de API. Você pode expor as chamadas de APIda CLI do Azure usando o --debug parâmetro. Veja o que acontece quando você cria um novo grupo de recursos:

az group create --location westus2 --name myResourceGroupName --debug

Aqui está a saída do terminal do Azure Cloud Shell com algumas linhas omitidas para brevidade. Observe esta saída importante:

Argumentos de comando: É a linguagem de script, não a CLI do Azure, que analisa argumentos de comando (parâmetros). Esta propriedade de saída é o primeiro lugar a procurar quando um comando resulta em um erro.
azlogging: Esse caminho é onde o arquivo de log está armazenado.
Cabeçalhos de solicitação: Esses cabeçalhos são os valores de parâmetro passados pelo comando PUT .
Conteúdo da resposta: Esta saída é retornada ao console sem a saída completa --debug.

cli.knack.cli: Command arguments: ['group', 'create', '--location', 'westus2', '--name', 'myResourceGroupName', '--debug']
cli.knack.cli: __init__ debug log:
...
cli.knack.cli: Event: CommandInvoker.OnPreCommandTableCreate []
cli.azure.cli.core: Modules found from index for 'group': ['azure.cli.command_modules.resource']
cli.azure.cli.core: Loading command modules:
...
cli.azure.cli.core: Loaded 53 groups, 233 commands.
cli.azure.cli.core: Found a match in the command table.
cli.azure.cli.core: Raw command  : group create
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/2025-10-08.21-47-27.group_create.5217.log'.
...
cli.azure.cli.core.sdk.policies: Request URL: 'https://management.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/myResourceGroupName?api-version=2022-09-01'
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': 'c79caddc-ed78-11ef-8a83-00155dbc433c'
cli.azure.cli.core.sdk.policies:     'CommandName': 'group create'
cli.azure.cli.core.sdk.policies:     'ParameterSetName': '--location --name --debug'
...
cli.azure.cli.core.sdk.policies: Response content:
...
{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroupName",
  "location": "westus2",
  "managedBy": null,
  "name": "myResourceGroupName",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": "Microsoft.Resources/resourceGroups"
}
cli.knack.cli: Event: Cli.SuccessfulExecute []
cli.knack.cli: Event: Cli.PostExecute [<function AzCliLogging.deinit_cmd_metadata_logging at 0x7f98a6bc7820>]
az_command_data_logger: exit code: 0
...

Principais perceções da saída de depuração

Análise de comandos: A linguagem de script (não a CLI do Azure) analisa argumentos. Olhe aqui primeiro quando estiver solucionando problemas.
Localização do ficheiro de registo: Encontre registos detalhados no caminho mostrado para análise pós-morte em azlogging.
Detalhes da API: Veja a chamada de API REST real que está sendo feita, incluindo o método HTTP (PUT, GET, etc.).
Código de saída: Um valor de 0 indica sucesso; valores diferentes de zero 0 indicam erros.

Alguns comandos da CLI do Azure executam várias ações. Use --debug para ver cada comando que a CLI do Azure está executando. Ainda mais útil, use --debug para solucionar problemas por que um script da CLI do Azure está produzindo resultados inesperados.

Solução de problemas com --debug

Quantas vezes, como desenvolvedor, você pensou: "Esta tarefa deve ser tão simples! Por que meu script não está funcionando?" Quando você recebe resultados inesperados dos comandos da CLI do Azure , o --debug parâmetro é seu amigo! Vamos trabalhar com um exemplo de uma empresa com 100 contas de armazenamento do Azure. Você precisa encontrar as contas onde o acesso público a blobs está habilitado.

# Bash script - INCORRECT
resourceGroup="msdocs-rg-00000000"
az storage account list --resource-group $resourceGroup --query "[?allowBlobPublicAccess == `true`].id"

Quando um valor de parâmetro não está formatado corretamente para a linguagem de script que está analisando o valor, você recebe um invalid jmespath_type value erro:

cli.knack.cli: Command arguments: ['storage', 'account', 'list', '--resource-group', 'msdocs-rg-00000000', '--query', '[?allowBlobPublicAccess == ].id', '--debug']
...
cli.azure.cli.core.azclierror: argument --query: invalid jmespath_type value: '[?allowBlobPublicAccess == ].id'
az_command_data_logger: argument --query: invalid jmespath_type value: '[?allowBlobPublicAccess == ].id'

Veja o valor da variável que Bash está passando para allowBlobPublicAccess. Na verdade, onde está o valor? Por que está faltando?

Lembre-se, é o ambiente (também conhecido como "linguagem de script") que analisa os valores das variáveis da CLI do Azure . Cada linguagem de script, e até mesmo versões da mesma linguagem de script, podem produzir resultados diferentes. Aqui está a maneira correta de passar um valor de parâmetro booleano em Bash:

# Bash script - CORRECT
resourceGroup="msdocs-rg-00000000"
az storage account list --resource-group $resourceGroup --query "[?allowBlobPublicAccess == \`true\`].id" --debug

cli.knack.cli: Command arguments: ['storage', 'account', 'list', '--resource-group', 'msdocs-rg-00000000', '--query', '[?allowBlobPublicAccess == `true`].id', '--debug']
...
[
  "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-rg-00000000/providers/Microsoft.Storage/storageAccounts/msdocssa00000000"
]

Sugestão

A principal diferença é escapar dos backticks com \true'' para que Bash não os interprete como substituição de comando.

Compreenda o conceito importante do --debug, e você está no caminho certo para usar a CLI do Azure com êxito em seu ambiente de escolha.

Diferenças de sintaxe da linguagem de script

Como acabamos de falar sobre --debug, o próximo passo é estar ciente do que causa a maioria dos erros de script. Um script escrito em Bash precisa ser modificado para ser executado com êxito no PowerShell ou nocmd.exe se o script contiver uma destas construções:

Caracteres de continuação de linha
Variáveis
Identificadores aleatórios
Citações
Construções de linguagem de programação

Eis alguns exemplos:

Sintaxe	Bash	PowerShell	cmd.exe
Caracteres de continuação de linha	Barra invertida (`\`)	Backtick (`)	Caret (`^`)
Nomenclatura variável	`variableName=varValue`	`$variableName="varValue"`	`set variableName=varValue`
Número como cadeia de caracteres	`\`50''	`50`	`50`
Booleano como corda	`\`verdadeiro''	`false`	`'true'`
ID aleatório	`let "randomIdentifier=$RANDOM*$RANDOM"`	`$randomIdentifier = (New-Guid).ToString().Substring(0,8)`	`set randomIdentifier=%RANDOM%`
Looping	`until`, `while`, `for`	`for`, `foreach`, `while`, `do-while`, `do-until`	`for`
Escrever no console	`echo`	`Write-Host` (preferencial) ou `echo`	`echo`

Dificuldades comuns

Esta tabela de exemplo não é completa. O que é importante entender ao receber um erro da CLI do Azure é considerar primeiro que pode haver um problema de sintaxe para seu ambiente. Teste essa possibilidade copiando e colando seu script em outra linguagem de script, como o Azure Cloud Shell. Use --debug em ambos os ambientes e anote a diferença na propriedade da saída command arguments.

Importante

Ao copiar blocos de código de artigos da Microsoft , esteja ciente de que a maioria da documentação da CLI do Azure na Microsoft é escrita para Bash e testada no Azure Cloud Shell.

Mais formas de obter ajuda

Use az find

Faça um tour rápido pelos comandos da CLI do Azure seguindo estes exemplos:

Encontre os comandos mais populares relacionados com a palavra blob:

az find blob

Mostrar os comandos mais populares para um grupo de comandos da CLI do Azure , como az storage:

az find "az storage"

Mostrar os parâmetros e subcomandos mais populares para um comando da CLI do Azure :

az find "az storage account create"

Use --help

Se você já sabe o nome do comando desejado, o --help argumento para esse comando obtém informações mais detalhadas sobre o comando e uma lista dos subcomandos disponíveis para um grupo de comandos. Continuando com nossos exemplos de armazenamento do Azure , veja como você pode obter uma lista dos subgrupos e comandos para gerenciar o serviço de blob de uma conta de armazenamento:

az storage account blob-service-properties --help

Sugestão

Use --help com qualquer comando ou subcomando para obter informações detalhadas de uso sem sair do terminal.

Índices de documentação de A a Z

Para encontrar exemplos de comandos de referência da CLI do Azure , use um dos vários índices de A a Z:

Índice de referência: Fornece uma lista de A a Z de todos os grupos de referência. Expanda a barra de navegação esquerda para subgrupos.
Lista de artigos conceituais da CLI do Azure: fornece uma lista de A a Z de inícios rápidos, guias de instruções, tutoriais e módulos de aprendizagem que explicam como usar comandos de referência da CLI do Azure em cenários reais. A lista de artigos agrupa artigos por grupo de comandos da CLI do Azure , como az account, depois az acr, etc. Use Ctrl+F no Windows (Cmd+F no macOS) para ir rapidamente para o grupo de comandos de sua escolha.
Scripts de exemplo da CLI do Azure: O índice tem três abas:
- Lista por área temática: encontre exemplos para um serviço do Azure.
- Lista por grupo de referência: Encontre exemplos para um grupo de comandos de referência.
- Repositório GitHub de exemplos da CLI do Azure: encontre exemplos no repositório GitHub de exemplos da CLI do Azure.

Usar o Copilot

O portal Azure e o Microsoft Edge oferecem experiências do Copilot que fornecem informações sobre comandos de referência da CLI do Azure, exemplos e artigos publicados. O Copilot também fornece links para perguntas relacionadas no Stack Overflow. Quando você tem um trabalho difícil de ser feito com várias etapas de script, o Copilot é útil na compilação de várias fontes de informação para responder à sua pergunta.

Observação

O GitHub Copilot também pode ajudá-lo a escrever scripts da CLI do Azure diretamente no seu editor de código, fornecendo integração de código inteligente e sugestões.

Comentários

Esta página foi útil?