**Esta documentação é somente para a versão 1 da AWS CLI.**

Anunciamos o próximo fim do suporte para a AWS CLI versão 1. É recomendável migrar para a AWS CLI versão 2. Para saber as datas e receber detalhes e informações adicionais sobre como migrar, consulte o [anúncio](https://aws.amazon.com/blogs/developer/cli-v1-maintenance-mode-announcement/). Para obter a documentação relacionada à AWS CLI versão 2, consulte o [Guia do usuário da versão 2](https://docs.aws.amazon.com/cli/latest/userguide/).

# Filtrar a saída na AWS CLI
<a name="cli-usage-filter"></a>

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 name="cli-usage-filter-server-side"></a>

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/v1/reference/ses/create-receipt-filter.html) e [ce](https://docs.aws.amazon.com/cli/v1/reference/ce/get-cost-and-usage.html). 
+ `--filters`, como [ec2](https://docs.aws.amazon.com/cli/v1/reference/ec2/describe-volumes.html), [autoscaling](https://docs.aws.amazon.com/cli/v1/reference/autoscaling/describe-tags.html) e [rds](https://docs.aws.amazon.com/cli/v1/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/v1/reference/dynamodb/scan.html](https://docs.aws.amazon.com/cli/v1/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 [Guia de referência da AWS CLI](https://docs.aws.amazon.com/cli/v1/reference/).

## Filtragem no lado do cliente
<a name="cli-usage-filter-client-side"></a>

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`,, 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
<a name="cli-usage-filter-client-side-output"></a>

**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
<a name="cli-usage-filter-client-side-output-example"></a>

```
$ 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
<a name="cli-usage-filter-client-side-identifiers"></a>

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
<a name="cli-usage-filter-client-side-select-list"></a>

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**

```
<listName>[ ]
```

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**

```
<arrayName>[<start>:<stop>:<step>]
```

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
<a name="cli-usage-filter-client-side-nested"></a>

Para refinar a filtragem de `Volumes[*]` para valores aninhados, use subexpressões anexando um ponto e seus critérios de filtragem.

**Sintaxe**

```
<expression>.<expression>
```

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
<a name="cli-usage-filter-client-side-specific-flattening"></a>

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
<a name="cli-usage-filter-client-side-specific-values"></a>

Para filtrar valores específicos em uma lista, use uma expressão de filtro como mostrado na sintaxe a seguir.

**Sintaxe**

```
? <expression> <comparator> <expression>]
```

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
<a name="cli-usage-filter-client-side-pipe"></a>

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**

```
<expression> | <expression>] 
```

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
<a name="cli-usage-filter-client-side-miltiselect-list"></a>

Para filtrar por vários identificadores, use uma lista de seleção múltipla usando a seguinte sintaxe: 

**Sintaxe**

```
<listName>[].[<expression>, <expression>]
```

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
<a name="cli-usage-filter-client-side-multiselect-hash"></a>

Para tornar essa saída mais fácil de ler, use um hash de seleção múltipla com a sintaxe a seguir.

**Sintaxe**

```
<listName>[].{<label>: <expression>, <label>: <expression>}
```

O rótulo do identificador não precisa ser o mesmo que o nome do identificador. O exemplo a seguir usa o rótulo `VolumeType` para os valores `VolumeType`.

```
$ aws ec2 describe-volumes \
    --query 'Volumes[].{VolumeType: VolumeType}'
[
  {
    "VolumeType": "standard",
  },
  {
    "VolumeType": "standard",
  },
  {
    "VolumeType": "standard",
  }
]
```

Para simplificar, o exemplo a seguir mantém os nomes dos identificadores para cada rótulo e exibe `VolumeId`, `VolumeType`, `InstanceId` e `State` para todos os volumes:

```
$ aws ec2 describe-volumes \
    --query 'Volumes[].{VolumeId: VolumeId, VolumeType: VolumeType, InstanceId: Attachments[0].InstanceId, State: Attachments[0].State}'
[
  {
    "VolumeId": "vol-e11a5288",
    "VolumeType": "standard",
    "InstanceId": "i-a071c394",
    "State": "attached"
  },
  {
    "VolumeId": "vol-2e410a47",
    "VolumeType": "standard",
    "InstanceId": "i-4b41a37c",
    "State": "attached"
  },
  {
    "VolumeId": "vol-a1b3c7nd",
    "VolumeType": "standard",
    "InstanceId": "i-1jd73kv8",
    "State": "attached"
  }
]
```

Para obter mais informações, consulte [Hash de multisseleção](https://jmespath.org/specification.html#multiselecthash) no *site do JMESPath*.

### Funções
<a name="cli-usage-filter-client-side-functions"></a>

A sintaxe JMESPath contém muitas funções que você pode usar em suas consultas. Para obter informações sobre funções JMESPath, consulte [Funções integradas](https://jmespath.org/specification.html#built-in-functions) no *site do JMESPath*.

Para demonstrar como você pode incorporar uma função em suas consultas, o exemplo a seguir usa a função `sort_by`. A função `sort_by` classifica uma matriz usando uma expressão como a chave de classificação com a seguinte sintaxe:

**Sintaxe**

```
sort_by(<listName>, <sort expression>)[].<expression>
```

O exemplo a seguir usa o [exemplo de hash de multisseleção](#cli-usage-filter-client-side-multiselect-hash) anterior e classifica a saída por `VolumeId`. 

```
$ aws ec2 describe-volumes \
    --query 'sort_by(Volumes, &VolumeId)[].{VolumeId: VolumeId, VolumeType: VolumeType, InstanceId: Attachments[0].InstanceId, State: Attachments[0].State}'
[
  {
    "VolumeId": "vol-2e410a47",
    "VolumeType": "standard",
    "InstanceId": "i-4b41a37c",
    "State": "attached"
  },
  {
    "VolumeId": "vol-a1b3c7nd",
    "VolumeType": "standard",
    "InstanceId": "i-1jd73kv8",
    "State": "attached"
  },
  {
    "VolumeId": "vol-e11a5288",
    "VolumeType": "standard",
    "InstanceId": "i-a071c394",
    "State": "attached"
  }
]
```

Para obter mais informações, consulte [sort\$1by](https://jmespath.org/specification.html#sort-by) no *site do JMESPath*.

### Exemplos avançados `--query`
<a name="cli-usage-filter-client-side-advanced"></a>

**Para extrair informações de um item específico**

O exemplo a seguir usa o parâmetro `--query` para localizar um item específico em uma lista e extrai as informações desse item. O exemplo lista todas as `AvailabilityZones` associadas ao endpoint de serviço especificado. Ele extrai o item da lista `ServiceDetails` que tem o `ServiceName` especificado e gera o campo `AvailabilityZones` do item selecionado. 

```
$ aws --region us-east-1 ec2 describe-vpc-endpoint-services \
    --query 'ServiceDetails[?ServiceName==`com.amazonaws.us-east-1.ecs`].AvailabilityZones'
[
    [
        "us-east-1a",
        "us-east-1b",
        "us-east-1c",
        "us-east-1d",
        "us-east-1e",
        "us-east-1f"
    ]
]
```

**Para mostrar snapshots após a data de criação especificada**

O exemplo a seguir mostra como listar todos os seus snapshots que foram criados após uma data especificada, incluindo apenas alguns dos campos disponíveis na saída.

```
$ aws ec2 describe-snapshots --owner self \
    --output json \
    --query 'Snapshots[?StartTime>=`2018-02-07`].{Id:SnapshotId,VId:VolumeId,Size:VolumeSize}'
[
    {
        "id": "snap-0effb42b7a1b2c3d4",
        "vid": "vol-0be9bb0bf12345678",
        "Size": 8
    }
]
```

**Para mostrar as AMIs mais recentes**

O exemplo a seguir lista as cinco imagens de máquina da Amazon (AMIs) mais recentes que você criou, classificadas das mais recentes para as mais antigas.

```
$ aws ec2 describe-images \
    --owners self \
    --query 'reverse(sort_by(Images,&CreationDate))[:5].{id:ImageId,date:CreationDate}'
[
    {
        "id": "ami-0a1b2c3d4e5f60001",
        "date": "2018-11-28T17:16:38.000Z"
    },
    {
        "id": "ami-0a1b2c3d4e5f60002",
        "date": "2018-09-15T13:51:22.000Z"
    },
    {
        "id": "ami-0a1b2c3d4e5f60003",
        "date": "2018-08-19T10:22:45.000Z"
    },
    {
        "id": "ami-0a1b2c3d4e5f60004",
        "date": "2018-05-03T12:04:02.000Z"
    },
    {
        "id": "ami-0a1b2c3d4e5f60005",
        "date": "2017-12-13T17:16:38.000Z"
    }
]
```

**Para mostrar instâncias não íntegras do Auto Scaling**

O exemplo a seguir mostra apenas o `InstanceId` para todas as instâncias com problemas de integridade no grupo de AutoScaling especificado.

```
$ aws autoscaling describe-auto-scaling-groups \
    --auto-scaling-group-name My-AutoScaling-Group-Name \
    --output text \
    --query 'AutoScalingGroups[*].Instances[?HealthStatus==`Unhealthy`].InstanceId'
```

**Para incluir volumes com a tag especificada**

O exemplo a seguir descreve todas as instâncias com uma tag `test`. Contanto que haja outra etiqueta além de `test` anexada ao volume, o volume ainda é retornado nos resultados.

A expressão abaixo para retornar todas as tags com a tag `test` em uma matriz. Qualquer etiqueta que não é a etiqueta `test` contém um valor `null`.

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Tags[?Value == `test`]'
```

**Para excluir volumes com a etiqueta especificada**

O exemplo a seguir descreve todas as instâncias sem uma etiqueta `test`. A utilização de uma expressão `?Value != `test`` simples não funciona para excluir um volume, pois os volumes podem ter várias etiquetas. Contanto que haja outra etiqueta além de `test` anexada ao volume, o volume ainda é retornado nos resultados.

Para excluir todos os volumes com a etiqueta `test`, comece com a expressão abaixo para retornar todas as etiquetas com a etiqueta `test` em um array. Qualquer etiqueta que não é a etiqueta `test` contém um valor `null`.

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Tags[?Value == `test`]'
```

Em seguida, filtrar todos os resultados `test` positivos usando a função `not_null`. 

```
$ aws ec2 describe-volumes \
    --query 'Volumes[?!not_null(Tags[?Value == `test`].Value)]'
```

Encadeie os resultados para simplificá-los, o que resultará na consulta a seguir.

```
$ aws ec2 describe-volumes \
    --query 'Volumes[?!not_null(Tags[?Value == `test`].Value)] | []'
```

## Combinação das filtragens no lado do servidor e no lado do cliente
<a name="cli-usage-filter-combining"></a>

É possível usar as filtragens no lado do servidor e no lado do cliente ao mesmo tempo. A filtragem no lado do servidor é concluída primeiro, o que envia os dados para o cliente que, em seguida, são filtrados pelo parâmetro `--query`. Se você estiver usando conjuntos de dados grandes, aplicar a filtragem no lado do servidor primeiro pode reduzir a quantidade de dados enviados ao cliente para cada chamada AWS CLI sem prejudicar a personalização poderosa proporcionada pela filtragem no lado do cliente.

O exemplo a seguir mostra volumes do Amazon EC2 usando filtragens no lado do servidor e no lado do cliente. O serviço filtra uma lista de todos os volumes anexados na zona de disponibilidade `us-west-2a`. O parâmetro `--query` limita ainda mais a saída apenas para aqueles volumes com um valor `Size` maior que 50 e mostra apenas os campos especificados com nomes definidos pelo usuário.

```
$ aws ec2 describe-volumes \
    --filters "Name=availability-zone,Values=us-west-2a" "Name=status,Values=attached" \
    --query 'Volumes[?Size > `50`].{Id:VolumeId,Size:Size,Type:VolumeType}'
[
    {
        "Id": "vol-0be9bb0bf12345678",
        "Size": 80,
        "VolumeType": "gp2"
    }
]
```

O exemplo a seguir recupera uma lista de imagens que atendem a vários critérios. Depois, usa o parâmetro `--query` para classificar a saída por `CreationDate`, selecionando apenas as mais recentes. Por fim, ele exibe o `ImageId` dessa imagem.

```
$ aws ec2 describe-images \
    --owners amazon \
    --filters "Name=name,Values=amzn*gp2" "Name=virtualization-type,Values=hvm" "Name=root-device-type,Values=ebs" \
    --query "sort_by(Images, &CreationDate)[-1].ImageId" \
    --output text
ami-00ced3122871a4921
```

O exemplo a seguir exibe o número de volumes disponíveis acima de 1000 IOPS usando `length` para contar quantos há em uma lista.

```
$ aws ec2 describe-volumes \
    --filters "Name=status,Values=available" \
    --query 'length(Volumes[?Iops > `1000`])'
3
```

O exemplo a seguir recupera os nomes de grupo do Auto Scaling que estão usando configurações de inicialização na Região da AWS especificada e que estão usando pilhas do CloudFormation.

```
$ aws autoscaling describe-auto-scaling-groups --region us-west-2 \
  --filters Name=tag-key,Values=aws:cloudformation:stack-name \
  --query 'AutoScalingGroups[?LaunchConfigurationName!=`null`].AutoScalingGroupName'
[
    "group-1",
    "group-2",
    "group-3"
]
```

## Recursos adicionais
<a name="cli-usage-filter-resources"></a>

**JMESPath Terminal**  
O JMESPath Terminal é um terminal de comandos interativos que permitem experimentar expressões JMESPath usadas na filtragem no lado do cliente. Usando o comando `jpterm`, o terminal mostra os resultados imediatos da consulta enquanto você está digitando. Você pode encaminhar diretamente a saída da AWS CLI para o terminal, permitindo assim a experimentação avançada de consultas.   
O exemplo a seguir encaminha a saída da `aws ec2 describe-volumes` diretamente para o JMESPath Terminal.  

```
$ aws ec2 describe-volumes | jpterm
```
Para obter mais informações sobre o JMESPath Terminal e instruções de instalação, consulte [JMESPath Terminal](https://github.com/jmespath/jmespath.terminal) no *GitHub*.

**Utilitário jq**  
O `jq` fornece uma maneira de transformar sua saída no lado do cliente em um formato de saída desejado. Para obter mais informações sobre o `jq` e instruções de instalação, consulte [jq](https://stedolan.github.io/jq/) no *GitHub*.