Dicas para usar a CLI do Azure com êxito

Artigo
03/01/2024

A CLI do Azure é uma ferramenta de linha de comando que permite configurar e gerenciar recursos do Azure por meio de vários ambientes de shell. Depois de escolher seu ambiente de shell preferido e instalar a CLI do Azure, use este artigo para descobrir dicas úteis sobre como evitar armadilhas comuns e usar a CLI do Azure com êxito.

Para saber mais sobre comandos específicos da CLI do Azure, confira a Lista de referências da CLI do Azure.

Formatação de saída

Três formatos de saída comuns são usados com comandos da CLI do Azure:

O formato json mostra as informações como uma cadeia de caracteres JSON.
- O JSON oferece as informações mais abrangentes.
- Esse formato é o padrão, mas você pode usar o parâmetro --output para especificar uma opção diferente.
- Altere o formato padrão global para um de sua preferência pessoal usando az config, como az config set core.output=table.
- O formato JSON preserva as aspas duplas, geralmente tornando-as inadequadas para fins de script.

O formato table apresenta a saída como uma tabela legível para pessoas. Você pode especificar quais valores aparecem na tabela e usar consultas para personalizar a saída, como é mostrado aqui:

# command
az vm show --resource-group myResourceGroup --name myVMname --query "{name: name, os:storageProfile.imageReference.offer}" --output table

# output
Name    Os
------  ------------
myVMname   UbuntuServer

O formato tsv retorna valores separados por guias e por novas linhas sem formatação, chaves ou outros símbolos extras.
- O formato TSV é útil para gerar scripts e saídas concisos.
- O TSV remove aspas duplas que o formato JSON preserva.
- Para especificar o formato desejado como TSV, use o parâmetro --query.
```
export vm_ids=$(az vm list --show-details --resource-group myResourceGroup --query "[?powerState=='VM running'].id" --output tsv)
az vm stop --ids $vm_ids
```

Para obter mais informações sobre esses e outros formatos de saída, confira Formatos de saída para comandos da CLI do Azure.

Converter valores para outro comando

Se o valor for usado mais de uma vez, atribua-o a uma variável. As variáveis permitem que você use valores mais de uma vez ou crie scripts mais gerais. Este exemplo atribui uma ID encontrada pelo comando az vm list a uma variável.

# assign the list of running VMs to a variable
running_vm_ids=$(az vm list --resource-group MyResourceGroup --show-details \
    --query "[?powerState=='VM running'].id" --output tsv)

# verify the value of the variable
echo $running_vm_ids

Se o valor for usado apenas uma vez, considere usar a barra vertical. (A tubulação passa a saída de um comando como entrada para um segundo comando.)

az vm list --query "[?powerState=='VM running'].name" --output tsv | grep my_vm

Para listas de vários valores, considere as seguintes opções:

Se você precisar de mais controles no resultado, use o loop "for":

#!/usr/bin/env bash
for vmList in $(az vm list --resource-group MyResourceGroup --show-details --query "[?powerState=='VM running'].id"   --output tsv); do
    echo stopping $vmList
    az vm stop --ids $vmList
    if [ $? -ne 0 ]; then
        echo "Failed to stop $vmList"
        exit 1
    fi
    echo $vmList stopped
done

Como alternativa, use xargs e considere usar o sinalizador -P para executar as operações em paralelo para melhor desempenho:

az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | xargs -I {} -P 10 az vm start --ids "{}"

Por fim, a CLI do Azure tem suporte interno para processar comandos com vários --ids em paralelo de modo a obter o mesmo efeito de xargs. @- é usado para obter valores do pipe:
```
az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | az vm start --ids @-
```

Para obter mais informações de como usar constructos do Bash com a CLI do Azure, incluindo loops, instruções de maiúsculas e minúsculas, if..then..else e tratamento de erro, confira Aprender a usar o Bash com a CLI do Azure.

Usar aspas em parâmetros

