Formatos de saída dos comandos da CLI do Azure

  • Artigo

A CLI do Azure usa JSON como formato de saída padrão, mas oferece outros formatos. Use o parâmetro --output (--out ou -o) para formatar a saída da CLI. Os valores e tipos de argumentos de saída são:

--output Descrição
json cadeia de caracteres JSON. Essa configuração é a padrão
jsonc JSON colorido
table A tabela ASCII com chaves como títulos de colunas
tsv Valores separados por tabulação, sem chaves
yaml YAML, uma alternativa ao JSON legível por seres humanos
yamlc YAML colorido
none Nenhuma saída diferente de erros e avisos

Aviso

Use um formato de saída de none ou armazene a saída do comando em uma variável para evitar a exposição de segredos, como chaves de API e credenciais. Observação: Alguns ambientes de CI/CD podem armazenar a saída dos comandos executados em registros. É uma boa prática confirmar o que está escrito nesses arquivos de registro e quem tem acesso a eles. Para mais informações, consulte Nenhum formato de saída.

Formato de saída JSON (padrão)

O exemplo a seguir exibe a lista de máquinas virtuais em suas assinaturas no formato JSON padrão.

az vm list --output json

A saída a seguir tem alguns campos omitidos para fins de brevidade e informações de identificação substituídas.

