As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# 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.
**Topics**
+ [
## Idempotência no Amazon EC2
](#client-tokens)
+ [
## Idempotência de RunInstances
](#run-instances-idempotency)
+ [
## Exemplos
](#Run_Instance_Idempotency_CLI)
+ [
## Recomendações de nova tentativa para solicitações idempotentes
](#recommended-actions)
## 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.
**Idempotente por padrão**
+ AssociateAddress
+ CreateVpnConnection
+ DisassociateAddress
+ ReplaceNetworkAclAssociation
+ TerminateInstances
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`.
**Idempotente usando um token de cliente**
+ AllocateHosts
+ AllocateIpamPoolCidr
+ AssociateClientVpnTargetNetwork
+ AssociateIpamResourceDiscovery
+ AttachVerifiedAccessTrustProvider
+ AuthorizeClientVpnIngress
+ CopyFpgaImage
+ CopyImage
+ CreateCapacityReservation
+ CreateCapacityReservationFleet
+ CreateClientVpnEndpoint
+ CreateClientVpnRoute
+ CreateEgressOnlyInternetGateway
+ CreateFleet
+ CreateFlowLogs
+ CreateFpgaImage
+ CreateInstanceConnectEndpoint
+ CreateIpam
+ CreateIpamPool
+ CreateIpamResourceDiscovery
+ CreateIpamScope
+ CreateLaunchTemplate
+ CreateLaunchTemplateVersion
+ CreateManagedPrefixList
+ CreateNatGateway
+ CreateNetworkAcl
+ CreateNetworkInsightsAccessScope
+ CreateNetworkInsightsPath
+ CreateNetworkInterface
+ CreateReplaceRootVolumeTask
+ CreateReservedInstancesListing
+ CreateRouteTable
+ CreateTrafficMirrorFilter
+ CreateTrafficMirrorFilterRule
+ CreateTrafficMirrorSession
+ CreateTrafficMirrorTarget
+ CreateVerifiedAccessEndpoint
+ CreateVerifiedAccessGroup
+ CreateVerifiedAccessInstance
+ CreateVerifiedAccessTrustProvider
+ CreateVolume
+ CreateVpcEndpoint
+ CreateVpcEndpointConnectionNotification
+ CreateVpcEndpointServiceConfiguration
+ DeleteVerifiedAccessEndpoint
+ DeleteVerifiedAccessGroup
+ DeleteVerifiedAccessInstance
+ DeleteVerifiedAccessTrustProvider
+ DetachVerifiedAccessTrustProvider
+ ExportImage
+ ImportImage
+ ImportSnapshot
+ ModifyInstanceCreditSpecification
+ ModifyLaunchTemplate
+ ModifyReservedInstances
+ ModifyVerifiedAccessEndpoint
+ ModifyVerifiedAccessEndpointPolicy
+ ModifyVerifiedAccessGroup
+ ModifyVerifiedAccessGroupPolicy
+ ModifyVerifiedAccessInstance
+ ModifyVerifiedAccessInstanceLoggingConfiguration
+ ModifyVerifiedAccessTrustProvider
+ ProvisionIpamPoolCidr
+ PurchaseHostReservation
+ RequestSpotFleet
+ RequestSpotInstances
+ RunInstances
+ StartNetworkInsightsAccessScopeAnalysis
+ StartNetworkInsightsAnalysis
**Tipos de idempotência**
+ Regional: as solicitações são idempotentes em cada região. No entanto, você pode usar a mesma solicitação, incluindo o mesmo token de cliente, em uma região diferente.
+ Zonal: as solicitações são idempotentes em cada zona de disponibilidade em uma região. Por exemplo, se você especificar o mesmo token de cliente em duas chamadas para **AllocateHosts** na mesma região, as chamadas serão bem-sucedidas se especificarem valores diferentes para o parâmetro **AvailabilityZone**.
## Idempotência de RunInstances
A ação da API [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) 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ê especificar explicitamente uma zona de disponibilidade usando o parâmetro **AvailabilityZone** no tipo de dados **Placement**.
+ Se você especificar implicitamente uma zona de disponibilidade usando o parâmetro **SubnetId**.
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`.
**dica**
Se uma das zonas de disponibilidade na região solicitada não estiver disponível, as solicitações de RunInstances que usam idempotência regional poderão falhar. Para utilizar os recursos da zona de disponibilidade oferecidos pela infraestrutura da AWS, recomendamos que você use a idempotência zonal ao executar instâncias. As solicitações RunInstances que usam idempotência zonal e têm como alvo uma zona de disponibilidade disponível são bem-sucedidas mesmo que outra zona de disponibilidade na região solicitada não esteja disponível.
## 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](https://docs.aws.amazon.com/cli/latest/reference/ec2/allocate-hosts.html) 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](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) 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](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) 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](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_AllocateHosts.html) 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](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) 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](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) 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.
| 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/AWSEC2/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/ec2/latest/devguide/ec2-api-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/AWSEC2/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. |