Quando você trabalha com comandos da CLI do Azure, esteja ciente de como seu shell usa aspas e caracteres de escape. Se você oferecer suporte a scripts usados em shells diferentes, entenda como eles diferem.

Bash. Colocação de aspas
PowerShell. Sobre as regras de colocação de aspas
Prompt de Comando do Windows. Instruções: caracteres de escape, delimitadores e aspas na linha de comando do Windows

Observação

Devido ao problema conhecido do PowerShell, algumas regras extras de escape se aplicam. Para obter mais informações, consulte Problemas com colocações de aspas no PowerShell.

Para evitar resultados inesperados, veja algumas sugestões:

Se você fornecer um parâmetro que contenha espaço em branco, coloque-o entre aspas.
No Bash ou no PowerShell, tanto as aspas simples quanto as duplas são interpretadas corretamente. No Prompt de Comando do Windows, somente as aspas duplas são interpretadas corretamente. As aspas simples são consideradas parte do valor.
Se o comando for executado apenas no Bash (ou no Zsh), use aspas simples para preservar o conteúdo dentro da cadeia de caracteres JSON. Aspas simples são necessárias ao fornecer valores JSON embutidos. Por exemplo, este JSON está correto no Bash: '{"key": "value"}'.
Se o comando for executado no Prompt de Comando do Windows, você precisará usar aspas duplas. Se o valor contiver aspas duplas, você precisará usar um caractere de escape. O equivalente da cadeia de caracteres JSON acima é "{\"key\": \"value\"}"
No PowerShell, se o valor for uma cadeia de caracteres vazia, use '""'.
No Bash ou no PowerShell, se o valor for uma cadeia de caracteres de aspas vazia '', use "''".
Use a convenção @<file> da CLI do Azure para carregar dados de um arquivo e ignorar os mecanismos de interpretação do shell.
```
az ad app create --display-name myName --native-app --required-resource-accesses @manifest.json
```
O Bash avalia aspas duplas em variáveis exportadas. Se esse comportamento não for o que você deseja, faça o escape da variável: "\$variable".
Alguns comandos da CLI do Azure usam uma lista de valores separados por espaços.
- Se o nome da chave ou o valor contiver espaços, coloque o par inteiro entre aspas: "my key=my value". Por exemplo:
```
az web app config app settings set --resource-group myResourceGroup --name myWebAppName --settings "client id=id1" "my name=john"
```
- Quando um parâmetro da CLI afirma que aceita uma lista separada por espaço, um destes dois formatos é esperado:
  1. Lista separada por espaço, sem aspas --parameterName firstValue secondValue
  2. Lista separada por espaços, com aspas --parameterName "firstValue" "secondValue"
  Este exemplo é uma cadeia de caracteres que contém um espaço. Ele não é uma lista separada por espaço: --parameterName "firstValue secondValue"

Há caracteres especiais do PowerShell, como em @. Para executar a CLI do Azure no PowerShell, adicione ` antes do caractere especial para fazer o escape. Você também pode colocar o valor entre aspas simples ou duplas "/".

# The following three examples will work in PowerShell
--parameterName `@parameters.json
--parameterName '@parameters.json'
--parameterName "@parameters.json"

# This example will not work in PowerShell
--parameterName @parameters.json

