# Definição do formato da saída na 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`](#json-output)**: a saída é formatada como uma string [JSON](https://json.org/). + **[`yaml`](#yaml-output)**: a saída é formatada como uma string [YAML](https://yaml.org/). + **[`yaml-stream`](#yaml-stream-output)**: a saída é transmitida e formatada como uma string [YAML](https://yaml.org/). A transmissão possibilita um manuseio mais rápido de tipos de dados grandes. + **[`text`](#text-output)** – 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`](#table-output)** – a saída é formatada como uma tabela usando os caracteres \$1\$1- 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. + **[`off`](#off-output)**: a saída suprime todas as saídas de comando para stdout. Isso é útil em scripts de automação e pipelines de CI/CD em que somente é necessário verificar o código de saída do comando sem processar a saída. ## Como selecionar o formato de saída Como explicado no tópico sobre [configuração](cli-chap-configure.md), 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](https://json.org) é 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](cli-usage-filter.md) 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/](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](https://yaml.org) é uma boa escolha para lidar com a saída programaticamente com serviços e ferramentas que emitem ou consomem strings no formato [YAML](https://yaml.org), como o CloudFormation com suporte para [modelos no formato YAML](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-formats.html). 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](https://github.com/mikefarah/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](https://yaml.org) 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. Você pode baixar `yq` no [repositório yq](https://github.com/mikefarah/yq) no *GitHub.* 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 Console de gerenciamento da AWS. **Importante** *É altamente recomendável que, se você especificar uma saída `text`, também use sempre a opção [`--query`](cli-usage-filter.md) 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 [Filtrar a saída na AWS CLI](cli-usage-filter.md). ``` $ 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 | +--------------+--------------+--------------+-----+ ``` ## Formato de off O formato `off` suprime todas as saídas de comando para stdout. Isso é útil em scripts de automação e pipelines de CI/CD em que somente é necessário verificar o código de saída do comando sem processar a saída. As mensagens de erro ainda são exibidas em stderr. O exemplo a seguir mostra como o formato `off` suprime saídas bem-sucedidas. É possível verificar o código de saída para determinar o houve êxito: ``` $ aws s3api list-buckets --output off $ echo $? 0 ``` Isso é particularmente útil em scripts de shell em que se deseja verificar a existência de um recurso sem capturar a saída: ``` #!/bin/bash if aws s3api head-bucket --bucket my-bucket --output off 2>/dev/null; then echo "Bucket exists" else echo "Bucket does not exist" fi ``` **nota** O formato `off` suprime apenas stdout. Os erros ainda são gravados em stderr.