# Criação de expressões para definir instâncias de contêiner em tarefas do Amazon ECS
<a name="cluster-query-language"></a>

Consultas ao cluster são expressões que permitem agrupar objetos. Por exemplo, você pode agrupar instâncias de contêiner por atributos, como Zona de disponibilidade, tipo de instância ou metadados personalizados. Para obter mais informações, consulte [Atributos de instância de contêiner do Amazon ECS](task-placement-constraints.md#attributes).

Depois de definir um grupo de instâncias de contêiner, você pode personalizar o Amazon ECS para posicionar tarefas em instâncias de contêiner baseadas no grupo. Para obter mais informações, consulte [Execução de uma aplicação como uma tarefa do Amazon ECS](standalone-task-create.md) e [Criação de uma implantação de atualização contínua do Amazon ECS](create-service-console-v2.md). Também é possível aplicar um filtro de grupo ao listar instâncias de contêiner.

## Sintaxe da expressão
<a name="expression-syntax"></a>

As expressões têm a seguinte sintaxe:

```
subject operator [argument]
```

**Assunto**  
O atributo ou o campo a ser avaliado.

`agentConnected`  
Selecione instâncias de contêiner pelo status da conexão do agente de contêiner do Amazon ECS. É possível usar esse filtro para pesquisar instâncias com agentes de contêiner desconectados.  
Operadores válidos: equals (==), not\$1equals (\$1=), in, not\$1in (\$1in), matches (=\$1), not\$1matches (\$1\$1)

`agentVersion`  
Selecione instâncias de contêiner pela versão do agente de contêiner do Amazon ECS. É possível usar esse filtro para encontrar instâncias que estejam executando versões desatualizadas do agente de contêiner do Amazon ECS.  
Operadores válidos: equals (==), not\$1equals (\$1=), greater\$1than (>), greater\$1than\$1equal (>=), less\$1than (<), less\$1than\$1equal (<=)

`attribute:attribute-name`  
Selecione instâncias de contêiner por atributo. Para obter mais informações, consulte [Atributos de instância de contêiner do Amazon ECS](task-placement-constraints.md#attributes).

`ec2InstanceId`  
Selecione instâncias de contêiner pelo ID da instância do Amazon EC2.  
Operadores válidos: equals (==), not\$1equals (\$1=), in, not\$1in (\$1in), matches (=\$1), not\$1matches (\$1\$1)

`registeredAt`  
Selecione instâncias de contêiner na data de registro da instância de contêiner. É possível usar esse filtro para encontrar instâncias recém-registradas ou instâncias muito antigas.  
Operadores válidos: equals (==), not\$1equals (\$1=), greater\$1than (>), greater\$1than\$1equal (>=), less\$1than (<), less\$1than\$1equal (<=)  
Formatos de data válidos: 2018-06-18T22:28:28\$100:00, 2018-06-18T22:28:28Z, 2018-06-18T22:28:28, 2018-06-18

`runningTasksCount`  
Selecione instâncias de contêiner pelo número de tarefas em execução. É possível usar esse filtro para encontrar instâncias vazias ou quase vazias (algumas tarefas em execução).  
Operadores válidos: equals (==), not\$1equals (\$1=), greater\$1than (>), greater\$1than\$1equal (>=), less\$1than (<), less\$1than\$1equal (<=)

`task:group`  
Selecione instâncias de contêiner por grupo de tarefas. Para obter mais informações, consulte [Tarefas do Amazon ECS relacionadas a grupos](task-groups.md).

**Operador**  
O operador de comparação. Os operadores a seguir são aceitos.


|  Operador  |  Descrição  | 
| --- | --- | 
|  ==, equals  |  Igualdade de strings  | 
|  \$1=, not\$1equals  |  Desigualdade de strings  | 
|  >, greater\$1than  |  Maior que  | 
|  >=, greater\$1than\$1equal  |  Maior ou igual a  | 
|  <, less\$1than  |  Menor que  | 
|  <=, less\$1than\$1equal  |  Menor ou igual a  | 
|  exists  |  O sujeito existe  | 
|  \$1exists, not\$1exists  |  O sujeito não existe  | 
|  em  |  Valor na lista de argumentos  | 
|  \$1in, not\$1in  |  Valor fora da lista de argumentos  | 
|  =\$1, matches  |  Correspondência de padrão  | 
|  \$1\$1, not\$1matches  |  Divergência de padrão  | 

**nota**  
Uma expressão individual não pode conter parênteses. No entanto, os parênteses podem ser usados para especificar precedência em expressões compostas.

**Argumento**  
Para muitos operadores, o argumento é um valor literal.

Os operadores `in` e `not_in` esperam uma lista de argumentos como argumento. Você especifica uma lista de argumentos da seguinte forma:

```
[argument1, argument2, ..., argumentN]
```

Os operadores matches e not\$1matches um argumento que se conforme à sintaxe de expressões regulares em Java. Para mais informações, consulte [java.util.regex.Pattern.](http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html)

**Expressões compostas**

É possível combinar expressões usando os operadores booleanos a seguir:
+ &&, e
+ \$1\$1, ou
+ \$1, not

É possível especificar a precedência usando parênteses:

```
(expression1 or expression2) and expression3
```

## Exemplo de expressões
<a name="expression-examples"></a>

Veja a seguir exemplos de expressões.

**Exemplo: igualdade de strings**  
A expressão a seguir seleciona instâncias com o tipo de instância especificado.

```
attribute:ecs.instance-type == t2.small
```

**Exemplo: lista de argumentos**  
A expressão a seguir seleciona instâncias na Zona de disponibilidade us-east-1a ou us-east-1b.

```
attribute:ecs.availability-zone in [us-east-1a, us-east-1b]
```

**Exemplo: expressão composta**  
A expressão a seguir seleciona as instâncias G2 que não estiverem na zona de disponibilidade us-east-1d.

```
attribute:ecs.instance-type =~ g2.* and attribute:ecs.availability-zone != us-east-1d
```

**Exemplo: afinidade de tarefas**  
A expressão a seguir seleciona as instâncias que são tarefas de hospedagem no grupo `service:production`.

```
task:group == service:production
```

**Exemplo: antiafinidade de tarefas**  
A expressão a seguir seleciona as instâncias que não são tarefas de hospedagem no grupo de bancos de dados.

```
not(task:group == database)
```

**Exemplo: contagem de tarefas em execução**  
A expressão a seguir seleciona as instâncias que estão executando apenas uma tarefa.

```
runningTasksCount == 1
```

**Exemplo: versão do agente de contêiner do Amazon ECS**  
A expressão a seguir seleciona instâncias que estão executando uma versão do agente de contêiner abaixo de 1.14.5.

```
agentVersion < 1.14.5
```

**Exemplo: tempo de registro da instância**  
A expressão a seguir seleciona instâncias que foram registradas antes de 13 de fevereiro de 2018.

```
registeredAt < 2018-02-13
```

**Exemplo: ID de instância do Amazon EC2**  
A expressão a seguir seleciona instâncias com os IDs de instância do Amazon EC2 a seguir.

```
ec2InstanceId in ['i-abcd1234', 'i-wxyx7890']
```