View a markdown version of this page

Solicitações de consulta para o Amazon EC2 - Amazon Elastic Compute Cloud
Estrutura de uma solicitação GETParâmetros de consultaAutenticação da API deEstruturas de resposta à consultaPaginaçãoEvitando solicitações via HTTP

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

Solicitações de consulta para o Amazon EC2

As solicitações de consulta são solicitações HTTP ou HTTPS que usam o verbo HTTP GET ou POST e um parâmetro de consulta chamadoAction. Para cada ação da API do Amazon EC2, você pode escolher se quer usar GET ou POST. Independentemente do verbo escolhido, os mesmos dados são enviados e recebidos. Para obter uma lista das ações da API do Amazon EC2, consulte Ações.

Estrutura de uma solicitação GET

A documentação do Amazon EC2 apresenta as solicitações GET como URLs, que podem ser usadas diretamente em um navegador.

nota

Como as solicitações GET são URLs, você deve codificar em URL os valores dos parâmetros. Na documentação do Amazon EC2, deixamos os exemplos de solicitações GET sem codificação para facilitar a leitura.

A solicitação consiste no seguinte:

  • Ponto final: o URL que serve como ponto de entrada para o serviço web. Para obter mais informações, consulte os endpoints de serviço do Amazon EC2.

  • Ação: a ação que você deseja realizar; por exemplo, use RunInstances para iniciar uma instância.

  • Parâmetros: qualquer parâmetro para a ação; cada parâmetro é separado por um e comercial (&).

  • Versão: a versão da API a ser usada. Para a API do Amazon EC2, a versão é 2016-11-15.

  • Parâmetros de autorização: os parâmetros de autorização AWS usados para garantir a validade e a autenticidade da solicitação. O Amazon EC2 é compatível com Signature versão 2 e Signature versão 4. Recomendamos usar a Versão 4 da assinatura. Para obter mais informações, consulte Solicitações de AWS API de assinatura no Guia do usuário do IAM.

Os seguintes parâmetros opcionais podem ser incluídos em sua solicitação:

  • DryRun: verifica se você tem as permissões necessárias para a ação, sem realmente fazer a solicitação. Se você tiver as permissões necessárias, a solicitação retornaráDryRunOperation; caso contrário, ela retornaráUnauthorizedOperation.

  • SecurityToken: o token de segurança temporário obtido por meio de uma chamada para AWS Security Token Service.

Para obter mais informações sobre parâmetros comuns para solicitações de API, consulte Parâmetros de consulta comuns.

Veja a seguir um exemplo de solicitação que executa instâncias:

https://ec2.amazonaws.com/?Action=RunInstances&ImageId=ami-2bb65342&MaxCount=3&MinCount=1&Placement.AvailabilityZone=us-east-1a&Monitoring.Enabled=true&Version=2016-11-15&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIDEXAMPLE%2F20130813%2Fus-east-1%2Fec2%2Faws4_request&X-Amz-Date=20130813T150206Z&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-date&X-Amz-Signature=525d1a96c69b5549dd78dbbec8efe264102288b83ba87b7d58d4b76b71f59fd2
Content-type: application/json
host:ec2.amazonaws.com

Para tornar essas solicitações de exemplo ainda mais fáceis de ler, a AWS documentação pode apresentá-las no seguinte formato:

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Placement.AvailabilityZone=us-east-1a
&Monitoring.Enabled=true
&Version=2016-11-15
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIAIOSFODNN7EXAMPLEus-east-1%2Fec2%2Faws4_request
&X-Amz-Date=20130813T150206Z
&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-date
&X-Amz-Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456c
Content-type: application/json
host:ec2.amazonaws.com

A primeira linha especifica o ponto final da solicitação. Depois do endpoint há um ponto de interrogação (?), que separa o endpoint dos parâmetros. Para obter mais informações sobre endpoints do Amazon EC2, consulte Endpoints de serviço do Amazon EC2.

O parâmetro Action indica a ação a ser realizada. Para obter uma lista completa de ações, consulte Ações. As linhas restantes especificam parâmetros adicionais para a solicitação.

No exemplo de solicitações de consulta que apresentamos na documentação da API do Amazon EC2, omitimos os cabeçalhos, os parâmetros comuns necessários e os parâmetros de autenticação para facilitar o foco nos parâmetros da ação. Nós os substituímos pela string &AUTHPARAMS literal para lembrá-lo de que você deve incluir esses parâmetros em sua solicitação; por exemplo:

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Placement.AvailabilityZone=us-east-1a
&Monitoring.Enabled=true
&AUTHPARAMS
Importante

Antes de especificar o ID da chave de acesso para o Credential parâmetro AWSAccessKeyId or, revise e siga as orientações nas credenciais AWS de segurança.

Parâmetros de consulta

Cada solicitação de consulta deve incluir os parâmetros comuns necessários para lidar com a autenticação e a seleção de uma ação. Os parâmetros de consulta diferenciam maiúsculas de minúsculas

Algumas operações levam listas de parâmetros. Essas listas são especificadas usando a notação param.n, em que n é um número inteiro começando em 1.

O exemplo a seguir adiciona vários dispositivos a um mapeamento de dispositivos de bloco usando uma lista de BlockDeviceMapping parâmetros.

