Como selecionar o formato de saída Formato de saída JSON Formato da saída YAML Formato da saída de fluxo do YAML Formato de saída de texto Formato de saída de tabela

Definição do formato da saída da AWS CLI

Este tópico descreve os diferentes formatos de saída para a AWS Command Line Interface (AWS CLI). A AWS CLI oferece suporte aos seguintes formatos de saída:

json: a saída é formatada como uma string JSON.
yaml: a saída é formatada como uma string YAML.
yaml-stream: a saída é transmitida e formatada como uma string YAML. A transmissão possibilita um manuseio mais rápido de tipos de dados grandes.
text: a saída é formatada como várias linhas de valores de string separados por tabulação. Isso pode ser útil para passar a saída para um processador de texto, como grep, sed ou awk.
table: a saída é formatada como uma tabela usando os caracteres +|- para formar as bordas da célula. Geralmente, a informação é apresentada em um formato "amigável", que é muito mais fácil de ler do que outros, mas não tão útil programaticamente.

Como selecionar o formato de saída

Como explicado no tópico sobre configuração, você pode especificar o formato de saída de três maneiras:

Usando a opção output em um perfil nomeado no arquivo config: o exemplo a seguir ajusta o formato de saída padrão como text.
```
[default]
output=text
```
Usando a variável de ambiente AWS_DEFAULT_OUTPUT: a saída a seguir ajusta o formato como table para os comandos nessa sessão de linhas de comandos até que a variável seja alterada ou a sessão encerrada. Usar essa variável de ambiente substitui qualquer valor definido no arquivo config.
```
$ export AWS_DEFAULT_OUTPUT="table"
```
Usando a opção --output na linha de comando: o exemplo a seguir define a saída apenas deste comando como json. Usar essa opção no comando substitui qualquer variável de ambiente definida atualmente ou o valor no arquivo config.
```
$ aws swf list-domains --registration-status REGISTERED --output json
```

Importante

O tipo de saída especificado por você modifica a forma de operação da opção --query.

Se você especificar --output text, a saída será paginada antes que o filtro --query seja aplicado, e a AWS CLI executará a consulta uma vez em cada página da saída. Consequentemente, a consulta inclui o primeiro elemento correspondente em cada página, o que pode resultar em uma saída adicional inesperada. Para filtrar ainda mais a saída, é possível usar outras ferramentas da linha de comando, como head ou tail.
Se você especificar --output json, --output yaml ou --output yaml-stream, a saída será completamente processada como uma única estrutura JSON nativa antes que o filtro --query seja aplicado. A AWS CLI executa a consulta apenas uma vez com relação a toda a estrutura, produzindo um resultado filtrado que é, então, a saída.

Formato de saída JSON

JSON é o formato de saída padrão da AWS CLI. A maioria das linguagens de programação pode facilmente decodificar strings JSON usando funções internas ou com bibliotecas disponíveis publicamente. É possível combinar a saída JSON com a opção --query de maneiras poderosas para filtrar e formatar a saída em formato JSON da AWS CLI.

Para filtragem mais avançada que talvez você não consiga fazer com --query, é possível considerar jq, um processador JSON da linha de comando. Baixe e localize o tutorial oficial em http://stedolan.github.io/jq/.

Veja a seguir um exemplo de saída JSON.


$ aws iam list-users --output json


{
    "Users": [
        {
            "Path": "/",
            "UserName": "Admin",
            "UserId": "AIDA1111111111EXAMPLE",
            "Arn": "arn:aws:iam::123456789012:user/Admin",
            "CreateDate": "2014-10-16T16:03:09+00:00",
            "PasswordLastUsed": "2016-06-03T18:37:29+00:00"
        },
        {
            "Path": "/backup/",
            "UserName": "backup-user",
            "UserId": "AIDA2222222222EXAMPLE",
            "Arn": "arn:aws:iam::123456789012:user/backup/backup-user",
            "CreateDate": "2019-09-17T19:30:40+00:00"
        },
        {
            "Path": "/",
            "UserName": "cli-user",
            "UserId": "AIDA3333333333EXAMPLE",
            "Arn": "arn:aws:iam::123456789012:user/cli-user",
            "CreateDate": "2019-09-17T19:11:39+00:00"
        }
    ]
}