Ao usar o parâmetro --query com um comando, alguns caracteres de JMESPath precisam usar o caractere de escape no shell.
- Bash
- PowerShell
- Cmd
Estes três comandos estão corretos e são equivalentes no Bash:
```
az version --query '"azure-cli"'
az version --query \"azure-cli\"
az version --query "\"azure-cli\""
```
Veja dois exemplos de comandos incorretos no Bash:
```
# Wrong, as the dash needs to be quoted in a JMESPath query
az version --query azure-cli
az version: error: argument --query: invalid jmespath_type value: 'azure-cli'

# Wrong, as the dash needs to be quoted in a JMESPath query, but quotes are interpreted by Bash
az version --query "azure-cli"
az version: error: argument --query: invalid jmespath_type value: 'azure-cli'
```
Para obter mais comparações de exemplo entre o Bash, o PowerShell e o Cmd, confira Consultar a saída de comando da CLI do Azure
Estes cinco comandos funcionam corretamente no PowerShell:
```
az version --query '\"azure-cli\"'
az version --query "\`"azure-cli\`""
az version --query "\""azure-cli\"""
az --% version --query "\"azure-cli\""
az --% version --query \"azure-cli\"
```
Para obter mais comparações de exemplo entre o Bash, o PowerShell e o Cmd, confira Consultar a saída de comando da CLI do Azure
Estes dois comandos funcionam corretamente no Prompt de Comando do Windows:
```
az version --query "\"azure-cli\""
az version --query \"azure-cli\"
```
Para obter mais comparações de exemplo entre o Bash, o PowerShell e o Cmd, confira Consultar a saída de comando da CLI do Azure

A melhor maneira de solucionar um problema de aspas é executar o comando com o sinalizador --debug. Esse sinalizador mostra os argumentos reais recebidos pela CLI do Azure na sintaxe Python.

# Correct
$ az '{"key":"value"}' --debug
Command arguments: ['{"key":"value"}', '--debug']

# Correct
$ az "{\"key\":\"value\"}" --debug
Command arguments: ['{"key":"value"}', '--debug']

# Wrong, as quotes and spaces are interpreted by Bash
$ az {"key": "value"} --debug
Command arguments: ['{key:', 'value}', '--debug']

# Wrong, as quotes are interpreted by Bash
$ az {"key":"value"} --debug
Command arguments: ['{key:value}', '--debug']

Usar caracteres de hífen em argumentos

Se um valor de parâmetro começar com um hífen, a CLI do Azure tentará analisá-lo como um nome de parâmetro. Se quiser analisá-lo como valor, use = para concatenar o nome e o valor do parâmetro: --password="-VerySecret".

Operações assíncronas

As operações no Azure podem levar um tempo significativo. Por exemplo, a configuração de uma máquina virtual em um datacenter não é instantânea. A CLI do Azure aguarda até que o comando seja concluído para aceitar outros comandos. Portanto, muitos comandos oferecem um parâmetro --no-wait, como é mostrado aqui:

az group delete --name MyResourceGroup --no-wait

Quando você exclui um grupo de recursos, todos os recursos que pertencem a ele também são removidos. A remoção desses recursos pode demorar bastante tempo. Quando você executa o comando com o parâmetro --no-wait, o console aceita novos comandos sem interromper a remoção.

Muitos comandos oferecem a opção de espera, pausando o console até que alguma condição seja atendida. O seguinte exemplo usa o comando az vm wait para dar suporte à criação de recursos independentes em paralelo:

az vm create --resource-group VMResources --name virtual-machine-01 --image centos --no-wait
az vm create --resource-group VMResources --name virtual-machine-02 --image centos --no-wait

subscription=$(az account show --query "id" -o tsv)
vm1_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-01"
vm2_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-02"
az vm wait --created --ids $vm1_id $vm2_id

Depois que as duas IDs forem criadas, você poderá usar o console novamente.

Trabalhar usando um proxy

Se você estiver usando a CLI do Azure em um servidor proxy que use certificados autoassinados, a biblioteca de solicitações 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 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/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, confira Como configurar proxies para as bibliotecas do Azure.

Execução simultânea

Se você executar comandos da CLI do Azure simultaneamente no mesmo computador, poderão ocorrer conflitos de gravação se vários deles gravarem no mesmo cache de token MSAL.

Para evitar possíveis falhas, isole a pasta de configuração da CLI do Azure de cada script definindo a variável de ambiente AZURE_CONFIG_DIR para um diretório separado com relação a cada um deles. Os comandos da CLI do Azure nesse script salvam a configuração e o cache de token no local configurado em vez de na pasta padrão ~/.azure.

