Definição do formato da saída da AWS CLI - AWS Command Line Interface

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

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. É possível fazer download dele e encontrar a documentação em https://mikefarah.gitbook.io/yq/.

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.

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. É possível fazer download dele e encontrar a documentação em http://mikefarah.github.io/yq/.

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 Filtragem da saída da AWS CLI.

$ 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 | +--------------+--------------+--------------+-----+