Formato da saída YAML

O YAML é uma boa escolha para lidar com a saída programaticamente com serviços e ferramentas que emitem ou consomem strings no formato YAML, como o AWS CloudFormation com suporte para modelos no formato YAML.

Para filtragem mais avançada que talvez você não consiga fazer com --query, é possível considerar yq, um processador YAML da linha de comando. Você pode baixar yq no repositório yq no GitHub.

Veja a seguir um exemplo de saída YAML.


$ aws iam list-users --output yaml


Users:
- Arn: arn:aws:iam::123456789012:user/Admin
  CreateDate: '2014-10-16T16:03:09+00:00'
  PasswordLastUsed: '2016-06-03T18:37:29+00:00'
  Path: /
  UserId: AIDA1111111111EXAMPLE
  UserName: Admin
- Arn: arn:aws:iam::123456789012:user/backup/backup-user
  CreateDate: '2019-09-17T19:30:40+00:00'
  Path: /backup/
  UserId: AIDA2222222222EXAMPLE
  UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
- Arn: arn:aws:iam::123456789012:user/cli-user
  CreateDate: '2019-09-17T19:30:40+00:00'
  Path: /
  UserId: AIDA3333333333EXAMPLE
  UserName: cli-user

Formato da saída de fluxo do YAML

O formato yaml-stream se beneficia do YAML e oferece uma visualização mais ágil/rápida de grandes conjuntos de dados ao transmitir os dados para você. Você pode começar a visualizar e usar dados de YAML antes do download de toda a consulta.

A seguir, veja um exemplo de saída yaml-stream.


$ aws iam list-users --output yaml-stream


- IsTruncated: false
  Users:
  - Arn: arn:aws:iam::123456789012:user/Admin
    CreateDate: '2014-10-16T16:03:09+00:00'
    PasswordLastUsed: '2016-06-03T18:37:29+00:00'
    Path: /
    UserId: AIDA1111111111EXAMPLE
    UserName: Admin
  - Arn: arn:aws:iam::123456789012:user/backup/backup-user
    CreateDate: '2019-09-17T19:30:40+00:00'
    Path: /backup/
    UserId: AIDA2222222222EXAMPLE
    UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
  - Arn: arn:aws:iam::123456789012:user/cli-user
    CreateDate: '2019-09-17T19:30:40+00:00'
    Path: /
    UserId: AIDA3333333333EXAMPLE
    UserName: cli-user

Veja a seguir um exemplo de saída de yaml-stream usando o parâmetro --page-size para paginar o conteúdo YAML transmitido.


$ aws iam list-users --output yaml-stream --page-size 2


- IsTruncated: true
  Marker: ab1234cdef5ghi67jk8lmo9p/q012rs3t445uv6789w0x1y2z/345a6b78c9d00/1efgh234ij56klmno78pqrstu90vwxyx  
  Users:
  - Arn: arn:aws:iam::123456789012:user/Admin
    CreateDate: '2014-10-16T16:03:09+00:00'
    PasswordLastUsed: '2016-06-03T18:37:29+00:00'
    Path: /
    UserId: AIDA1111111111EXAMPLE
    UserName: Admin
  - Arn: arn:aws:iam::123456789012:user/backup/backup-user
    CreateDate: '2019-09-17T19:30:40+00:00'
    Path: /backup/
    UserId: AIDA2222222222EXAMPLE
    UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
- IsTruncated: false
  Users:
  - Arn: arn:aws:iam::123456789012:user/cli-user
    CreateDate: '2019-09-17T19:30:40+00:00'
    Path: /
    UserId: AIDA3333333333EXAMPLE
    UserName: cli-user

Formato de saída de texto

O formato text organiza a saída da AWS CLI em linhas delimitadas por tabulação. Isso funciona bem com ferramentas de texto Unix tradicionais, como grep, sed e awk, bem como o processamento de texto executado pelo PowerShell.

O formato de saída text segue a estrutura básica mostrada abaixo. As colunas são classificados alfabeticamente por nomes de chaves correspondentes subjacentes do objeto JSON.


IDENTIFIER  sorted-column1 sorted-column2
IDENTIFIER2 sorted-column1 sorted-column2

