# Como garantir idempotência
Ao realizar uma operação de mutação, você poderá ver uma exceção devido à ocorrência de tempos limite ou problemas no servidor após a mutação dos recursos. Isso pode dificultar na hora de determinar se a mutação ocorreu e pode levar a várias novas tentativas. No entanto, se a operação original e as repetições subsequentes realmente tiverem feito as mutações, você poderá ter aplicado alterações de empilhamento ou criado mais recursos do que pretendia. A idempotência garante que uma operação altere recursos no máximo uma vez. Com uma solicitação idempotente, se a solicitação original passar pela mutação com êxito, todas as novas tentativas subsequentes serão concluídas com êxito sem realizar nenhuma outra mutação.
**Topics**
+ [Idempotência no Amazon ECS](#client-tokens)
+ [Idempotência para RunTask](#RunTaskIdempotency)
+ [Exemplos](#Run_Task_Idempotency_CLI)
+ [Recomendações de nova tentativa para solicitações idempotentes](#recommended-actions)
## Idempotência no Amazon ECS
As ações de API comportam opcionalmente a idempotência usando um *token de cliente*. Os comandos AWS CLI correspondentes também comportam a idempotência usando um token de cliente. Um token de cliente é uma string exclusiva que diferencia maiúsculas de minúsculas. Para fazer uma solicitação de API idempotente usando uma dessas ações, especifique um token de cliente na solicitação. Não reutilize os mesmos tokens de cliente para outras solicitações de API. Se você tentar novamente uma solicitação concluída com êxito usando o mesmo token de cliente e os mesmos parâmetros, a nova tentativa será bem-sucedida sem realizar nenhuma ação adicional.
**Idempotente usando um token de cliente**
+ CreateService
O token do cliente pode ter até 36 caracteres ASCII no intervalo de 33 a 126 (inclusive).
+ CreateTaskSet
O token do cliente pode ter até 36 caracteres ASCII no intervalo de 33 a 126 (inclusive).
+ RunTask
O token do cliente pode ter até 64 caracteres ASCII no intervalo de 33 a 126 (inclusive).
**Tipos de idempotência**
+ cluster: solicitações com o mesmo token no mesmo cluster são idempotentes. Por exemplo, o ClientToken A só pode ser usado como parâmetro de solicitação uma vez para solicitações `RunTask` no Cluster X. As solicitações `RunTask` para outros clusters são consideradas uma solicitação separada. Portanto, você pode usar o ClientToken A para uma solicitação `RunTask` para o cluster Y.
## Idempotência para RunTask
A API `RunTask` oferece suporte para idempotência usando um token de cliente. Um token de cliente é uma string exclusiva que você especifica ao fazer uma solicitação de API. Se você tentar refazer uma solicitação de API com o mesmo token de cliente e os mesmos parâmetros de solicitação depois de ela ter sido concluída com êxito, o resultado da solicitação original será retornado. Se você tentar refazer uma solicitação que já foi bem sucedida utilizando o mesmo token de cliente, mas com um ou mais parâmetros diferentes, exceto a região ou a zona de disponibilidade, a tentativa falhará com um `ConflictException`. Se você não especificar seu próprio token de cliente, o AWS SDK e a AWS Command Line Interface gerarão automaticamente um token de cliente para a solicitação a fim de garantir idempotência. Um token de cliente pode ser qualquer string que inclua até 64 caracteres ASCII no intervalo de 33 a 126 (inclusive).
O tempo de vida (TTL) do token do cliente `RunTask` é de 24 horas. Não reutilize o mesmo token de cliente para solicitações diferentes. O TTL máximo do token de cliente é válido para qualquer um dos dois valores a seguir que seja menor:
+ 24 horas
+ A vida útil do recurso mais 1 hora
A vida útil de um recurso é a data e hora em que a tarefa foi criada até a o carimbo de data e hora em que o último status (`lastStatus`) mudou para `STOPPED`. Quando você usa `RunTask` para iniciar mais de uma tarefa, a vida útil do recurso é igual à vida útil da última tarefa que mudou para `STOPPED`.
### Regras e respostas para nova tentativa de RunTask
Quando você repete uma solicitação porque recebeu uma exceção 5xx, normalmente a resposta de nova tentativa com êxito inclui todas as informações que a solicitação original teria retornado. As tarefas que foram interrompidas por menos de 1 hora incluem apenas o ARN da tarefa, o último status e o status desejado.
A seguir apresentamos um trecho de exemplo da resposta de uma nova tentativa quando há uma tarefa em execução, uma tarefa interrompida e uma tarefa que falhou na inicialização.
```
{
"failures": [
{
"arn": "arn:aws:ecs:us-east-1:123456789012:container/4df26bb4-f057-467b-a079-961675296e64",
"reason": "RESOURCE:MEMORY"
}
],
"tasks": [
{
"desiredStatus": "RUNNING",
"taskArn": "arn:aws:ecs:us-east-1:123456789012:task/default/fdf2c302-468c-4e55-b884-5331d816e7fb",
...
},
{
"taskArn": "arn:aws:ecs:us-east-1:123456789012:task/default/fdf2c302-468c-4e55-b884-5331d819999",
"lastStatus": "STOPPED",
...
}
]
}
```
Falhas que aconteceram há mais de 1 hora incluem apenas o número de tarefas com falha.
## Exemplos
### Exemplos de comando da AWS CLI
Para tornar um comando AWS CLI idempotente, adicione a opção `--client-token`.
**Exemplo: create-service**
O comando [create-service](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-service.html#examples) a seguir usa idempotência, pois inclui um token de cliente.
```
aws ecs create-service \
--cluster MyCluster \
--service MyService \
--task-definition MyTaskDefinition:2 \
--desired-count 2 \
--launch-type FARGATE \
--platform-version LATEST \
--network-configuration "awsvpcConfiguration={subnets=["subnet-12344321"],securityGroups=["sg-12344321"],assignPublicIp="ENABLED"}" \
--client-token 550e8400-e29b-41d4-a716-44665544
```
**Exemplo: create-task-set**
O comando [create-task-set](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-task-set.html#examples) a seguir usa idempotência, pois inclui um token de cliente.
```
aws ecs create-task-set \
--cluster MyCluster \
--service MyService \
--task-definition MyTaskDefinition:2 \
--network-configuration "awsvpcConfiguration={subnets=["subnet-12344321"],securityGroups=["sg-12344321"]}" \
--client-token 550e8400-e29b-41d4-a716-44665544
```
**Exemplo: run-task**
O comando [run-task](https://docs.aws.amazon.com/cli/latest/reference/ecs/run-task.html#examples) a seguir usa idempotência, pois inclui um token de cliente.
```
aws ecs run-task \
--cluster MyCluster \
--task-definition MyTaskDefinition:2 \
--client-token 550e8400-e29b-41d4-a716-446655440000
```
### Exemplos de solicitação de API
Para tornar uma solicitação de API idempotente, adicione o parâmetro `clientToken`.
**Exemplo: CreateService**
A solicitação de API [CreateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html) a seguir usa idempotência, pois inclui um token de cliente.
```
POST / HTTP/1.1
Host: ecs.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 87
X-Amz-Target: AmazonEC2ContainerServiceV20141113.CreateService
X-Amz-Date: 20150429T170125Z
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{
"serviceName": "MyService",
"taskDefinition": "MyTaskDefinition:2",
"desiredCount": 10,
"capacityProviderStrategy": [
{
"base": "number",
"capacityProvider": "FARGATE",
"weight": 1
}
],
"capacityProviderStrategy": [
{
"base": "number",
"capacityProvider": "FARGATE_SPOT",
"weight": 1
}
],
"clientToken": "550e8400-e29b-41d4-a716-44665544"
}
```
**Exemplo: CreateTaskSet**
A solicitação de API [CreateTaskSet](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateTaskSet.html) a seguir usa idempotência, pois inclui um token de cliente.
```
POST / HTTP/1.1
Host: ecs.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 87
X-Amz-Target: AmazonEC2ContainerServiceV20141113.CreateTaskSet
X-Amz-Date: 20150429T170125Z
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{
"serviceName": "MyService",
"taskDefinition": "mytask:1",
"desiredCount": 1,
"capacityProviderStrategy": [
{
"base": "number",
"capacityProvider": "FARGATE",
"weight": 1
}
],
"capacityProviderStrategy": [
{
"base": "number",
"capacityProvider": "FARGATE_SPOT",
"weight": 1
}
],
"clientToken": "550e8400-e29b-41d4-a716-44665544"
}
```
**Exemplo: RunTask**
A solicitação de API [RunTask](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html) a seguir usa idempotência, pois inclui um token de cliente.
```
POST / HTTP/1.1
Host: ecs.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 45
X-Amz-Target: AmazonEC2ContainerServiceV20141113.RunTask
X-Amz-Date: 20161121T215740Z
User-Agent: aws-cli/1.11.13 Python/2.7.12 Darwin/16.1.0 botocore/1.4.66
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{
"count": 1,
"taskDefinition": "mytask:1",
"clientToken": "550e8400-e29b-41d4-a716-446655440000"
}
```
## Recomendações de nova tentativa para solicitações idempotentes
A tabela a seguir mostra algumas respostas comuns que você pode obter para solicitações de API idempotentes e fornece recomendações para novas tentativas.
| Resposta | Recomendação | Comentários |
| --- | --- | --- |
| 200 (OK) | Não repetir | A solicitação original foi concluída com êxito. Qualquer repetição subsequente é retornada com êxito. |
| Códigos de resposta da série 400 ([erros do cliente](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/errors-overview.html#CommonErrors)) | Não repetir | Há um dos seguintes problemas com a solicitação: [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/AmazonECS/latest/developerguide/ECS_Idempotency.html)
Se a solicitação envolver um recurso em processo de mudança de estado, a repetição da solicitação poderá ser bem-sucedida. |
| Códigos de resposta da série 500 ([erros do servidor](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/errors-overview.html#api-error-codes-table-server)) | Tentar novamente | O erro é causado por um problema no servidor da AWS e geralmente é transitório. Repita a solicitação com uma estratégia de recuo apropriada. |