Sugestões para utilizar a CLI do Azure com sucesso

  • Artigo

A CLI do Azure é uma ferramenta de linha de comando que permite configurar e gerenciar recursos do Azure 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, consulte a lista Referência 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:

  1. O json formato mostra informações como uma cadeia de caracteres JSON.

    • JSON fornece as informações mais abrangentes.
    • Esse formato é o padrão, mas você pode usar o --output parâmetro para especificar uma opção diferente.
    • Altere o formato padrão global para uma de suas preferências pessoais usando az config , como az config set core.output=table.
    • O formato JSON preserva as aspas duplas, geralmente tornando-o inadequado para fins de script.

  2. O table formato apresenta a saída como uma tabela legível. Você pode especificar quais valores aparecem na tabela e usar consultas para personalizar a saída, conforme 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

  3. O tsv formato retorna valores separados por tabulação e por novas linhas sem formatação extra, teclas ou outros símbolos.

    • O formato TSV é útil para fins de saída concisa e scripting.
    • O TSV tira aspas duplas que o formato JSON preserva.
    • Para especificar o formato desejado para TSV, use o --query parâmetro.
    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, consulte Formatos de saída para comandos da CLI do Azure.

Passar 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 a tubulação. (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:

  1. Se você precisar de mais controles sobre o resultado, use um 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

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

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

  3. Finalmente, a CLI do Azure tem suporte interno para processar comandos com múltiplos --ids em paralelo para obter o mesmo efeito de xargs. @- é usado para obter valores do tubo:

    az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | az vm start --ids @-

Para obter mais informações sobre como usar construções Bash com a CLI do Azure, incluindo loops, instruções de caso, if.. então.. e tratamento de erros, consulte Aprenda a usar o Bash com a CLI do Azure.

Usar aspas em parâmetros

Ao trabalhar 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.

Nota

Devido a um problema conhecido no PowerShell, algumas regras de escape extras se aplicam. Para obter mais informações, consulte Citando problemas com o PowerShell.

Para evitar resultados imprevistos, aqui ficam algumas sugestões:

  • Se você fornecer um parâmetro que contenha espaço em branco, envolva-o entre aspas.

  • No Bash ou PowerShell, aspas simples e duplas são interpretadas corretamente. No Prompt de Comando do Windows, apenas aspas duplas são interpretadas corretamente -- aspas simples são tratadas como parte do valor.

  • Se o comando só for executado em Bash (ou Zsh), use aspas simples para preservar o conteúdo dentro da cadeia de caracteres JSON. Cotações simples são necessárias ao fornecer valores JSON embutidos. Por exemplo, este JSON está correto em Bash: '{"key": "value"}'.

  • Se o comando for executado em um prompt de comando do Windows, você deverá usar aspas duplas. Se o valor contiver aspas duplas, você deve escapar dele. O equivalente da cadeia de caracteres JSON acima é "{\"key\": \"value\"}"

  • No PowerShell, se o seu valor for uma cadeia de caracteres vazia, use '""'.

  • Em Bash ou PowerShell, se o seu valor for uma cadeia de aspas ''vazia , use "''".

  • Use a convenção da @<file> CLI do Azure para carregar 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, escape da variável: "\$variable".

  • Alguns comandos da CLI do Azure usam uma lista de valores separados por espaço.

    • Se o nome ou valor da chave contiver espaços, envolva todo o par: "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 indica que aceita uma lista separada por espaço, um dos dois formatos é esperado:

      1. Lista sem aspas e separada por espaços --parameterName firstValue secondValue
      2. Lista separada por espaços entre aspas --parameterName "firstValue" "secondValue"

      Este exemplo é uma cadeia de caracteres com um espaço. 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 escapar dele. 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

  • Quando você usa o --query parâmetro com um comando, alguns caracteres de JMESPath precisam ser escapados no shell.

    Estes três comandos são corretos e equivalentes em Bash:

    az version --query '"azure-cli"'
az version --query \"azure-cli\"
az version --query "\"azure-cli\""

    Aqui estão 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 exemplos de comparações entre Bash, PowerShell e Cmd, consulte Query Azure CLI command output

  • A melhor maneira de solucionar um problema de cotação é executar o comando com o --debug sinalizador. Esse sinalizador revela os argumentos reais recebidos pela CLI do Azure na sintaxe do 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 parâmetros

Se o valor de um parâmetro começar com um hífen, a CLI do Azure tentará analisá-lo como um nome de parâmetro. Para 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 uma quantidade notável de tempo. Por exemplo, configurar uma máquina virtual em um data center não é instantâneo. A CLI do Azure aguarda até que o comando termine para aceitar outros comandos. Muitos comandos, portanto, oferecem um --no-wait parâmetro 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 levar muito tempo. Quando você executa o comando com o --no-wait parâmetro, o console aceita novos comandos sem interromper a remoção.

Muitos comandos oferecem uma opção de espera, pausando o console até que alguma condição seja atendida. O exemplo a seguir 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 ambos os IDs forem criados, você poderá usar o console novamente.

Trabalhar atrá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 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 REQUESTS_CA_BUNDLE de ambiente como o caminho do arquivo de certificado do pacote da autoridade de certificação no formato PEM.

SO Pacote de autoridade de certificação padrão
Windows de 32 bits C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem
Windows de 64 bits C:\Program Files\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem
Ubuntu/Debian 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

Anexe o certificado do servidor proxy ao arquivo de certificado do pacote da autoridade de certificação ou copie o conteúdo para outro arquivo de certificado. Em seguida, defina REQUESTS_CA_BUNDLE para o novo local do arquivo. Eis um exemplo:

<Original cacert.pem>

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

Alguns proxies requerem autenticação. O formato das HTTP_PROXY variáveis ou HTTPS_PROXY de ambiente deve incluir a autenticação, como HTTPS_PROXY="https://username:password@proxy-server:port". Para obter detalhes, consulte Como configurar proxies para as bibliotecas do Azure.

Execução simultânea

Se você executar comandos da CLI do Azure simultaneamente na mesma máquina, conflitos de gravação poderão acontecer se vários comandos da CLI do Azure gravarem no mesmo cache de token MSAL.

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

export AZURE_CONFIG_DIR=/my/config/dir

Parâmetros de atualização genéricos

Os grupos de comandos da CLI do Azure geralmente apresentam um comando update. 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, --sete --remove.

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

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

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

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)

Um serviço com o qual você deseja trabalhar pode não ter suporte à CLI do Azure. Você pode usar os comandos az resource para trabalhar com esses recursos.

Se você só precisar de comandos create ou update, use az deployment group create. Para obter exemplos práticos, consulte Modelos de início rápido do Azure.

Comandos da API REST (az rest)

Se os parâmetros de atualização genéricos e o recurso az não atenderem às suas necessidades, você poderá usar 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. Para obter mais informações, consulte Referência da API REST do Azure.

Este exemplo funciona com a API do Microsoft Graph. Para atualizar URIs de redirecionamento para um aplicativo, chame a API REST do aplicativo Update, 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 na forma de OData, certifique-se de escapar $ em diferentes ambientes: em Bash, escape $ como \$ e em PowerShell, escape $ como `$

Exemplos de script

Aqui estão exemplos de como usar variáveis e fazer looping em uma lista ao trabalhar com Máquinas Virtuais do Azure. Para obter exemplos detalhados sobre como usar construções Bash com a CLI do Azure, incluindo loops, instruções de caso, if.. então.. e tratamento de erros, consulte Aprenda a usar o Bash com a CLI do Azure.

Use estes scripts para salvar IDs em variáveis:

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

Use estes scripts para percorrer uma lista:

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
)

Consulte também