A seguir, veja um exemplo de saída text. Cada campo é separado dos outros por tabulação, com uma guia adicional na qual há um campo vazio.


$ aws iam list-users --output text


USERS   arn:aws:iam::123456789012:user/Admin                2014-10-16T16:03:09+00:00   2016-06-03T18:37:29+00:00   /          AIDA1111111111EXAMPLE   Admin
USERS   arn:aws:iam::123456789012:user/backup/backup-user   2019-09-17T19:30:40+00:00                               /backup/   AIDA2222222222EXAMPLE   backup-user
USERS   arn:aws:iam::123456789012:user/cli-user             2019-09-17T19:11:39+00:00                               /          AIDA3333333333EXAMPLE   cli-user

A quarta coluna é o campo PasswordLastUsed e está vazia nas duas últimas entradas porque esses usuários nunca fazem login no AWS Management Console.

Importante

É altamente recomendável que, se você especificar uma saída text, também use sempre a opção --query para garantir um comportamento consistente.

Isso ocorre porque o formato de texto ordena alfabeticamente as colunas da saída pelo nome da chave do objeto JSON subjacente retornado pelo serviço da AWS, e recursos similares podem não têm os mesmos nomes de chave. Por exemplo, a representação JSON de uma instância do Amazon EC2 baseada em Linux pode ter elementos que não estão presentes na representação JSON de uma instância baseada em Windows ou vice-versa. Além disso, os recursos podem ter elementos de valores de chave adicionados ou removidos em futuras atualizações, alterando a ordem das colunas. Este é o local em que --query expande a funcionalidade da saída text para fornecer total controle sobre o formato de saída.

No exemplo a seguir, o comando especifica quais elementos devem ser exibidos e define a ordem das colunas com a notação da lista [key1, key2, ...]. Isso oferece a você a segurança de que os valores de chave corretos sempre serão exibido na coluna esperada. Por fim, observe como a AWS CLI resulta em None como os valores para as chaves que não existem.


$ aws iam list-users --output text --query 'Users[*].[UserName,Arn,CreateDate,PasswordLastUsed,UserId]'


Admin         arn:aws:iam::123456789012:user/Admin         2014-10-16T16:03:09+00:00   2016-06-03T18:37:29+00:00   AIDA1111111111EXAMPLE
backup-user   arn:aws:iam::123456789012:user/backup-user   2019-09-17T19:30:40+00:00   None                        AIDA2222222222EXAMPLE
cli-user      arn:aws:iam::123456789012:user/cli-backup    2019-09-17T19:11:39+00:00   None                        AIDA3333333333EXAMPLE

O exemplo a seguir mostra como você pode usar grep e awk com a saída text do comando aws ec2 describe-instances. O primeiro comando exibe a zona de disponibilidade, o estado atual e o ID de cada instância na saída text. O segundo comando processa essa saída para exibir somente os IDs de todas as instâncias em execução na Zona de disponibilidade us-west-2a.


$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text


us-west-2a      running i-4b41a37c
us-west-2a      stopped i-a071c394
us-west-2b      stopped i-97a217a0
us-west-2a      running i-3045b007
us-west-2a      running i-6fc67758


$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text | grep us-west-2a | grep running | awk '{print $3}'


i-4b41a37c
i-3045b007
i-6fc67758

O exemplo a seguir vai mais longe e mostra não apenas como filtrar a saída, mas como usar essa saída para automatizar a alteração dos tipos de instância para cada instância interrompida.


$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[State.Name, InstanceId]' --output text |
> grep stopped |
> awk '{print $2}' |
> while read line;
> do aws ec2 modify-instance-attribute --instance-id $line --instance-type '{"Value": "m1.medium"}';
> done