[
  {
    "availabilitySet": null,
    "diagnosticsProfile": null,
    "hardwareProfile": {
      "vmSize": "Standard_DS1"
    },
    "id": "/subscriptions/.../resourceGroups/DEMORG1/providers/Microsoft.Compute/virtualMachines/DemoVM010",
    "instanceView": null,
    "licenseType": null,
    "location": "westus",
    "name": "DemoVM010",
    "networkProfile": {
      "networkInterfaces": [
        {
          "id": "/subscriptions/.../resourceGroups/demorg1/providers/Microsoft.Network/networkInterfaces/DemoVM010VMNic",
          "primary": null,
          "resourceGroup": "demorg1"
        }
      ]
    },
          ...
          ...
          ...
]

Formato de saída YAML

O formato yaml imprime a saída como YAML, um formato de serialização de dados de texto sem formatação. YAML tende a ser mais fácil de ler que o JSON e facilmente mapeia para esse formato. Alguns aplicativos e comandos da CLI usam YAML como entrada de configuração, em vez de JSON.

az vm list --output yaml

A saída a seguir tem alguns campos omitidos para fins de brevidade e informações de identificação substituídas.

- availabilitySet: null
  diagnosticsProfile: null
  hardwareProfile:
    vmSize: Standard_DS1_v2
  id: /subscriptions/.../resourceGroups/DEMORG1/providers/Microsoft.Compute/virtualMachines/DemoVM010
  identity: null
  instanceView: null
  licenseType: null
  location: westus
  name: ExampleVM1
  networkProfile:
    networkInterfaces:
    - id: /subscriptions/.../resourceGroups/DemoRG1/providers/Microsoft.Network/networkInterfaces/DemoVM010Nic
      primary: null
      resourceGroup: DemoRG1
  ...
...

Formato de saída da tabela

O formato table imprime a saída como uma tabela ASCII, facilitando a leitura e a análise. Objetos aninhados não são incluídos na saída da tabela, mas ainda podem ser filtrados como parte de uma consulta. Alguns campos não estão incluídos na tabela, por isso, esse formato é o ideal quando seu objetivo é ter uma visão geral rápida dos dados e que possa ser pesquisada manualmente.

az vm list --output table

Name         ResourceGroup    Location
-----------  ---------------  ----------
DemoVM010    DEMORG1          westus
demovm212    DEMORG1          westus
demovm213    DEMORG1          westus
KBDemo001VM  RGDEMO001        westus
KBDemo020    RGDEMO001        westus

Você pode usar o parâmetro --query para personalizar as propriedades e as colunas que você deseja mostrar na saída da lista. O exemplo a seguir mostra como selecionar o Nome da VM e o Nome do Grupo de Recursos no comando list.

az vm list --query "[].{resource:resourceGroup, name:name}" --output table

Resource    Name
----------  -----------
DEMORG1     DemoVM010
DEMORG1     demovm212
DEMORG1     demovm213
RGDEMO001   KBDemo001VM
RGDEMO001   KBDemo020

Observação

Algumas chaves não são impressas no modo de exibição de tabela, por padrão. Elas são: id, type e etag. Se você precisar ver isso na saída, poderá usar o recurso de recriação de chave JMESPath para alterar o nome da chave e evitar a filtragem.

az vm list --query "[].{objectID:id}" --output table

Para obter mais informações sobre como usar consultas para filtrar dados, confira Usar as consultas JMESPath com a CLI do Azure.

O formato de saída TSV

O formato de saída tsv retorna valores separados por tabulação e nova linha sem formatação, chaves ou outros símbolos adicionais. Esse formato facilita o consumo da saída em outros comandos e ferramentas que precisam processar o texto de alguma maneira. Como o formato table, tsv não imprime objetos aninhados.

Se o exemplo anterior com a opção tsv for usado, gerará o resultado separado por tabulações.

az vm list --output tsv

None    None        /subscriptions/.../resourceGroups/DEMORG1/providers/Microsoft.Compute/virtualMachines/DemoVM010    None    None    westus    DemoVM010            None    Succeeded    DEMORG1    None            Microsoft.Compute/virtualMachines    cbd56d9b-9340-44bc-a722-25f15b578444
None    None        /subscriptions/.../resourceGroups/DEMORG1/providers/Microsoft.Compute/virtualMachines/demovm212    None    None    westus    demovm212            None    Succeeded    DEMORG1    None            Microsoft.Compute/virtualMachines    4bdac85d-c2f7-410f-9907-ca7921d930b4
None    None        /subscriptions/.../resourceGroups/DEMORG1/providers/Microsoft.Compute/virtualMachines/demovm213    None    None    westus    demovm213            None    Succeeded    DEMORG1    None            Microsoft.Compute/virtualMachines    2131c664-221a-4b7f-9653-f6d542fbfa34
None    None        /subscriptions/.../resourceGroups/RGDEMO001/providers/Microsoft.Compute/virtualMachines/KBDemo001VM    None    None    westus    KBDemo001VM            None    Succeeded    RGDEMO001    None            Microsoft.Compute/virtualMachines    14e74761-c17e-4530-a7be-9e4ff06ea74b
None    None        /subscriptions/.../resourceGroups/RGDEMO001/providers/Microsoft.Compute/virtualMachines/KBDemo020   None    None    westus    KBDemo020            None    Succeeded    RGDEMO001    None            Microsoft.Compute/virtualMachines    36baa9-9b80-48a8-b4a9-854c7a858ece

Uma restrição do formato de saída TSV é que não há uma garantia de ordem na saída. A CLI realiza todos os esforços para preservar a ordenação classificando alfabeticamente as chaves de classificação na resposta JSON e depois imprimindo os valores nessa ordem para a saída TSV. Não há garantia de que a ordem seja sempre idêntica, já que o formato de resposta de serviço do Azure pode mudar.

Para impor uma ordem consistente, é necessário usar o parâmetro --query e o formato de lista de multisseleção. Quando um comando de CLI retorna um único dicionário JSON, use o formato geral [key1, key2, ..., keyN] para forçar uma ordem de chave. Para comandos da CLI que retornam uma matriz, use o [].[key1, key2, ..., keyN] de formato geral para ordenar valores de coluna.

Por exemplo, para ordenar as informações exibidas acima da ID, do local, do grupo de recursos e do nome da VM:

az vm list --output tsv --query '[].[id, location, resourceGroup, name]'

/subscriptions/.../resourceGroups/DEMORG1/providers/Microsoft.Compute/virtualMachines/DemoVM010    westus    DEMORG1    DemoVM010
/subscriptions/.../resourceGroups/DEMORG1/providers/Microsoft.Compute/virtualMachines/demovm212    westus    DEMORG1    demovm212
/subscriptions/.../resourceGroups/DEMORG1/providers/Microsoft.Compute/virtualMachines/demovm213    westus    DEMORG1    demovm213
/subscriptions/.../resourceGroups/RGDEMO001/providers/Microsoft.Compute/virtualMachines/KBDemo001VM     westus  RGDEMO001       KBDemo001VM
/subscriptions/.../resourceGroups/RGDEMO001/providers/Microsoft.Compute/virtualMachines/KBDemo020       westus  RGDEMO001       KBDemo020

O exemplo a seguir mostra como a saída tsv pode ser transportada para outros comandos no bash. A consulta é usada para filtrar a saída e forçar o ordenamento, grep seleciona itens com o texto "RGD" e o comando cut seleciona o quarto campo para mostrar o nome da VM na saída.

az vm list --output tsv --query '[].[id, location, resourceGroup, name]' | grep RGD | cut -f4

KBDemo001VM
KBDemo020

O formato de saída tsv é frequentemente usado ao atribuir valores a variáveis. Este exemplo obtém a ID de assinatura ativa e a armazena em uma variável para uso em um script.

# Bash Script
subscriptionID=$(az account show --query id --output tsv)
echo "Using subscription ID $subscriptionID"

Para obter mais exemplos de parâmetros --query, consulte Como consultar a saída do comando da CLI do Azure.

Nenhum formato de saída

Alguns comandos da CLI do Azure geram informações que você deve proteger. Aqui estão quatro exemplos:

  • senhas
  • Cadeias de conexão
  • segredos
  • keys

Para proteger segredos e chaves ao usar comandos da CLI do Azure, escolha uma dessas opções:

Opção Benefício Caso de uso
--output none formato de saída Evita que informações confidenciais sejam exibidas no seu console. Se o comando falhar, você ainda receberá mensagens de erro. 1. Use quando a saída do comando pode ser recuperada posteriormente.
2. Use quando você não tiver necessidade de saída.
3. Uma escolha comum quando uma identidade gerenciada ou uma entidade de serviço está sendo usada para gerenciar recursos do Azure.
Parâmetro --query Armazena a saída em uma variável. 1. Use quando a saída do comando não pode ser recuperada posteriormente.
2. Use quando precisar usar um valor de saída de comando em um script.

Use none e recupere informações de segurança posteriormente

Alguns segredos do Azure podem ser recuperados posteriormente. Um bom exemplo são os segredos armazenados no Azure Key Vault. Neste exemplo, crie um segredo do Azure Key Vault usando az keyvault secret set com a opção --output none. Você pode recuperar o segredo mais tarde usando o comando az keyvault secret show.

az keyvault secret set --name MySecretName \
                       --vault-name MyKeyVaultName \
                       --value MySecretValue\
                       --output none

Usar --query e retornar informações de segurança para uma variável

O uso de --query para armazenar a saída em uma variável não é tecnicamente um formato de saída. É uma solução para proteger segredos, e é uma alternativa ao uso --output none. Por exemplo, quando você redefine uma credencial de entidade de serviço, a senha não pode ser recuperada novamente.

Redefina uma credencial de entidade de serviço retornando a saída no formato JSON padrão:

# reset service principal credentials using default output format (json).
az ad sp credential reset --id myServicePrincipalID --output json

Saída do console mostrando a nova senha no console.

{
  "appId": "myServicePrincipalID",
  "password": "myServicePrincipalNewPassword",
  "tenant": "myTenantID"
}

Uma solução melhor é retornar informações confidenciais para uma variável.

# Bash Script
# reset service principal credentials returning results to a variable
myNewPassword=$(az ad sp credential reset --id myServicePrincipalID --query password --output tsv)

# Display the new password (remove this line in production for security)
echo "New password: $myNewPassword"

Para obter mais exemplos sobre como armazenar a saída para uma variável, consulte Usar a CLI do Azure com êxito - passar valores para outro comando. Para saber mais sobre --query sintaxe de parâmetro, consulte Como consultar a saída do comando da CLI do Azure.

Definir o formato de saída padrão

Os comandos da CLI do Azure fornecem saída que pode ser controlada de duas maneiras:

Controle de saída Benefício Como fazer
Cenário global Selecione um valor de saída padrão que você mais usa para não precisar fornecer continuamente um parâmetro --output para cada comando de referência. Especifique um formato de saída padrão usando az config set.
Parâmetro Command Especifique a saída no nível de comando e dê aos scripts a máxima flexibilidade. Você controla a saída do console, e a entrada de variáveis para cada comando de referência. Substitua a configuração padrão usando o parâmetro --output de um comando de referência.

A saída padrão para a CLI do Azure é json. Defina a saída padrão para none quando a saída do console não for necessária.

az config set core.output=none

Você pode substituir a saída padrão de qualquer comando de referência da CLI do Azure usando o parâmetro --output. Aqui está um script de comandos que alteram e testam a saída do comando:

# set your default output to table
az config set core.output=table

# show your active subscription in table format
# notice how only a subset of properties are returned in the table
az account show

# override your table default and show your active subscription in jsonc format
az account show --output jsonc

# reset your default output to json
az config set core.output=json

Confira também