export AZURE_CONFIG_DIR=/my/config/dir

$env:AZURE_CONFIG_DIR='D:\my\config\dir'

set AZURE_CONFIG_DIR=D:\my\config\dir

Parâmetros de atualização genéricos

Os grupos de comandos da CLI do Azure geralmente apresentam um comando de atualização. Por exemplo, as máquinas virtuais do Azure incluem o comando az vm update. A maioria dos comandos de atualização oferece os três parâmetros genéricos: --add, --set e --remove.

Os parâmetros --set e --add usam uma lista de pares chave-valor separados por espaços: key1=value1 key2=value2. Para ver quais propriedades você pode atualizar, use um comando de exibição, como az vm show.

az vm show --resource-group VMResources --name virtual-machine-01

Para simplificar o comando, você pode usar uma cadeia de caracteres JSON. Por exemplo, use o seguinte valor para anexar um novo disco de dados a uma máquina virtual:

az vm update --resource-group VMResources --name virtual-machine-01 \
--add storageProfile.dataDisks "{\"createOption\": \"Attach\", \"managedDisk\":
   {\"id\":
   \"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/yg/providers/Microsoft.Compute/disks/yg-disk\"},
   \"lun\": 1}"

Comandos de recurso genéricos (az resource)

Talvez um serviço com o qual você quer trabalhar ainda não seja compatível com a CLI do Azure. Você pode usar os comandos az resource para trabalhar com esses recursos.

Se você precisar apenas criar ou atualizar comandos, use az deployment group create. Use os Modelos de Início Rápido do Azure para obter exemplos de trabalho.

Comandos da API REST (az rest)

Se os parâmetros genéricos de atualização e o az resource não atenderem às suas necessidades, use o comando az rest para chamar a API REST. O comando autentica automaticamente usando a credencial conectada e define o cabeçalho Content-Type: application/json. Consulte a Referência da API REST do Azure para saber mais.

Este exemplo funciona com a API do Microsoft Graph. Para atualizar os URIs de redirecionamento de um Aplicativo, chamamos a API REST Atualizar aplicativo, como neste código:

# Get the application
az rest --method GET \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001'

# Update `redirectUris` for `web` property
az rest --method PATCH \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001' \
    --body '{"web":{"redirectUris":["https://myapp.com"]}}'

Ao usar --uri-parameters para solicitações no formato de OData, use o caractere de escape $ em ambientes diferentes. No Bash, use o caractere escape $ como \$; e no PowerShell, use-o em $ como `$

Exemplos de script

Veja exemplos de uso de variáveis e loops em uma lista ao trabalhar com as Máquinas Virtuais do Azure. Para obter exemplos mais detalhados de como usar constructos do Bash com a CLI do Azure, incluindo loops, instruções de maiúsculas e minúsculas, if/then/else e tratamento de erro, confira Aprender a usar o Bash com a CLI do Azure.

Use estes scripts para salvar IDs em variáveis:

Bash
PowerShell

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
   `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    SET "vm_ids=%%F %vm_ids%"  :: construct the id list
)
az vm stop --ids %vm_ids% :: CLI stops all VMs in parallel

$vm_ids=(az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv)
az vm stop --ids $vm_ids # CLI stops all VMs in parallel

Use estes scripts para fazer loop em uma lista:

Bash
PowerShell

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
    `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    ECHO Stopping %%F
    az vm stop --ids %%F
)

$vm_ids=(az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv)
foreach ($vm_id in $vm_ids) {
    Write-Output "Stopping $vm_id"
    az vm stop --ids $vm_id
}

Confira também

Configurar a CLI do Azure
Aprender a usar o Bash com a CLI do Azure
Consultar a saída do comando da CLI do Azure
Usar variáveis em comandos da CLI do Azure
Localizar amostras e artigos publicados da CLI do Azure