http://ec2.amazonaws.com/?Action=RunInstances
&ImageId.1=ami-72aa081b
...
&BlockDeviceMapping.1.DeviceName=/dev/sdj
&BlockDeviceMapping.1.Ebs.NoDevice=true
&BlockDeviceMapping.2.DeviceName=/dev/sdh
&BlockDeviceMapping.2.Ebs.VolumeSize=300
&BlockDeviceMapping.3.DeviceName=/dev/sdc
&BlockDeviceMapping.3.VirtualName=ephemeral1
&AUTHPARAMS

Autenticação da API de

Você pode enviar solicitações de consulta pelo protocolo HTTP ou HTTPS.

Independentemente do protocolo usado, você deve incluir uma assinatura em cada solicitação de consulta. O Amazon EC2 é compatível com Signature versão 2 e Signature versão 4. Recomendamos usar a Versão 4 da assinatura. Para obter mais informações, consulte Solicitações de AWS API de assinatura no Guia do usuário do IAM.

As solicitações do Signature Version 4 permitem que você especifique todos os parâmetros de autorização em um único cabeçalho, por exemplo:

Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Amz-Date: 20130813T150211Z
Host: ec2.amazonaws.com
Authorization: AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/202230813/us-east-1/ec2/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456c

http://ec2.amazonaws.com/?Action=RunInstances
ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Monitoring.Enabled=true
&Placement.AvailabilityZone=us-east-1a
&Version=2016-11-15

Estruturas de resposta à consulta

Em resposta a uma solicitação de consulta, o serviço retorna uma estrutura de dados XML que está em conformidade com um esquema XML definido para o Amazon EC2. A estrutura de uma resposta XML é específica para a solicitação associada. Em geral, os tipos de dados de resposta são nomeados de acordo com a operação realizada e se o tipo de dados é um contêiner (pode ter filhos). Exemplos de contêineres incluem groupSet grupos de segurança e keySet pares de chaves (veja o exemplo a seguir). Os elementos do item são filhos dos contêineres e seu conteúdo varia de acordo com a função do contêiner.

Cada resposta bem-sucedida inclui uma ID de solicitação em um requestId elemento, e toda resposta malsucedida inclui uma ID de solicitação em um RequestID elemento. O valor é uma string exclusiva AWS atribuída. Se você tiver problemas com uma solicitação específica, AWS solicitará o ID da solicitação para ajudar a solucionar o problema. Veja a seguir um exemplo de resposta.

<DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2016-11-15/">
  <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>
  <keySet>
    <item>
      <keyName>gsg-keypair</keyName>
      <keyFingerprint>
         00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
      </keyFingerprint>
    </item>
  </keySet>
</DescribeKeyPairsResponse>
Considerações

  • A partir de 31 de julho de 2024, para quaisquer novas ações de API do Amazon EC2 ou regiões AWS recém-suportadas, as estruturas de dados XML nas respostas não incluirão novas linhas e recuos. Se você usa um cliente personalizado, certifique-se de que ele não dependa das respostas, incluindo novas linhas e recuos.

  • A partir de 31 de julho de 2025, as estruturas de dados XML nas respostas não incluirão mais novas linhas e recuos. Essa alteração reduzirá o tamanho das respostas. Se você usa um cliente personalizado, certifique-se de que ele não dependa das respostas, incluindo novas linhas e recuos.

  • A ordem dos elementos na resposta, incluindo aqueles dentro de estruturas aninhadas, pode variar. Os aplicativos não devem presumir que os elementos aparecem em uma ordem específica.

Paginação

Para ações que podem retornar uma longa lista de itens, a API do Amazon EC2 inclui parâmetros para suportar a paginação:MaxResults, NextToken (entrada) e nextToken (saída). Com a paginação, você especifica um tamanho para MaxResults e, em seguida, cada chamada retorna 0 para MaxResults itens e conjuntos. nextToken Se houver itens adicionais para iterar, não nextToken é nulo e você pode especificar seu valor no NextToken parâmetro de uma chamada subsequente para obter o próximo conjunto de itens. Com a paginação, você continua chamando a ação até que nextToken seja nula, mesmo que receba menos de MaxResults itens, incluindo zero itens.

Se você chamar uma ação de descrição da API com uma lista de IDs eMaxResults, a solicitação falhará com o erroInvalidParameterCombination.

Recomendamos que você use a paginação ao usar ações de descrição que podem potencialmente retornar um grande número de resultados, como. DescribeInstances O uso da paginação limita o número de itens retornados e o tempo necessário para que essas chamadas retornem.

Para obter mais informações, consulte Paginação no Amazon EC2 Developer Guide.

Evitando solicitações via HTTP

Se sua carga de trabalho não exigir que você use HTTP, recomendamos que você evite usá-la para evitar a transmissão e o recebimento de dados não criptografados e, em vez disso, use HTTPS. Você pode usar a chave de condição aws:SecureTransportglobal do IAM em suas políticas do IAM para impedir que os usuários enviem solicitações por HTTP.

O exemplo de política a seguir impede que os usuários enviem solicitações por HTTP.

{
    "Statement": [
        {
            "Sid": "AllowAllEC2HttpsRequests",
            "Effect": "Allow",
            "Action": "ec2:*",
            "Resource": "*",
            "Condition": {
                "StringEqualsIgnoreCase": {
                    "aws:SecureTransport": "true"
                }
            }
        }
    ]
}