Cómo garantizar la idempotencia

Al realizar una operación de modificación, puede aparecer una excepción debido a tiempos de espera o problemas del servidor después de que los recursos se hayan modificado. Esto puede dificultar determinar si se realizó la modificación y provocar varios reintentos. Sin embargo, si la operación original y los reintentos posteriores modificaron los recursos, es posible que se hayan aplicado cambios acumulados o que se hayan creado más recursos de los previstos. La idempotencia garantiza que una operación modifique los recursos una sola vez como máximo. Con una solicitud idempotente, si la solicitud original modificó los recursos correctamente, cualquier reintento posterior se completa correctamente sin realizar ninguna modificación adicional.

Idempotencia en Amazon ECS

Las siguientes acciones de la API admiten opcionalmente idempotencia mediante un token de cliente. Los comandos AWS CLI correspondientes también admiten idempotencia usando un token de cliente. Un token de cliente es una cadena única que distingue entre mayúsculas y minúsculas. Para realizar una solicitud de API idempotente mediante una de estas acciones, especifique un token de cliente en la solicitud. No debe reutilizar el mismo token de cliente para diferentes solicitudes de API. Si reintenta una solicitud que se completó correctamente con el mismo token de cliente y los mismos parámetros, el reintento se realizará con éxito sin realizar ninguna otra acción.

Idempotencia de RunTask

La API RunTask admite idempotencia mediante un token de cliente. Un token de cliente es una cadena única que se especifica cuando se realiza una solicitud de API. Si vuelve a intentar una solicitud de API con el mismo token de cliente y los mismos parámetros de solicitud después de que se haya completado correctamente, se devuelve el resultado de la solicitud original. Si se reintenta una solicitud correcta con el mismo token de cliente, pero uno o varios parámetros son diferentes, salvo la región o la zona de disponibilidad, el reintento falla con ConflictException. Si no se especifica un token de cliente propio, el SDK de AWS y AWS Command Line Interface generan automáticamente un token de cliente para la solicitud a fin de garantizar que sea idempotente. Un token de cliente puede ser cualquier cadena de hasta 64 caracteres ASCII dentro del intervalo de 33 a 126, ambos incluidos.

El tiempo de vida (TTL) del token de cliente RunTask es de 24 horas. No se debe reutilizar el mismo token de cliente para solicitudes diferentes. El TTL máximo del token de cliente es válido hasta el menor de los siguientes dos valores:

Reglas y respuestas de reintento de RunTask

Cuando se reintenta una solicitud porque se recibió una excepción 5xx, la respuesta correcta del reintento suele incluir toda la información que habría devuelto la solicitud original. Las tareas que llevan detenidas menos de una hora solo incluyen el ARN de la tarea, el último estado y el estado deseado.

A continuación se muestra un fragmento de ejemplo de la respuesta de un reintento cuando hay una tarea en ejecución, una tarea detenida y una tarea que no se pudo lanzar.

{
  "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",
      ...
     }
  ]
}

Los errores con más de una hora de antigüedad solo incluyen el número de tareas con error.

Ejemplos

Ejemplos de comando de AWS CLI

Para hacer que un comando AWS CLI sea idempotente, agregue la opción --client-token.

Ejemplo: create-service

El siguiente comando create-service utiliza idempotencia porque incluye un 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

Ejemplo: create-task-set

El siguiente comando create-task-set utiliza idempotencia porque incluye un 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

Ejemplo: run-task

El siguiente comando run-task utiliza idempotencia porque incluye un token de cliente.

aws ecs run-task \
    --cluster MyCluster \
    --task-definition MyTaskDefinition:2 \
    --client-token 550e8400-e29b-41d4-a716-446655440000

Ejemplos de solicitud de la API

Para hacer que una solicitud de la API sea idempotente, agrega el parámetro clientToken.

Ejemplo: CreateService

La siguiente solicitud a la API CreateService usa idempotencia porque incluye un 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"
}

Ejemplo: CreateTaskSet

La siguiente solicitud a la API CreateTaskSet usa idempotencia porque incluye un 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" 
}

Ejemplo: RunTask

La siguiente solicitud a la API RunTask usa idempotencia porque incluye un 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" 
}

Vuelva a intentar las recomendaciones para solicitudes idempotentes

En la siguiente tabla se muestran algunas respuestas comunes que puede obtener para solicitudes de API idempotentes y se ofrecen recomendaciones de reintento.