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.

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.

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:

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