A saída text também pode ser útil no PowerShell. Como as colunas na saída text são delimitadas por tabulação, é possível dividir facilmente a saída em uma matriz usando o delimitador `t do PowerShell. O comando a seguir exibe o valor da terceira coluna (InstanceId) se a primeira coluna (AvailabilityZone) corresponder à string us-west-2a.


PS C:\>aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text |
%{if ($_.split("`t")[0] -match "us-west-2a") { $_.split("`t")[2]; } }


-4b41a37c
i-a071c394
i-3045b007
i-6fc67758

Embora o exemplo anterior mostre como usar o parâmetro --query para analisar os objetos JSON subjacentes e extrair a coluna desejada, o PowerShell tem capacidade própria para lidar com o JSON, se a compatibilidade entre as plataformas não for uma preocupação. Em vez de lidar com a saída como texto, o que é exigido pela maioria dos shells de comando, o PowerShell permite que você use o cmdlet ConvertFrom-JSON para produzir um objeto estruturado hierarquicamente. Depois, é possível acessar diretamente o membro desejado usando esse objeto.


(aws ec2 describe-instances --output json | ConvertFrom-Json).Reservations.Instances.InstanceId

dica

Se você enviar o texto e filtrar a saída para um único campo usando o parâmetro --query, a saída será uma única linha de valores separados por tabulação. Para obter cada valor em uma linha separada, você pode colocar o campo de saída entre colchetes, conforme mostrado nos exemplos a seguir.

Saída de linha única separada por tabulação:


$ aws iam list-groups-for-user --user-name susan  --output text --query "Groups[].GroupName"


HRDepartment    Developers      SpreadsheetUsers  LocalAdmins

Cada valor em sua própria linha, colocando [GroupName] entre colchetes:


$ aws iam list-groups-for-user --user-name susan  --output text --query "Groups[].[GroupName]"


HRDepartment
Developers
SpreadsheetUsers
LocalAdmins

Formato de saída de tabela

O formato table produz representações legíveis da saída complexa da AWS CLI em um formato tabular.


$ aws iam list-users --output table


-----------------------------------------------------------------------------------------------------------------------------------------------------------------
|                                                                                 ListUsers                                                                     |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
||                                                                                  Users                                                                      ||
|+----------------------------------------------------+---------------------------+---------------------------+----------+-----------------------+-------------+|
||                         Arn                        |       CreateDate          |    PasswordLastUsed       |   Path   |        UserId         |   UserName  ||
|+----------------------------------------------------+---------------------------+---------------------------+----------+-----------------------+-------------+|
||  arn:aws:iam::123456789012:user/Admin              | 2014-10-16T16:03:09+00:00 | 2016-06-03T18:37:29+00:00 | /        | AIDA1111111111EXAMPLE | Admin       ||
||  arn:aws:iam::123456789012:user/backup/backup-user | 2019-09-17T19:30:40+00:00 |                           | /backup/ | AIDA2222222222EXAMPLE | backup-user ||
||  arn:aws:iam::123456789012:user/cli-user           | 2019-09-17T19:11:39+00:00 |                           | /        | AIDA3333333333EXAMPLE | cli-user    ||
+---------------------------------------------------------------------------------------------------------------------------------------------------------------+

É possível combinar a opção --query com o formato table para exibir um conjunto de elementos pré-selecionado na saída bruta. As diferenças das saída entre as notações de lista e dicionário: no primeiro exemplo, os nomes de coluna são ordenados alfabeticamente, e, no segundo, as colunas sem nome são ordenadas conforme definido pelo usuário. Para obter mais informações sobre a opção --query, consulte AWS CLI Saída do filtro.


$ aws ec2 describe-volumes --query 'Volumes[*].{ID:VolumeId,InstanceId:Attachments[0].InstanceId,AZ:AvailabilityZone,Size:Size}' --output table


------------------------------------------------------
|                   DescribeVolumes                  | 
+------------+----------------+--------------+-------+
|     AZ     |      ID        | InstanceId   | Size  |
+------------+----------------+--------------+-------+
|  us-west-2a|  vol-e11a5288  |  i-a071c394  |  30   |
|  us-west-2a|  vol-2e410a47  |  i-4b41a37c  |  8    |
+------------+----------------+--------------+-------+


$ aws ec2 describe-volumes --query 'Volumes[*].[VolumeId,Attachments[0].InstanceId,AvailabilityZone,Size]' --output table


----------------------------------------------------
|                  DescribeVolumes                 |
+--------------+--------------+--------------+-----+
|  vol-e11a5288|  i-a071c394  |  us-west-2a  |  30 |
|  vol-2e410a47|  i-4b41a37c  |  us-west-2a  |  8  |
+--------------+--------------+--------------+-----+

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Controlar a saída do comando

Paginação