# Controle de saída do comando na AWS CLI
Esta seção descreve as diferentes maneiras de controlar a saída da AWS Command Line Interface (AWS CLI). Personalizar a saída da AWS CLI em seu terminal pode melhorar a legibilidade, simplificar a automação de scripts e facilitar a navegação em conjuntos de dados maiores.
A AWS CLI aceita vários [formatos de saída](cli-usage-output-format.md), como [`json`](cli-usage-output-format.md#json-output), [`text`](cli-usage-output-format.md#text-output), [`yaml`](cli-usage-output-format.md#yaml-output), [`off`](cli-usage-output-format.md#off-output) e [`table`](cli-usage-output-format.md#table-output). Alguns serviços têm [paginação](cli-usage-pagination.md) do lado do servidor para seus dados e a AWS CLI fornece seus próprios recursos do lado do cliente para opções adicionais de paginação.
Por último, a AWS CLI com [filtragem nos lados do servidor e do cliente](cli-usage-filter.md) que você pode usar individualmente ou em conjunto para filtrar a saída da sua AWS CLI.
**Topics**
+ [Saída confidencial](#cli-usage-output-sensitive)
+ [Opções de saída do lado do servidor e do lado do cliente](#cli-usage-output-server-client)
+ [Definição do formato da saída na AWS CLI](cli-usage-output-format.md)
+ [Saída de erro estruturada na AWS CLI](cli-usage-error-format.md)
+ [Usar as opções de paginação na AWS CLI](cli-usage-pagination.md)
+ [Filtrar a saída na AWS CLI](cli-usage-filter.md)
## Saída confidencial
Algumas operações da AWS CLI podem retornar informações que podem ser consideradas confidenciais, incluindo informações de variáveis de ambiente. A exposição dessas informações pode representar um risco de segurança em determinados cenários; por exemplo, as informações podem ser incluídas nos logs de integração contínua e implantação contínua (CI/CD). Portanto, é importante que você revise quando está incluindo essa saída como parte de seus logs e suprima a saída quando não for necessária.
Para obter informações adicionais sobre a proteção de dados confidenciais, consulte [Proteção de dados no AWS CLI](data-protection.md).
Considere as seguintes práticas recomendadas:
+ Considere recuperar programaticamente seus segredos de um repositório de segredos, como o AWS Secrets Manager.
+ Analise o conteúdo dos seus logs de compilação para garantir que não contenham informações confidenciais. Considere abordagens como canalizar para `/dev/null` ou capturar a saída como uma variável bash ou PowerShell para suprimir as saídas do comando.
Veja a seguir um exemplo de bash para redirecionar a saída, mas não os erros, para `/dev/null`:
```
$ aws s3 ls > /dev/null
```
Para obter detalhes sobre como suprimir a saída do seu terminal, consulte a documentação do usuário do terminal que você usa.
+ Considere o acesso aos seus logs e defina o escopo do acesso de acordo com seu caso de uso.
## Opções de saída do lado do servidor e do lado do cliente
A AWS CLI conta com [filtragem nos lados do servidor e do cliente](cli-usage-filter.md) que você pode usar individualmente ou em conjunto para filtrar sua saída da AWS CLI. A filtragem no lado do servidor é processada primeiro e retorna a saída para a filtragem no lado do cliente. A filtragem no lado do servidor é compatível com a API do serviço. A filtragem no lado do cliente é suportada pelo cliente da AWS CLI com o parâmetro `--query`.
As opções de saída **do lado do servidor** são recursos diretamente compatíveis com a API do AWS service (Serviço da AWS). Os dados filtrados ou paginados não são enviados ao cliente, o que pode acelerar os tempos de resposta HTTP e melhorar a largura de banda para conjuntos de dados maiores.
As opções de saída **do lado do cliente** são recursos criados pela AWS CLI. Todos os dados são enviados ao cliente e, em seguida, a AWS CLI filtra ou realiza a paginação do conteúdo exibido. As operações do lado do cliente não economizam velocidade ou largura de banda para conjuntos de dados maiores.
Quando as opções do lado do servidor e do lado do cliente são usadas juntas, as operações do lado do servidor são concluídas primeiro e depois enviadas ao cliente para operações do lado do cliente. Essa ação usa a economia em potencial de velocidade e largura de banda das opções do lado do servidor, enquanto usa recursos adicionais da AWS CLI para obter a saída desejada.
# 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.
# Saída de erro estruturada na AWS CLI
Este tópico descreve os formatos de saída de erro estruturada para a AWS Command Line Interface (AWS CLI). A CLI grava erros em stderr e aceita os seguintes formatos:
+ **[`enhanced`](#cli-error-format-enhanced)** (padrão): mensagem de erro com detalhes adicionais exibidos em linha. Use para depuração legível por humanos.
+ **[`json`](#cli-error-format-json)**: a saída é formatada como uma string [JSON](https://json.org/) com todos os campos de erro. Use para automação e criação de scripts.
+ **[`yaml`](#cli-error-format-yaml)**: a saída é formatada como uma string [YAML](https://yaml.org/) com todos os campos de erro. Use para automação e criação de scripts.
+ **[`text`](#cli-error-format-text)**: formata erros usando o formatador de texto. Use para verificação visual rápida.
+ **[`table`](#cli-error-format-table)**: formata erros usando o formatador de tabela. Use para verificação visual rápida.
+ **[`legacy`](#cli-error-format-legacy)**: formato de erro original sem detalhes estruturados. Use para compatibilidade com versões anteriores.
## Configurar o formato do erro
É possível configurar o formato do erro usando qualquer um dos seguintes métodos:
Sinalizador da linha de comandos
```
$ aws --cli-error-format json
```
Arquivo de configuração: (`~/.aws/config`)
```
[default]
cli_error_format = json
```
Variável de ambiente
```
$ export AWS_CLI_ERROR_FORMAT=yaml
```
## Formato de saída de erro
As seguintes seções descrevem cada formato.
### Formato aprimorado (padrão)
O formato aprimorado exibe mensagens de erro com detalhes adicionais em linha para valores simples. Para estruturas complexas, o formato fornece uma dica para usar JSON ou YAML.
**Exemplo: configuração de região ausente**
```
aws: [ERROR]: An error occurred (NoRegion): You must specify a region. You can also configure your region by running "aws configure".
```
**Exemplo: bucket do S3 inexistente com campos adicionais**
```
aws: [ERROR]: An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist
Additional error details:
BucketName: amzn-s3-demo-bucket
```
**Exemplo: campos de erro complexos**
```
An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]
Additional error details:
CancellationReasons:
Use "--cli-error-format json" or another error format to see the full details.
```
### Formato JSON
O formato JSON fornece uma representação estruturada com todos os campos de erro.
**Exemplo: configuração de região ausente**
```
{
"Code": "NoRegion",
"Message": "You must specify a region. You can also configure your region by running \"aws configure\"."
}
```
**Exemplo: bucket do S3 inexistente**
```
{
"Code": "NoSuchBucket",
"Message": "The specified bucket does not exist",
"BucketName": "amzn-s3-demo-bucket"
}
```
### Formato YAML
O formato YAML fornece uma representação estruturada com todos os campos de erro.
**Exemplo: configuração de região ausente**
```
Code: NoRegion
Message: You must specify a region. You can also configure your region by running "aws configure".
```
**Exemplo: bucket do S3 inexistente**
```
Code: NoSuchBucket
Message: The specified bucket does not exist
BucketName: amzn-s3-demo-bucket
```
### Formato de texto
O formato de texto usa o mesmo formatador usado para uma saída bem-sucedida do comando.
**Exemplo: bucket do S3 inexistente**
```
amzn-s3-demo-bucket NoSuchBucket The specified bucket does not exist
```
### Formato da tabela
O formato de tabela usa o mesmo formatador usado para uma saída bem-sucedida do comando.
**Exemplo: bucket do S3 inexistente**
```
-------------------------------------------------------------------------------------|
| error |
+---------------------------+---------------+----------------------------------------+
| BucketName | Code | Message |
+---------------------------+---------------+----------------------------------------+
| amzn-s3-demo-bucket | NoSuchBucket | The specified bucket does not exist |
+---------------------------+---------------+----------------------------------------+
```
### Formato legado
O formato legado fornece o formato de erro original sem detalhes estruturados. Esse formato não inclui o prefixo “An error occurred (ErrorCode):” para exceções da CLI.
**Exemplo: configuração de região ausente**
```
aws: [ERROR]: You must specify a region. You can also configure your region by running "aws configure".
```
**Exemplo: bucket do S3 inexistente**
```
An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist
```
**nota**
Agora os erros incluem consistentemente o prefixo `aws: [ERROR]:` para exceções da CLI. As versões anteriores nem sempre incluíam esse prefixo.
As seguintes exceções sempre usam o formato legado, independentemente do formato de erro configurado:
`UnknownArgumentError`: exibe informações de uso.
Interrupções do teclado (`KeyboardInterrupt`)
## Exemplo completo
O seguinte exemplo mostra um comando com a formatação de erro JSON.
```
$ aws s3api get-object \
--bucket amzn-s3-demo-bucket \
--key file.txt out.txt \
--cli-error-format json
```
Saída (stderr):
```
{
"Code": "NoSuchBucket",
"Message": "The specified bucket does not exist",
"BucketName": "amzn-s3-demo-bucket"
}
```
O campo `BucketName` é um membro de erro modelado exibido pelo serviço Amazon S3.
# Usar as opções de paginação na AWS CLI
Este tópico descreve as diferentes maneiras de paginar a saída da AWS Command Line Interface (AWS CLI).
Há duas formas principais de controlar a paginação pela AWS CLI.
+ [Usando os parâmetros de paginação do lado do servidor.](#cli-usage-pagination-serverside)
+ [Usando o programa de paginação do lado do cliente de saída padrão](#cli-usage-pagination-clientside).
Os parâmetros de paginação do lado do servidor são processados primeiro, e qualquer saída é enviada para a paginação do lado do cliente.
## Paginação do lado do servidor
Para a maioria dos comandos que retornam uma extensa lista de itens, a AWS CLI oferece várias opções do lado do servidor para controlar o número de itens incluídos na saída quando a AWS CLI chama a API de um serviço para preencher a lista. A paginação do lado do servidor na AWS CLI é habilitada pela API do serviço da AWS; portanto, essas opções só funcionarão se a API de serviço as habilitar.
**Topics**
+ [--no-paginate](#cli-usage-pagination-nopaginate)
+ [--page-size](#cli-usage-pagination-pagesize)
+ [--max-items](#cli-usage-pagination-maxitems)
+ [--starting-token](#cli-usage-pagination-startingtoken)
Por padrão, a AWS CLI usa um tamanho de página determinado pelo serviço específico e recupera todos os itens disponíveis. Por exemplo, o Amazon S3 tem um tamanho de página padrão de mil. Se você executar `aws s3api list-objects` em um bucket do Amazon S3 que contém 3,5 mil objetos, a AWS CLI fará automaticamente quatro chamadas para o Amazon S3, lidando com a lógica de paginação específica do serviço para você em segundo plano e retornando todos os 3,5 mil objetos na saída final.
Consulte informações sobre se um comando específico oferece paginação do lado do servidor no [Guia de referência da AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/reference/index.html).
### Como usar o parâmetro –no-paginate
A opção `--no-paginate` desabilita os seguintes tokens de paginação no lado do cliente. Ao usar um comando, por padrão a AWS CLI faz várias chamadas automaticamente para retornar todos os resultados possíveis para criar a paginação. Uma chamada para cada página. Desabilitar a paginação faz com que a AWS CLI chame apenas uma vez pela primeira página de resultados do comando.
Por exemplo, se você executar o`aws s3api list-objects` em um bucket do Amazon S3 que contém 3500 objetos, o AWS CLI fará apenas a primeira chamada para o Amazon S3, retornando apenas os primeiros 1000 objetos na saída final.
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--no-paginate
{
"Contents": [
...
```
### Como usar o parâmetro --page-size
Caso haja problemas ao executar os comandos da lista em um grande número de recursos, o tamanho da página padrão poderá ser muito alto. Isso pode fazer com que as chamadas para os serviços do AWS excedam o tempo máximo permitido e gerar um erro de “expiração”. Você pode usar a opção `--page-size` para especificar que a AWS CLI solicite um número menor de itens de cada chamada para o serviço da AWS. A AWS CLI ainda recuperará a lista completa, mas executará um número maior de chamadas de API de serviço em segundo plano e recuperará um número menor de itens em cada chamada. Isso fornece às chamadas individuais chances melhores de sucesso sem um tempo limite. Alterar o tamanho da página não afeta a saída, afeta somente o número de chamadas da API que precisam ser feitas para gerar a saída.
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--page-size 100
{
"Contents": [
...
```
### Como usar o parâmetro --max-items
Para incluir menos itens por vez na saída da AWS CLI, use a opção `--max-items`. A AWS CLI ainda lida com paginação com o serviço conforme descrito anteriormente, mas imprime apenas o número de itens que você especificar de cada vez.
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--max-items 100
{
"NextToken": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==",
"Contents": [
...
```
### Como usar o parâmetro --starting-token
Se o número de saída de itens (`--max-items`) for menor do que o número total de itens retornados pelas chamadas de API subjacentes, a saída incluirá um `NextToken` que pode ser passado para um comando subsequente para recuperar o próximo conjunto de itens. O exemplo a seguir mostra como usar o valor `NextToken` retornado pelo exemplo anterior e permite que você recupere os segundos 100 itens.
**nota**
O parâmetro `--starting-token` não pode ser nulo nem vazio. Se o comando anterior não retornar um valor `NextToken`, não haverá mais itens a serem retornados e você não precisará chamar o comando novamente.
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--max-items 100 \
--starting-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==
{
"Contents": [
...
```
O serviço da AWS especificado pode não retornar itens na mesma ordem cada vez que você chamá-lo. Se você especificar valores diferentes para `--page-size` e `--max-items`, poderá obter resultados inesperados com itens ausentes ou duplicados. Para evitar que isso aconteça, use o mesmo número para `--page-size` e `--max-items` para sincronizar a paginação da AWS CLI com a paginação do serviço subjacente. Também é possível recuperar a lista completa e executar quaisquer operações necessárias de paginação localmente.
## Paginação do lado do cliente
AWS CLIA versão 2 fornece um programa de paginação do lado do cliente para uso na saída. Por padrão, o atributo retorna toda a saída pelo programa de paginação padrão do sistema operacional.
Em ordem de precedência, você pode especificar a paginação de saída destas duas formas:
+ Usando a configuração `cli_pager` no arquivo `config` no perfil `default` ou nomeado.
+ Usando a variável de ambiente `AWS_PAGER`.
+ Usando a variável de ambiente `PAGER`.
Por ordem de precedência, você pode desabilitar todo o uso de um programa de paginação externo das seguintes maneiras:
+ Usar opção de linha de comando `--no-cli-pager` para desabilitar a paginação para o uso de um único comando.
+ Definir a configuração `cli_pager` ou a variável `AWS_PAGER` como uma string vazia.
**Topics**
+ [cli\$1pager](#cli-usage-pagination-clipager)
+ [AWS\$1PAGER](#cli-usage-pagination-awspager)
+ [--no-cli-pager](#cli-usage-pagination-noclipager)
+ [Sinalizadores de paginação](#cli-usage-pagination-flags)
### Como usar a configuração cli\$1pager
Você pode salvar as definições de configuração usadas com frequência e credenciais em arquivos que são mantidos pela AWS CLI. As configurações em um perfil de nome têm precedência sobre as configurações no perfil `default`. Para obter mais informações sobre as opções de configuração, consulte [Configurações do arquivo de configuração e credenciais na AWS CLI](cli-configure-files.md).
O exemplo a seguir define a paginação de saída padrão para o programa `less`.
```
[default]
cli_pager=less
```
O exemplo abaixo define o padrão para desativar o uso de um paginador.
```
[default]
cli_pager=
```
### Como definir a variável de ambiente AWS\$1PAGER
O exemplo a seguir define a paginação de saída padrão para o programa `less`. Para obter mais informações sobre variáveis de ambiente, consulte [Configurar variáveis de ambiente para a AWS CLI](cli-configure-envvars.md).
------
#### [ Linux and macOS ]
```
$ export AWS_PAGER="less"
```
------
#### [ Windows ]
```
C:\> setx AWS_PAGER "less"
```
------
### Como usar a opção --no-cli-pager
Para desabilitar o uso de uma paginação em um único comando, use a opção `--no-cli-pager`. Para obter mais informações sobre as opções de linha de comando, consulte [Opções da linha de comando na AWS CLI](cli-configure-options.md).
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--no-cli-pager
{
"Contents": [
...
```
### Como usar sinalizadores de paginação
Você pode especificar sinalizadores para usar automaticamente com seu programa de paginação. Os sinalizadores dependem do programa de paginação utilizado. Os exemplos abaixo são referem-se aos padrões típicos de `less` e `more`.
------
#### [ Linux and macOS ]
Se você não especificar o contrário, o paginador que a AWS CLI versão 2 usará por padrão é `less`. Se você não tiver a variável de ambiente `LESS` definida, a AWS CLI versão 2 usará os sinalizadores `FRX`. Você pode combinar sinalizadores especificando-os ao definir a paginação AWS CLI.
O exemplo a seguir usa o sinalizador `S`. Esse sinalizador então se combina aos sinalizadores `FRX` padrão para criar um sinalizador `FRXS`.
```
$ export AWS_PAGER="less -S"
```
Caso não queira usar nenhum dos sinalizadores `FRX`, você poderá negá-los. O exemplo a seguir nega o sinalizador `F` para criar um sinalizador `RX` final.
```
$ export AWS_PAGER="less -+F"
```
Para obter mais informações sobre sinalizadores `less`, consulte [less](http://manpages.org/less/1#options) em *manpages.org*.
------
#### [ Windows ]
Se você não especificar o contrário, o paginador que a AWS CLI versão 2 usará por padrão é `more` sem sinalizadores adicionais.
O exemplo a seguir usa o parâmetro `/c`.
```
C:\> setx AWS_PAGER "more /c"
```
Para obter mais informações sobre sinalizadores `more`, consulte `[more](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/more)` nos *Documentos da Microsoft*.
------
# Filtrar a saída na AWS CLI
A AWS Command Line Interface (AWS CLI) conta com filtragem nos lados do servidor e do cliente que você pode usar individualmente ou em conjunto para filtrar sua saída da AWS CLI. A filtragem no lado do servidor é processada primeiro e retorna a saída para a filtragem no lado do cliente.
+ A filtragem no lado do servidor é suportada pela API, e você geralmente a implementa com um parâmetro `--filter`. O serviço retorna apenas resultados correspondentes que podem acelerar os tempos de resposta de HTTP para conjuntos de dados grandes.
+ A filtragem no lado do cliente é suportada pelo cliente da AWS CLI com o parâmetro `--query`. Esse parâmetro oferece recursos que a filtragem do lado do servidor pode não ter.
**Topics**
+ [Filtragem no lado do servidor](#cli-usage-filter-server-side)
+ [Filtragem no lado do cliente](#cli-usage-filter-client-side)
+ [Combinação das filtragens no lado do servidor e no lado do cliente](#cli-usage-filter-combining)
+ [Recursos adicionais](#cli-usage-filter-resources)
## Filtragem no lado do servidor
A filtragem no lado do servidor na AWS CLI é fornecida pela API do serviço AWS. O serviço da AWS retorna apenas os registros na resposta HTTP que correspondem ao seu filtro, o que pode acelerar os tempos de resposta de HTTP para conjuntos de dados grandes. Como a filtragem no lado do servidor é definida pela API do serviço, os nomes e funções dos parâmetros variam entre os serviços. Alguns nomes de parâmetros comuns usados na filtragem são:
+ `--filter`, como [ses](https://docs.aws.amazon.com/cli/latest/reference/ses/create-receipt-filter.html) e [ce](https://docs.aws.amazon.com/cli/latest/reference/ce/get-cost-and-usage.html).
+ `--filters`, como [ec2](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-volumes.html), [autoscaling](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/describe-tags.html) e [rds](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html).
+ Nomes que começam com a palavra `filter`; por exemplo, `--filter-expression` para o comando [https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html).
Para ter informações sobre se um comando específico oferece filtragem no lado do servidor e a respeito das regras de filtragem, consulte o [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/reference/index.html).
## Filtragem no lado do cliente
A AWS CLI fornece recursos de filtragem integrada baseados em JSON no lado do cliente com o parâmetro`--query`. O parâmetro `--query` é uma ferramenta poderosa que você pode usar para personalizar o conteúdo e estilo da sua saída. O parâmetro `--query` recebe a resposta HTTP retornada pelo servidor e filtra os resultados antes de exibi-los. Como toda a resposta HTTP é enviada para o cliente antes da filtragem, a filtragem no lado do cliente pode ser mais lenta do que a filtragem no lado do servidor para conjuntos de dados grandes.
A consulta usa a [sintaxe JMESPath](https://jmespath.org/) para criar expressões para filtrar sua saída. Para aprender a sintaxe JMESPath, consulte o [Tutorial](https://jmespath.org/tutorial.html) no *site do JMESPath*.
**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.
**Topics**
+ [Antes de começar](#cli-usage-filter-client-side-output)
+ [Identificadores](#cli-usage-filter-client-side-identifiers)
+ [Como selecionar em uma lista](#cli-usage-filter-client-side-select-list)
+ [Como filtrar dados aninhados](#cli-usage-filter-client-side-nested)
+ [Resultados da simplificação](#cli-usage-filter-client-side-specific-flattening)
+ [Filtragem de valores específicos](#cli-usage-filter-client-side-specific-values)
+ [Encadeamento de expressões](#cli-usage-filter-client-side-pipe)
+ [Filtragem por vários valores de identificador](#cli-usage-filter-client-side-miltiselect-list)
+ [Adição de rótulos a valores de identificador](#cli-usage-filter-client-side-multiselect-hash)
+ [Funções](#cli-usage-filter-client-side-functions)
+ [Exemplos avançados `--query`](#cli-usage-filter-client-side-advanced)
### Antes de começar
**nota**
Esses exemplos de expressão de filtro são escritos para shells básicos do tipo Linux. Ao usar esses exemplos, use as regras de aspas corretas para o shell do terminal. A forma como o terminal interpreta as entradas pode mudar muito o que é enviado à AWS CLI. A forma como o terminal lê aspas simples `'`, aspas duplas `"` ou acentos graves ``` pode alterar a maneira como o conteúdo é lido.
Para obter mais informações, consulte [Usar aspas e literais com strings na AWS CLI](cli-usage-parameters-quoting-strings.md).
A saída JSON a seguir mostra um exemplo do que o parâmetro `--query` pode produzir. A saída descreve três volumes do Amazon EBS anexados a instâncias separadas do Amazon EC2.
#### Exemplo de saída
```
$ aws ec2 describe-volumes
{
"Volumes": [
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-2e410a47",
"State": "in-use",
"SnapshotId": "snap-708e8348",
"CreateTime": "2013-09-18T20:26:15.000Z",
"Size": 8
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
}
```
### Identificadores
Identificadores são rótulos para valores de saída. Ao criar filtros, você usa identificadores para refinar os resultados da consulta. No exemplo de saída a seguir, todos os identificadores como `Volumes`, `AvailabilityZone` e `AttachTime` estão destacados.
```
$ aws ec2 describe-volumes
{
"Volumes": [
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-2e410a47",
"State": "in-use",
"SnapshotId": "snap-708e8348",
"CreateTime": "2013-09-18T20:26:15.000Z",
"Size": 8
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
}
```
Para obter mais informações, consulte [Identificadores](https://jmespath.org/specification.html#identifiers ) no *site do JMESPath*.
### Como selecionar em uma lista
Uma lista ou matriz é um identificador que é seguido por um colchete “`[`“, como `Volumes` e `Attachments` na [Antes de começar](#cli-usage-filter-client-side-output).
**Sintaxe**
```
[ ]
```
Para filtrar toda a saída de uma matriz, você pode usar a notação curinga. Expressões [curinga](http://jmespath.org/specification.html#wildcard-expressions) são expressões usadas para retornar elementos usando a notação `*`.
O exemplo a seguir consulta todo o conteúdo `Volumes`.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
```
Para exibir um volume específico na matriz por índice, chame o índice da matriz. Por exemplo, o primeiro item na matriz `Volumes` tem um índice igual a 0, o que resulta na consulta `Volumes[0]`. Para obter mais informações sobre índices de matriz, consulte [Expressões de índice](http://jmespath.org/specification.html#index-expressions) no *site do JMESPath*.
```
$ aws ec2 describe-volumes \
--query 'Volumes[0]'
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
}
```
Para exibir um intervalo específico de volumes por índice, use `slice` com a sintaxe a seguir, em que **start** é o índice da matriz inicial, **stop** é o índice em que o filtro interrompe o processamento e **step** é o intervalo de salto.
**Sintaxe**
```
[::]
```
Se algum deles for omitido da expressão slice, os seguintes valores padrão serão usados:
+ Start: o primeiro índice na lista, 0.
+ Stop: o último índice na lista.
+ Step: sem pular etapas, onde o valor é 1.
Para retornar somente os dois primeiros volumes, use um valor de start igual a 0, um valor de stop igual 2 e um valor de step igual a 1, conforme mostrado no exemplo a seguir.
```
$ aws ec2 describe-volumes \
--query 'Volumes[0:2:1]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-2e410a47",
"State": "in-use",
"SnapshotId": "snap-708e8348",
"CreateTime": "2013-09-18T20:26:15.000Z",
"Size": 8
}
]
```
Como este exemplo contém valores padrão, você pode encurtar o slice de `Volumes[0:2:1]` para `Volumes[:2]`.
O exemplo a seguir omite valores padrão e retorna cada dois volumes em toda a matriz.
```
$ aws ec2 describe-volumes \
--query 'Volumes[::2]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
```
Os valores de step também podem ser números negativos, o que resulta na filtragem em ordem inversa de uma matriz, conforme mostrado no exemplo a seguir.
```
$ aws ec2 describe-volumes \
--query 'Volumes[::-2]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
}
]
```
Para obter mais informações, consulte [Slices](https://jmespath.org/specification.html#slices) no *site do JMESPath*.
### Como filtrar dados aninhados
Para refinar a filtragem de `Volumes[*]` para valores aninhados, use subexpressões anexando um ponto e seus critérios de filtragem.
**Sintaxe**
```
.
```
O exemplo a seguir mostra todas as informações de `Attachments` para todos os volumes.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments'
[
[
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
[
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
[
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
]
]
```
Para filtrar ainda mais os valores aninhados, acrescente a expressão para cada identificador aninhado. O exemplo a seguir lista o `State` para todos os `Volumes`.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[*].State'
[
[
"attached"
],
[
"attached"
],
[
"attached"
]
]
```
### Resultados da simplificação
Para obter mais informações, consulte [Subexpressões](https://jmespath.org/specification.html#subexpressions) no *site do JMESPath*.
Você pode simplificar os resultados para `Volumes[*].Attachments[*].State` removendo a notação curinga, o que resultará na consulta `Volumes[*].Attachments[].State`. A simplificação muitas vezes é útil para melhorar a legibiliade dos resultados.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[].State'
[
"attached",
"attached",
"attached"
]
```
Para obter mais informações, consulte [Simplificação](https://jmespath.org/specification.html#flatten) no *site do JMESPath*.
### Filtragem de valores específicos
Para filtrar valores específicos em uma lista, use uma expressão de filtro como mostrado na sintaxe a seguir.
**Sintaxe**
```
? ]
```
Os comparadores de expressão incluem `==`, `!=`, `<`, `<=`, `>` e `>=`. O exemplo a seguir filtra `VolumeIds` para todos os `Volumes` em um `State` igual a `Attached`.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[?State==`attached`].VolumeId'
[
[
"vol-e11a5288"
],
[
"vol-2e410a47"
],
[
"vol-a1b3c7nd"
]
]
```
Os resultados podem ser simplificados, o que resulta no exemplo a seguir.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[?State==`attached`].VolumeId[]'
[
"vol-e11a5288",
"vol-2e410a47",
"vol-a1b3c7nd"
]
```
O exemplo a seguir filtra `VolumeIds` para todos os `Volumes` com tamanho inferior a 20.
```
$ aws ec2 describe-volumes \
--query 'Volumes[?Size < `20`].VolumeId'
[
"vol-2e410a47",
"vol-a1b3c7nd"
]
```
Para obter mais informações, consulte [Expressões de filtragem](https://jmespath.org/specification.html#filterexpressions) no *site do JMESPath*.
### Encadeamento de expressões
Você pode encadear resultados de um filtro para uma nova lista e, em seguida, filtrar o resultado com outra expressão usando a seguinte sintaxe:
**Sintaxe**
```
| ]
```
O exemplo a seguir leva os resultados do filtro da expressão `Volumes[*].Attachments[].InstanceId` e produz o primeiro resultado na matriz.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[].InstanceId | [0]'
"i-a071c394"
```
Esse exemplo faz isso criando primeiro a matriz a partir da expressão a seguir.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[].InstanceId'
"i-a071c394",
"i-4b41a37c",
"i-1jd73kv8"
```
Depois, devolva o primeiro elemento para essa matriz.
```
"i-a071c394"
```
Para obter mais informações, consulte [Expressões de encadeamento](https://jmespath.org/specification.html#pipe-expressions) no *site do JMESPath*.
### Filtragem por vários valores de identificador
Para filtrar por vários identificadores, use uma lista de seleção múltipla usando a seguinte sintaxe:
**Sintaxe**
```
[].[, ]
```
No exemplo a seguir, `VolumeId` e `VolumeType` são filtrados na lista `Volumes`, o que resulta na expressão abaixo.
```
$ aws ec2 describe-volumes \
--query 'Volumes[].[VolumeId, VolumeType]'
[
[
"vol-e11a5288",
"standard"
],
[
"vol-2e410a47",
"standard"
],
[
"vol-a1b3c7nd",
"standard"
]
]
```
Para adicionar dados aninhados à lista, adicione outra lista de seleção múltipla. O exemplo a seguir expande o exemplo anterior filtrando também por `InstanceId` e `State` na lista aninhada `Attachments`. Isso resulta na seguinte expressão.
```
$ aws ec2 describe-volumes \
--query 'Volumes[].[VolumeId, VolumeType, Attachments[].[InstanceId, State]]'
[
[
"vol-e11a5288",
"standard",
[
[
"i-a071c394",
"attached"
]
]
],
[
"vol-2e410a47",
"standard",
[
[
"i-4b41a37c",
"attached"
]
]
],
[
"vol-a1b3c7nd",
"standard",
[
[
"i-1jd73kv8",
"attached"
]
]
]
]
```
Para torná-la mais legível, simplifique a expressão conforme mostrado no exemplo a seguir.
```
$ aws ec2 describe-volumes \
--query 'Volumes[].[VolumeId, VolumeType, Attachments[].[InstanceId, State][]][]'
[
"vol-e11a5288",
"standard",
[
"i-a071c394",
"attached"
],
"vol-2e410a47",
"standard",
[
"i-4b41a37c",
"attached"
],
"vol-a1b3c7nd",
"standard",
[
"i-1jd73kv8",
"attached"
]
]
```
Para obter mais informações, consulte [Lista de multisseleção](https://jmespath.org/specification.html#multiselectlist) no *site do JMESPath*.
### Adição de rótulos a valores de identificador
Para tornar essa saída mais fácil de ler, use um hash de seleção múltipla com a sintaxe a seguir.
**Sintaxe**
```
[].{