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á.
# Acesso programático ao Amazon EC2
É possível criar e gerenciar seus recursos do Amazon EC2 usando o Console de gerenciamento da AWS ou uma interface programática. Para acessar informações sobre o uso do console do Amazon EC2, consulte o [Guia do usuário do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
**Como funciona**
+ [Endpoints do Amazon EC2](ec2-endpoints.md)
+ [Consistência final](eventual-consistency.md)
+ [Idempotência](ec2-api-idempotency.md)
+ [Controle de utilização de solicitações](ec2-api-throttling.md)
+ [Paginação](ec2-api-pagination.md)
**Interfaces programáticas**
+ [AWS Command Line Interface (AWS CLI)](ec2-aws-cli.md)
+ [AWS CloudFormation](ec2-cloudformation.md)
+ [AWS SDKs da](sdk-general-information-section.md)
+ [API de baixo nível](ec2-low-level-api.md)
**Começar**
+ [Exemplos de código](service_code_examples.md)
+ [Console-to-Code](console-to-code.md)
**Monitoramento**
+ [AWS CloudTrail](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitor-with-cloudtrail.html)
+ [Monitorar solicitações](monitor.md)
# Endpoints de serviço do Amazon EC2
Um endpoint é uma URL que serve como ponto de entrada para um serviço AWS web. O Amazon EC2 comporta os seguintes tipos de endpoint:
+ [IPv4 endpoints](#ipv4)
+ [Endpoints de pilha dupla (suportam tanto quanto](#ipv6)) IPv4 IPv6
+ [ Endpoints do FIPS](https://docs.aws.amazon.com/general/latest/gr/rande.html#FIPS-endpoints)
Ao fazer uma solicitação, você pode especificar o endpoint a ser usado. Se você não especificar um endpoint, o IPv4 endpoint será usado por padrão. Para usar outro tipo de endpoint, você deve especificá-lo em sua solicitação. Para obter exemplos de como fazer isso, consulte [Especificar endpoints](#examples). Para ver uma tabela de endpoints disponíveis, consulte [Endpoints de serviço por região](#service-endpoints).
## IPv4 endpoints
IPv4 os endpoints oferecem suporte somente ao IPv4 tráfego. IPv4 os endpoints estão disponíveis para todas as regiões.
Se você especificar o endpoint geral, `ec2.amazonaws.com`, usaremos o endpoint para `us-east-1`. Para usar uma região diferente, especifique o endpoint associado a ela. Por exemplo, se você especificar `ec2.us-east-2.amazonaws.com` como endpoint, direcionaremos sua solicitação para o endpoint `us-east-2`.
IPv4 os nomes de endpoints usam a seguinte convenção de nomenclatura:
+ `service.region.amazonaws.com`
Por exemplo, o nome do IPv4 endpoint para a `eu-west-1` região é`ec2.eu-west-1.amazonaws.com`.
## Endpoints de pilha dupla (IPv4 e) IPv6
Os endpoints de pilha dupla oferecem suporte tanto ao tráfego quanto ao tráfego. IPv4 IPv6 Quando você faz uma solicitação para um endpoint de pilha dupla, o URL do endpoint é resolvido para um IPv4 endereço IPv6 ou, dependendo do protocolo usado pela rede e pelo cliente.
O Amazon EC2 comporta somente endpoints de pilha dupla regionais, o que significa que você deve especificar a região como parte do nome do endpoint. Os nomes de endpoints de pilha dupla usam a seguinte convenção de nomenclatura:
+ `ec2.region.api.aws`
Por exemplo, o nome do endpoint de pilha dupla para a região `eu-west-1` é `ec2.eu-west-1.api.aws`.
## Endpoints de serviço por região
Veja a seguir os endpoints de serviço para o Amazon EC2. Para obter mais informações sobre regiões, consulte [Regiões e zonas de disponibilidade](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) no *Manual do usuário do Amazon EC2*.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/ec2/latest/devguide/ec2-endpoints.html)
## Especificar endpoints
Esta seção fornece alguns exemplos de como especificar um endpoint ao fazer uma solicitação.
------
#### [ AWS CLI ]
Os exemplos a seguir mostram como especificar um endpoint para a região `us-east-2` usando a AWS CLI.
+ **Pilha dupla**
```
aws ec2 describe-regions --region us-east-2 --endpoint-url https://ec2.us-east-2.api.aws
```
+ **IPv4**
```
aws ec2 describe-regions --region us-east-2 --endpoint-url https://ec2.us-east-2.amazonaws.com
```
------
#### [ AWS SDK for Java 2.x ]
Os exemplos a seguir mostram como especificar um endpoint para a região `us-east-2` usando o AWS SDK for Java 2.x.
+ **Pilha dupla**
```
Ec2Client client = Ec2Client.builder()
.region(Region.US_EAST_2)
.endpointOverride(URI.create("https://ec2.us-east-2.api.aws"))
.build();
```
+ **IPv4**
```
Ec2Client client = Ec2Client.builder()
.region(Region.US_EAST_2)
.endpointOverride(URI.create("https://ec2.us-east-2.amazonaws.com"))
.build();
```
------
#### [ AWS SDK para Java 1.x ]
Os exemplos a seguir mostram como especificar um endpoint para a `eu-west-1` região usando o AWS SDK para Java 1.x.
+ **Pilha dupla**
```
AmazonEC2 s3 = AmazonEC2ClientBuilder.standard()
.withEndpointConfiguration(new EndpointConfiguration(
"https://ec2.eu-west-1.api.aws",
"eu-west-1"))
.build();
```
+ **IPv4**
```
AmazonEC2 s3 = AmazonEC2ClientBuilder.standard()
.withEndpointConfiguration(new EndpointConfiguration(
"https://ec2.eu-west-1.amazonaws.com",
"eu-west-1"))
.build();
```
------
#### [ AWS SDK for Go ]
Os exemplos a seguir mostram como especificar um endpoint para a região `us-east-1` usando o AWS SDK para Go.
+ **Pilha dupla**
```
sess := session.Must(session.NewSession())
svc := ec2.New(sess, &aws.Config{
Region: aws.String(endpoints.UsEast1RegionID),
Endpoint: aws.String("https://ec2.us-east-1.api.aws")
})
```
+ **IPv4**
```
sess := session.Must(session.NewSession())
svc := ec2.New(sess, &aws.Config{
Region: aws.String(endpoints.UsEast1RegionID),
Endpoint: aws.String("https://ec2.us-east-1.amazonaws.com")
})
```
------
# Consistência eventual na API da Amazon EC2
A EC2 API da Amazon segue um modelo de consistência eventual, devido à natureza distribuída do sistema que suporta a API. Isso significa que o resultado de um comando de API que você executa e que afeta seus EC2 recursos da Amazon pode não ser imediatamente visível para todos os comandos subsequentes que você executar. Você deve ter isso em mente ao executar um comando de API que segue imediatamente um comando de API anterior.
A consistência eventual pode afetar a maneira como você gerencia seus recursos. Por exemplo, se você executar um comando para criar um recurso, ele, por fim, ficará visível para outros comandos. Isso significa que, se você executar um comando para modificar ou descrever o recurso que acabou de criar, é possível que o respectivo ID não tenha se propagado por todo o sistema, e você receberá um erro indicando que o recurso não existe.
Para gerenciar a consistência eventual, é possível fazer o seguinte:
+ Confirme o estado do recurso antes de executar um comando para modificá-lo. Execute o comando `Describe` apropriado usando um algoritmo de recuo exponencial para garantir tempo suficiente para que o comando anterior se propague pelo sistema. Para fazer isso, execute o `Describe` comando repetidamente, começando com alguns segundos de tempo de espera e aumentando gradualmente até alguns minutos de tempo de espera.
+ Adicione o tempo de espera entre os comandos subsequentes, mesmo que um comando `Describe` exiba uma resposta precisa. Aplique um algoritmo de recuo exponencial começando com alguns segundos de tempo de espera e aumente gradualmente até alguns minutos de tempo de espera.
**Exemplos de erro de consistência eventual**
Veja a seguir exemplos de códigos de erro que você pode encontrar como resultado de uma consistência eventual.
+ `InvalidInstanceID.NotFound`
Se você executar o comando `RunInstances` com êxito e, depois, executar imediatamente outro comando usando o ID da instância fornecido na resposta de `RunInstances`, ele poderá exibir um erro `InvalidInstanceID.NotFound`. Isso não significa que a instância não existe.
Alguns comandos específicos que podem ser afetados são:
+ `DescribeInstances`: para confirmar o estado real da instância, execute esse comando usando um algoritmo de recuo exponencial.
+ `TerminateInstances`: para confirmar o estado da instância, primeiro execute o comando `DescribeInstances` usando um algoritmo de recuo exponencial.
**Importante**
Se você receber um erro `InvalidInstanceID.NotFound` após a execução de `TerminateInstances`, isso não significa que a instância foi ou será encerrada. Sua instância ainda pode estar em execução. É por isso que é importante primeiro confirmar o estado da instância usando `DescribeInstances`.
+ `InvalidGroup.NotFound`
Se você executar o comando `CreateSecurityGroup` com êxito e, depois, executar imediatamente outro comando usando o ID do grupo de segurança fornecido na resposta de `CreateSecurityGroup`, ele poderá exibir um erro `InvalidGroup.NotFound`. Para confirmar o estado do grupo de segurança, execute o comando `DescribeSecurityGroups` usando um algoritmo de recuo exponencial.
+ `InstanceLimitExceeded`
Você solicitou mais instâncias do que o limite atual permite para o tipo de instância especificado. Você poderá atingir esse limite inesperadamente se estiver executando e encerrando instâncias rapidamente, pois as instâncias encerradas contam para seu limite de instâncias por um tempo depois de serem encerradas.
# 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. |
# Limitação de solicitações para a API da Amazon EC2
A EC2 Amazon limita as solicitações de EC2 API para cada AWS conta por região. Fazemos isso para ajudar no desempenho do serviço e para garantir o uso justo para todos os EC2 clientes da Amazon. A limitação garante que as solicitações para a EC2 API da Amazon não excedam os limites máximos permitidos de solicitações de API. As solicitações de API estão sujeitas aos limites de solicitações, independentemente de serem originadas de:
+ Aplicativos de terceiros
+ Uma ferramentas da linha de comando
+ O EC2 console da Amazon
Se você exceder o limite de controle de utilização de API, receberá o código de erro `RequestLimitExceeded`.
**Topics**
+ [Como o controle de utilização é aplicado](#throttling-how)
+ [Limites de token de solicitações](#throttling-limits-rate-based)
+ [Limites de tokens de recursos](#throttling-limits-cost-based)
+ [Monitore o controle de utilização da API](#throttling-monitor)
+ [Notas tentativas e recuo exponencial](#api-backoff)
+ [Solicitar um aumento de limite de](#throttling-increase)
## Como o controle de utilização é aplicado
A Amazon EC2 usa o [algoritmo de token bucket](https://en.wikipedia.org/wiki/Token_bucket) para implementar a limitação de API. Com esse algoritmo, sua conta tem um *bucket* que contém um número específico de *tokens*. O número de tokens no bucket representa seu limite de controle de utilização em qualquer segundo.
A Amazon EC2 implementa dois tipos de limitação de API:
**Topics**
+ [Limitação de intervalo de solicitações](#throttling-rate-based)
+ [Limitação de taxa de recursos](#throttling-cost-based)
### Limitação de intervalo de solicitações
Com a limitação da taxa de solicitação, cada API é avaliada individualmente, e você tem controle de utilização em relação ao número de solicitações feitas por API. Cada solicitação feita remove um token do bucket da API. Por exemplo, o tamanho do bucket de tokens para `DescribeHosts`, uma ação de API *sem mutação*, é de cem tokens. Você pode fazer até cem solicitações `DescribeHosts` no total por segundo. Se você exceder cem solicitações em um segundo, terá controle de utilização nessa API, e as solicitações restantes nesse segundo falharão. No entanto, as solicitações de outra API não serão afetadas.
Os buckets são recarregados automaticamente a uma taxa definida. Se o bucket ficar abaixo da capacidade máxima, um determinado número de tokens será adicionado novamente a ele a cada segundo até atingir sua capacidade máxima. Se o bucket estiver cheio quando os tokens de recarga forem adicionados, eles serão descartados. O bucket não pode conter mais do que seu número máximo de tokens. Por exemplo, o tamanho do bucket para `DescribeHosts`, uma ação de API *sem mutação*, é de cem tokens e a taxa de recarga é vinte tokens por segundo. Se você fizer cem solicitações `DescribeHosts` em um segundo, o bucket será reduzido para zero (0) tokens. O bucket será então recarregado com vinte tokens a cada segundo até atingir sua capacidade máxima de cem tokens. Isso significa que um bucket vazio atingirá sua capacidade máxima após 5 segundos se nenhuma solicitação for feita durante esse período.
Para fazer solicitações de API, não é necessário esperar que o bucket esteja completamente cheio. Você pode usar tokens de recarga à medida que eles são adicionados ao bucket. Se você usar imediatamente os tokens de recarga, o bucket não atingirá sua capacidade máxima. Por exemplo, o tamanho do bucket para `DescribeHosts`, uma ação de API *sem mutação*, é de cem tokens e a taxa de recarga é vinte tokens por segundo. Se você esgotar o bucket fazendo cem solicitações de API em um segundo, poderá continuar fazendo vinte solicitações de API por segundo usando os tokens de recarga à medida que forem adicionados ao bucket. O bucket só pode ser recarregado até a capacidade máxima quando você faz menos de vinte solicitações de API por segundo.
Para obter mais informações, consulte [Solicite tamanhos de buckets de token e taxas de recarga](#throttling-limits-rate-based).
### Limitação de taxa de recursos
Algumas ações de API, como `RunInstances` e `TerminateInstances`, conforme descrito na tabela a seguir, usam a limitação da taxa de recursos além da limitação da taxa de solicitação. Essas ações de API têm um bucket de tokens separado que se esgota com base no número de recursos afetados pela solicitações. Assim como os buckets de token de solicitação, os buckets de token de recurso têm um limite máximo que permite picos e uma taxa de recarga que permite manter um fluxo constante de solicitações pelo tempo necessário. Se você exceder um limite de bucket específico para uma API, inclusive quando um bucket ainda não foi reabastecido para comportar a próxima solicitação de API, a ação de API será limitada, mesmo que você não tenha atingido o limite total de controle de utilização da API.
Por exemplo, o tamanho do bucket de recursos para `RunInstances` é de mil tokens e a taxa de recarga é de dois tokens por segundo. Portanto, você pode iniciar imediatamente mil instâncias, usando qualquer número de solicitações de API, como uma solicitação para mil instâncias ou quatro solicitações para 250 instâncias. Depois que o bucket de tokens de recursos estiver vazio, você poderá iniciar até duas instâncias por segundo, usando uma solicitação para duas instâncias ou duas solicitações para uma instância.
Para obter mais informações, consulte [Tamanhos do bucket de tokens de recursos e taxas de recarga](#throttling-limits-cost-based).
## Solicite tamanhos de buckets de token e taxas de recarga
Para fins de limitação da taxa de solicitação, as ações da API são agrupadas nas seguintes categorias:
+ **Ações não mutantes**: ações de API que recuperam dados sobre recursos. Essa categoria geralmente inclui todas as ações de API `Describe*`, `List*`, `Search*` e `Get*`, como `DescribeRouteTables`, `SearchTransitGatewayRoutes` e `GetIpamPoolCidrs`. Essas ações de API geralmente têm os maiores limites de controle de utilização de API.
+ **Ações não filtradas e não paginadas sem mutação**: um subconjunto específico de ações de API sem mutação que, quando solicitadas sem especificar [paginação](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-pagination.html) ou [filtro](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/Using_Filtering.html#Filtering_Resources_CLI), usam tokens de um bucket de tokens menor. É recomendável que você use paginação e filtragem para que os tokens sejam deduzidos do bucket de tokens padrão (maior).
+ **Ações mutantes**: as ações de API que criam. modificam ou excluem recursos. Essa categoria geralmente inclui todas as ações de API que não são categorizadas como *ações não mutantes*, como `AllocateHosts`, `ModifyHosts` e `CreateCapacityReservation`. Essas ações têm um limite de controle de utilização menor do que as ações de API não mutantes.
+ **Ações que consomem muitos recursos**: ações de API mutantes que levam mais tempo e consomem mais recursos para serem concluídas. Essas ações têm um limite de controle de utilização até menor do que as *ações mutantes*. Elas têm controle de utilização separado de outras *ações mutantes*.
+ Ações **sem mutação do console — ações** de API sem mutação que são solicitadas no console da Amazon. EC2 Essas ações de API têm controle de utilização separado de outras ações de API não mutantes.
+ **Ações não categorizadas**: são ações de API que recebem seus próprios tamanhos de bucket de tokens e taxas de recarga, embora, por definição, se encaixem em uma das outras categorias.
| Categoria de ações de API | Ações | Capacidade máxima do bucket | Taxa de recarga do bucket |
| --- | --- | --- | --- |
| Ações não mutantes | As ações `Describe*`, `List*`, `Search*` e `Get*` da API que não estão incluídas em outra categoria. | 100 | 20 |
| Ações não mutantes não filtradas e não paginadas | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/ec2/latest/devguide/ec2-api-throttling.html) | 50 | 10 |
| Ações não mutantes | Todas as ações de API mutantes que não são *ações que consomem muitos recursos* ou *ações sem categoria*. | 50 | 5 |
| Ações que consomem muitos recursos | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/ec2/latest/devguide/ec2-api-throttling.html) | 50 | 5 |
| Ações não mutantes do console | As ações `Describe*``List*`,`Search*`, e de `Get*` API, que são chamadas pelo EC2 console da Amazon, mas não estão incluídas em outra categoria. | 100 | 10 |
| Ações sem categoria | Capacidade máxima do bucket | Taxa de recarga do bucket |
| --- | --- | --- |
| AcceptVpcEndpointConnections | 10 | 1 |
| AdvertiseByoipCidr | 1 | 0.1 |
| AssignIpv6Addresses | 100 | 5 |
| AssignPrivateIpAddresses | 100 | 5 |
| AssignPrivateNatGatewayAddress | 10 | 1 |
| AssociateCapacityReservationBillingOwner | 1 | 0,5 |
| AssociateEnclaveCertificateIamRole | 10 | 1 |
| AssociateIamInstanceProfile | 100 | 5 |
| AssociateNatGatewayAddress | 10 | 1 |
| AttachVerifiedAccessTrustProvider | 10 | 2 |
| AuthorizeClientVpnIngress | 5 | 2 |
| CancelDeclarativePoliciesReport | 1 | 1 |
| CopyImage | 100 | 1 |
| CreateClientVpnRoute | 5 | 2 |
| CreateCoipCidr | 5 | 1 |
| CreateCoipPool | 5 | 1 |
| CreateDefaultSubnet | 1 | 1 |
| CreateDefaultVpc | 1 | 1 |
| CreateLaunchTemplateVersion | 100 | 5 |
| CreateNatGateway | 10 | 1 |
| CreateNetworkInterface | 100 | 5 |
| CreateRestoreImageTask | 50 | 0.1 |
| CreateSnapshot | 100 | 5 |
| CreateSnapshots | 100 | 5 |
| CreateSpotDatafeedSubscription | 50 | 3 |
| CreateStoreImageTask | 50 | 0.1 |
| CreateSubnetCidrReservation | 5 | 1 |
| CreateTags | 100 | 10 |
| CreateVerifiedAccessEndpoint | 20 | 4 |
| CreateVerifiedAccessGroup | 10 | 2 |
| CreateVerifiedAccessInstance | 10 | 2 |
| CreateVerifiedAccessTrustProvider | 10 | 2 |
| CreateVolume | 100 | 5 |
| CreateVpcEndpoint | 4 | 0.3 |
| CreateVpcEndpointServiceConfiguration | 10 | 1 |
| DeleteClientVpnRoute | 5 | 2 |
| DeleteCoipCidr | 5 | 1 |
| DeleteCoipPool | 5 | 1 |
| DeleteCoipPoolPermission | 5 | 1 |
| DeleteNatGateway | 10 | 1 |
| DeleteNetworkInterface | 100 | 5 |
| DeleteSnapshot | 100 | 5 |
| DeleteSpotDatafeedSubscription | 50 | 3 |
| DeleteSubnetCidrReservation | 5 | 1 |
| DeleteQueuedReservedInstances | 5 | 5 |
| DeleteTags | 100 | 10 |
| DeleteVerifiedAccessEndpoint | 20 | 4 |
| DeleteVerifiedAccessGroup | 10 | 2 |
| DeleteVerifiedAccessInstance | 10 | 2 |
| DeleteVerifiedAccessTrustProvider | 10 | 2 |
| DeleteVolume | 100 | 5 |
| DeleteVpcEndpoints | 4 | 0.3 |
| DeleteVpcEndpointServiceConfigurations | 10 | 1 |
| DeprovisionByoipCidr | 1 | 0.1 |
| DeregisterImage | 100 | 5 |
| DescribeAggregateIdFormat | 10 | 10 |
| DescribeByoipCidrs | 1 | 0,5 |
| DescribeCapacityBlockExtensionOfferings | 10 | 0,15 |
| DescribeCapacityBlockOfferings | 10 | 0,15 |
| DescribeDeclarativePoliciesReports | 5 | 5 |
| DescribeHostReservations | 5 | 2 |
| DescribeHostReservationOfferings | 5 | 2 |
| DescribeIdentityIdFormat | 10 | 10 |
| DescribeIdFormat | 10 | 10 |
| DescribeInstanceTopology | 1 | 1 |
| DescribeMovingAddresses | 1 | 1 |
| DescribePrincipalIdFormat | 10 | 10 |
| DescribeReservedInstancesOfferings | 10 | 10 |
| DescribeSecurityGroupReferences | 20 | 5 |
| DescribeSpotDatafeedSubscription | 100 | 13 |
| DescribeSpotFleetInstances | 100 | 5 |
| DescribeSpotFleetRequestHistory | 100 | 5 |
| DescribeSpotFleetRequests | 50 | 3 |
| DescribeStaleSecurityGroups | 20 | 5 |
| DescribeStoreImageTasks | 50 | 0,5 |
| DescribeVerifiedAccessInstanceLoggingConfigurations | 10 | 2 |
| DetachVerifiedAccessTrustProvider | 10 | 2 |
| DisableFastLaunch | 5 | 2 |
| DisableImageBlockPublicAccess | 1 | 0,1 |
| DisableSnapshotBlockPublicAccess | 1 | 0,1 |
| DisassociateCapacityReservationBillingOwner | 1 | 0,5 |
| DisassociateEnclaveCertificateIamRole | 10 | 1 |
| DisassociateIamInstanceProfile | 100 | 5 |
| DisassociateNatGatewayAddress | 10 | 1 |
| EnableFastLaunch | 5 | 2 |
| EnableImageBlockPublicAccess | 1 | 0,1 |
| EnableSnapshotBlockPublicAccess | 1 | 0.1 |
| GetAssociatedEnclaveCertificateIamRoles | 10 | 1 |
| GetDeclarativePoliciesReportSummary | 5 | 5 |
| GetHostReservationPurchasePreview | 5 | 2 |
| ModifyImageAttribute | 100 | 5 |
| ModifyInstanceMetadataDefaults | 2 | 2 |
| ModifyInstanceMetadataOptions | 100 | 5 |
| ModifyLaunchTemplate | 100 | 5 |
| ModifyNetworkInterfaceAttribute | 100 | 5 |
| ModifySnapshotAttribute | 100 | 5 |
| ModifyVerifiedAccessEndpoint | 20 | 4 |
| ModifyVerifiedAccessEndpointPolicy | 20 | 4 |
| ModifyVerifiedAccessGroup | 10 | 2 |
| ModifyVerifiedAccessGroupPolicy | 20 | 4 |
| ModifyVerifiedAccessInstance | 10 | 2 |
| ModifyVerifiedAccessInstanceLoggingConfiguration | 10 | 2 |
| ModifyVerifiedAccessTrustProvider | 10 | 2 |
| ModifyVpcEndpoint | 4 | 0.3 |
| ModifyVpcEndpointServiceConfiguration | 10 | 1 |
| MoveAddressToVpc | 1 | 1 |
| ProvisionByoipCidr | 1 | 0.1 |
| PurchaseCapacityBlock | 10 | 0,15 |
| PurchaseCapacityBlockExtension | 10 | 0,15 |
| PurchaseHostReservation | 5 | 2 |
| PurchaseReservedInstancesOffering | 5 | 5 |
| RejectVpcEndpointConnections | 10 | 1 |
| RestoreAddressToClassic | 1 | 1 |
| RevokeClientVpnIngress | 5 | 2 |
| RunInstances | 5 | 2 |
| StartDeclarativePoliciesReport | 1 | 1 |
| StartInstances | 5 | 2 |
| TerminateInstances | 100 | 5 |
| UnassignPrivateIpAddresses | 100 | 5 |
| UnassignPrivateNatGatewayAddress | 10 | 1 |
| WithdrawByoipCidr | 1 | 0.1 |
## Tamanhos do bucket de tokens de recursos e taxas de recarga
A tabela a seguir lista os tamanhos dos buckets de tokens de recursos e as taxas de recarga para ações de API que usam limitação de taxa de recursos.
| Ação da API | Capacidade máxima do bucket | Taxa de recarga do bucket |
| --- | --- | --- |
| RunInstances | 1000 | 2 |
| TerminateInstances | 1000 | 20 |
| StartInstances | 1000 | 2 |
| StopInstances | 1000 | 20 |
## Monitore o controle de utilização da API
Você pode usar CloudWatch a Amazon para monitorar suas solicitações de EC2 API da Amazon e coletar e rastrear métricas sobre a limitação de APIs. Você também pode criar um alarme que avise quando estiver perto de atingir os limites de controle de utilização da API. Para obter mais informações, consulte [Monitore solicitações de EC2 API da Amazon usando a Amazon CloudWatchMonitore solicitações de API usando CloudWatch](monitor.md).
## Notas tentativas e recuo exponencial
É possível que sua aplicação precise tentar novamente uma solicitação de API. Por exemplo:
+ Para conferir se há uma atualização no status de um recurso.
+ Para enumerar um grande número de recursos (por exemplo, todos os seus volumes).
+ Para repetir uma solicitação depois que ela falha com um erro do servidor (5xx) ou um erro de controle de utilização.
No entanto, erros de cliente (4xx) indicam que você precisa analisar a solicitação para corrigir o problema antes de tentar novamente.
**Alterações de status de recursos**
Antes de iniciar a sondagem para conferir se há atualizações de status, aguarde a conclusão da solicitação. Por exemplo, aguarde alguns minutos antes de conferir se sua instância está ativa. Ao iniciar a sondagem, use um intervalo de latência apropriado entre as solicitações sucessivas para reduzir a taxa de solicitações de API. Para obter os melhores resultados, use um intervalo de latência crescente ou variável.
Como alternativa, você pode usar EventBridge a Amazon para notificá-lo sobre o status de alguns recursos. Por exemplo, você pode usar o evento **EC2 Instance State-Change Notification** para notificá-lo sobre uma mudança de estado em uma instância. Para obter mais informações, consulte [Automatizar a Amazon EC2 usando EventBridge](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/automating_with_eventbridge.html).
**Novas tentativas**
Quando você precisar fazer a sondagem ou repetir uma solicitação de API, é recomendável usar um algoritmo de recuo exponencial para calcular o intervalo de latência entre as solicitações de API. A ideia por trás do recuo exponencial é usar esperas progressivamente mais longas entre as novas tentativas para respostas de erro consecutivas. Você deve implementar um intervalo máximo de atraso, bem como um número máximo de novas tentativas. Também é possível usar instabilidade (atraso aleatório) para evitar colisões sucessivas. Para obter mais informações, consulte [Tempos limite, novas tentativas e recuo com variação de sinal](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/).
Cada AWS SDK implementa a lógica de repetição automática. Para obter mais informações, consulte o [comportamento de repetição](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) no *Guia de referência de ferramentas AWS SDKs e ferramentas*.
## Solicitar um aumento de limite de
É possível solicitar um aumento dos limites de controle de utilização de API para a Conta da AWS.
**Recomendações**
+ Solicite no máximo três vezes o limite existente em uma única solicitação.
+ Priorize o aumento das taxas de recarga do bucket antes de aumentar a respectiva capacidade máxima.
+ Se a taxa de recarga do bucket solicitada exceder a capacidade máxima, aumente a capacidade máxima do bucket ao mesmo tempo.
+ Forneça todas as ações de API que exijam aumento. Os limites são aplicados às ações individuais da API, não às categorias de ação da API.
+ Há limites de taxa de solicitação e taxa de recursos para as seguintes ações de API: `RunInstances`, `StartInstances`, `StopInstances` e `TerminateInstances`. Indique qual limite deve ser aumentado.
**Como solicitar acesso a esse atributo**
1. Abra o [AWS Support Center](https://console.aws.amazon.com/support/home#/).
1. Escolha **Criar caso**.
1. Escolha **Conta e faturamento**.
1. Em **Serviço**, escolha **Informações gerais e introdução**.
1. Em **Categoria**, escolha **Uso AWS e serviços**.
1. Selecione **Próxima etapa: informações adicionais**.
1. Em **Subject (Assunto)**, insira **Request an increase in my Amazon EC2 API throttling limits**.
1. Em **Descrição**, copie o modelo a seguir e forneça as informações necessárias.
```
Please increase the API throttling limits for my account.
Related page: https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-throttling.html
Description: Brief notes about your use case. If available, include the IDs
of a few Amazon EC2 requests that were throttled.
Time window: One-hour window when peak throttling or usage occurred.
region_1 request rate increases:
action: new_bucket_maximum_capacity
action: new_bucket_refill_rate
action: new_bucket_maximum_capacity|new_bucket_refill_rate
region_1 resource rate increases:
action: new_bucket_maximum_capacity
action: new_bucket_refill_rate
action: new_bucket_maximum_capacity|new_bucket_refill_rate
region_2 request rate increases:
action: new_bucket_maximum_capacity
action: new_bucket_refill_rate
action: new_bucket_maximum_capacity|new_bucket_refill_rate
region_2 resource rate increases:
action: new_bucket_maximum_capacity
action: new_bucket_refill_rate
action: new_bucket_maximum_capacity|new_bucket_refill_rate
```
1. Escolha **Próxima etapa: solucione ou entre em contato conosco**.
1. Escolha a guia **Fale conosco** e selecione o idioma e o método de contato preferidos.
1. Selecione **Enviar**.
# Paginação na API do Amazon EC2
Recomendamos que você use a paginação ao chamar ações de descrição que podem exibir um grande número de resultados, como `DescribeInstances`. O uso da paginação limita o número de itens exibidos por uma chamada de descrição e o tempo necessário para o retorno da chamada. Se você tiver um grande número de recursos, chamadas não paginadas poderão ter controle de utilização e atingir o tempo limite. Portanto, a latência geral é melhor com chamadas paginadas do que com chamadas não paginadas porque as chamadas paginadas são consistentemente bem-sucedidas.
Para obter mais informações, consulte [Pagination](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Query-Requests.html#api-pagination) (Paginação) em *Amazon EC2 API Reference* (Referência de API do Amazon EC2).
## Práticas recomendadas
Sempre que possível, especifique uma lista de IDs de recursos em suas chamadas de descrição. Essa é a maneira mais rápida de descrever um grande número de recursos. Observe que você não deve especificar mais de mil IDs em uma única chamada. Veja um exemplo a seguir.
```
private List describeMyInstances(List ids){
if (ids == null || ids.isEmpty()) {
return ImmutableList.of();
}
final DescribeInstancesRequest request = new DescribeInstancesRequest()
.withInstanceIds(ids);
return ec2.describeInstances(request).getReservations();
}
```
Caso você não possa especificar IDs de recursos em suas chamadas de descrição, é altamente recomendável usar a paginação. Veja um exemplo a seguir.
```
private List describeMyInstances(final Collection filters){
final DescribeInstancesRequest request = new DescribeInstancesRequest()
.withFilters(filters)
.withMaxResults(1000);
List reservations = new ArrayList<>();
String nextToken = null;
do {
request.setNextToken(nextToken);
final DescribeInstancesResult response = ec2.describeInstances(request);
reservations.addAll(response.getReservations());
nextToken = response.getNextToken();
} while (nextToken != null);
return reservations;
}
```
Se você precisar repetir uma chamada paginada, use o [recuo exponencial com instabilidade](ec2-api-throttling.md#api-backoff).
## Problemas comuns
Veja a seguir exemplos de código que inadvertidamente faz chamadas não paginadas.
**Example Exemplo de problema: transmitir uma lista vazia de IDs de recursos**
O código a seguir usa uma lista de IDs. No entanto, se a lista estiver vazia, o resultado será uma chamada não paginada.
```
private List describeMyInstances(List ids){
final DescribeInstancesRequest request = new DescribeInstancesRequest()
.withInstanceIds(ids);
return ec2.describeInstances(request).getReservations();
}
```
Para corrigir esse problema, a lista não deve estar vazia antes de fazer a chamada de descrição.
```
private List describeMyInstances(List ids){
if (ids == null || ids.isEmpty()) {
return ImmutableList.of();
// OR
return Lists.newArrayList();
// OR
return new ArrayList<>();
}
final DescribeInstancesRequest request = new DescribeInstancesRequest()
.withInstanceIds(ids);
return ec2.describeInstances(request).getReservations();
}
```
**Example Exemplo de problema: MaxResults não definido**
O código a seguir confere e usa `nextToken`, mas não define `MaxResults`.
```
private List describeMyInstances(final Collection filters){
final DescribeInstancesRequest request = new DescribeInstancesRequest()
.withFilters(filters);
List reservations = new ArrayList<>();
String nextToken = null;
do {
request.setNextToken(nextToken);
final DescribeInstancesResult response = ec2.describeInstances(request);
reservations.addAll(response.getReservations());
nextToken = response.getNextToken();
} while (nextToken != null);
return reservations;
}
```
Para corrigir esse problema, adicione `withMaxResults` da forma a seguir.
```
private List describeMyInstances(final Collection filters){
final DescribeInstancesRequest request = new DescribeInstancesRequest()
.withFilters(filters)
.withMaxResults(1000);
List reservations = new ArrayList<>();
String nextToken = null;
do {
request.setNextToken(nextToken);
final DescribeInstancesResult response = ec2.describeInstances(request);
reservations.addAll(response.getReservations());
nextToken = response.getNextToken();
} while (nextToken != null);
return reservations;
}
```