Ensuring idempotency in Amazon EC2 API requests

Quando você faz uma solicitação de API de mutação, a solicitação normalmente retorna um resultado antes da conclusão dos fluxos de trabalho assíncronos da operação. As operações também podem expirar ou encontrar outros problemas no servidor antes de serem concluídas, mesmo que a solicitação já tenha retornado um resultado. Isso pode dificultar na hora de determinar se a solicitação foi bem-sucedida ou não, e pode levar a várias novas tentativas para garantir que a operação seja concluída com êxito. No entanto, se a solicitação original e as tentativas subsequentes forem bem-sucedidas, a operação será concluída várias vezes. Isso significa que você pode criar mais recursos do que pretendia.

A idempotência garante que uma solicitação de API seja concluída no máximo uma vez. Com uma solicitação idempotente, se a solicitação original for concluída com êxito, todas as novas tentativas subsequentes serão concluídas com êxito sem realizar nenhuma ação. No entanto, o resultado pode conter informações atualizadas, como o status atual da criação.

Idempotência no Amazon EC2

As ações de API a seguir são idempotentes por padrão e não exigem configuração adicional. Os comandos AWS CLI correspondentes também comportam a idempotência por padrão.

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. Token de cliente é uma string exclusiva que diferencia maiúsculas de minúsculas de até 64 caracteres ASCII. 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. Se você tentar refazer uma solicitação com êxito 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 erro IdempotentParameterMismatch.

Idempotência de RunInstances

A ação da API RunInstances usa idempotência regional e zonal.

O tipo de idempotência usado depende de como você especifica a zona de disponibilidade na sua solicitação da API RunInstances. A solicitação usa idempotência zonal nos seguintes casos:

Se você não especificar uma zona de disponibilidade de forma explícita nem implícita, a solicitação usará idempotência regional.

Idempotência zonal

A idempotência zonal garante que uma solicitação da API RunInstances seja idempotente em cada zona de disponibilidade em uma região. Isso garante que uma solicitação com o mesmo token de cliente possa ser concluída somente uma vez em cada zona de disponibilidade em uma região. No entanto, o mesmo token de cliente pode ser usado para iniciar instâncias em outras zonas de disponibilidade na região.

Por exemplo, se você enviar uma solicitação idempotente para iniciar uma instância na zona de disponibilidade us-east-1a e depois usar o mesmo token de cliente em uma solicitação na zona de disponibilidade us-east-1b, executaremos instâncias em cada uma dessas zonas de disponibilidade. Se um ou mais dos parâmetros forem diferentes, as tentativas subsequentes com o mesmo token de cliente nessas zonas de disponibilidade retornarão com êxito sem realizar nenhuma ação adicional ou falharão com um erro IdempotentParameterMismatch.

Idempotência regional

A idempotência regional garante que uma solicitação da API RunInstances seja idempotente em uma região. Isso garante que uma solicitação com o mesmo token de cliente possa ser concluída somente uma vez em uma região. No entanto, exatamente a mesma solicitação, com o mesmo token de cliente, pode ser usada para executar instâncias em uma região diferente.

Por exemplo, se você enviar uma solicitação idempotente para executar uma instância na região us-east-1 e depois usar o mesmo token de cliente em uma solicitação na região eu-west-1, executaremos instâncias em cada uma dessas regiões. Se um ou mais dos parâmetros forem diferentes, as tentativas subsequentes com o mesmo token de cliente nessas regiões retornarão com êxito sem realizar nenhuma ação adicional ou falharão com um erro IdempotentParameterMismatch.

Exemplos

Exemplos de comando da AWS CLI

Para tornar um comando AWS CLI idempotente, adicione a opção --client-token.

Exemplo 1: idempotência

O comando allocate-hosts a seguir usa idempotência, pois inclui um token de cliente.

aws ec2 allocate-hosts  --instance-type m5.large  --availability-zone eu-west-1a  --auto-placement on  --quantity 1 --client-token 550e8400-e29b-41d4-a716-446655440000

Exemplo 2: idempotência regional de run-instances

O comando run-instances a seguir usa idempotência regional, pois inclui um token de cliente, mas não especifica de forma explícita nem implícita uma zona de disponibilidade.

aws ec2 run-instances --image-id ami-b232d0db --count 1 --key-name my-key-pair --client-token 550e8400-e29b-41d4-a716-446655440000

Exemplo 3: idempotência zonal de run-instances

O comando run-instances a seguir usa idempotência zonal, pois inclui um token de cliente e uma zona de disponibilidade especificada de forma explícita.

aws ec2 run-instances  --placement "AvailabilityZone=us-east-1a" --image-id ami-b232d0db --count 1 --key-name my-key-pair --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 1: idempotência

O comando da API AllocateHosts a seguir usa idempotência, pois inclui um token de cliente.

https://ec2.amazonaws.com/?Action=AllocateHosts
&AvailabilityZone=us-east-1b
&InstanceType=m5.large
&Quantity=1
&AutoPlacement=off
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

Exemplo 2: idempotência regional de RunInstances

A solicitação da API RunInstances a seguir usa idempotência regional, pois inclui um token de cliente, mas não especifica de forma explícita nem implícita uma zona de disponibilidade.

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-3ac33653
&MaxCount=1
&MinCount=1
&KeyName=my-key-pair
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

Exemplo 3: idempotência zonal de RunInstances

A solicitação da API RunInstances a seguir usa idempotência zonal, pois inclui um token de cliente e uma zona de disponibilidade especificada de forma explícita.

https://ec2.amazonaws.com/?Action=RunInstances
&Placement.AvailabilityZone=us-east-1d
&ImageId=ami-3ac33653
&MaxCount=1
&MinCount=1
&KeyName=my-key-pair
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

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.