Solicitudes de consulta para Amazon EC2

Las solicitudes de consulta son solicitudes HTTP o HTTPS que utilizan el verbo HTTP GET o POST y un parámetro de consulta denominado. Action Para cada acción de la API de Amazon EC2, puede elegir si desea utilizar GET o POST. Independientemente del verbo que elija, se envían y reciben los mismos datos. Para obtener una lista de las acciones de la API Amazon EC2, consulte Acciones.

Estructura de una solicitud GET

La documentación de Amazon EC2 presenta las solicitudes GET como URL, que se pueden utilizar directamente en un navegador.

nota

Como las solicitudes GET son direcciones URL, debe codificar en URL los valores de los parámetros. En la documentación de Amazon EC2, dejamos las solicitudes GET de ejemplo sin codificar para que sean más fáciles de leer.

La solicitud consta de lo siguiente:

• Punto final: la URL que sirve como punto de entrada para el servicio web. Para obtener más información, consulte los puntos de enlace del servicio Amazon EC2.

• Acción: la acción que desea realizar; por ejemplo, úsela RunInstances para lanzar una instancia.

• Parámetros: todos los parámetros de la acción; cada parámetro está separado por un signo (&).

• Versión: la versión de API que se va a utilizar. Para la API de Amazon EC2, la versión es el 15 de noviembre de 2016.

• Parámetros de autorización: los parámetros de autorización que se AWS utilizan para garantizar la validez y autenticidad de la solicitud. Amazon EC2 es compatible con Signature Version 2 y Signature Version 4. Le recomendamos utilizar la versión de firma 4 de . Para obtener más información, consulte Firmar las solicitudes de AWS API en la Guía del usuario de IAM.

Puede incluir los siguientes parámetros opcionales en su solicitud:

• DryRun: Comprueba si tienes los permisos necesarios para la acción, sin necesidad de realizar realmente la solicitud. Si tiene los permisos necesarios, se devuelve la solicitudDryRunOperation; de lo contrario, se devuelveUnauthorizedOperation.

• SecurityToken: El token de seguridad temporal obtenido mediante una llamada a AWS Security Token Service.

Para obtener más información sobre los parámetros comunes de las solicitudes de API, consulta los parámetros de consulta comunes.

A continuación, se muestra un ejemplo de solicitud que lanza instancias:

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 que estas solicitudes de ejemplo sean aún más fáciles de leer, AWS la documentación puede presentarlas en el siguiente 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

La primera línea especifica el punto final de la solicitud. Después del punto de enlace hay un signo de interrogación (?) que separa el punto de enlace de los parámetros. Para obtener más información sobre los puntos de enlace de Amazon EC2, consulte los puntos de enlace de servicio de Amazon EC2.

El parámetro Action indica la acción que se va a llevar a cabo. Para obtener una lista completa de las acciones, consulte Acciones. Las líneas restantes especifican parámetros adicionales para la solicitud.

En el ejemplo de solicitudes de consulta que presentamos en la documentación de la API de Amazon EC2, omitimos los encabezados, los parámetros obligatorios comunes y los parámetros de autenticación para que pueda centrarse más fácilmente en los parámetros de la acción. Los sustituimos por la cadena &AUTHPARAMS literal para recordarle que debe incluir estos parámetros en su solicitud; por ejemplo:

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 el identificador de la clave de acceso para el Credential parámetro AWSAccessKeyId o, revise y siga las instrucciones de las credenciales AWS de seguridad.

Parámetros de consulta

Cada solicitud de consulta debe incluir los parámetros comunes necesarios para gestionar la autenticación y la selección de una acción. Los parámetros de consulta distinguen mayúsculas de minúsculas.

Algunas operaciones toman listas de parámetros. Estas listas se especifican mediante la notación param.n, donde n es un número entero que comienza en 1.

El siguiente ejemplo agrega varios dispositivos a un mapeo de dispositivos de bloques mediante una 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

Consulta la autenticación de la API

Puede enviar solicitudes de consulta a través del protocolo HTTP o HTTPS.

Independientemente del protocolo que utilice, debe incluir una firma en cada solicitud de consulta. Amazon EC2 es compatible con Signature Version 2 y Signature Version 4. Le recomendamos utilizar la versión de firma 4 de . Para obtener más información, consulte Firmar las solicitudes de AWS API en la Guía del usuario de IAM.

Las solicitudes de la versión 4 de Signature permiten especificar todos los parámetros de autorización en un solo encabezado, por ejemplo:

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

Estructuras de respuesta a consultas

En respuesta a una solicitud de consulta, el servicio devuelve una estructura de datos XML que se ajusta a un esquema XML definido para Amazon EC2. La estructura de una respuesta XML es específica de la solicitud asociada. En general, los tipos de datos de respuesta se nombran en función de la operación realizada y de si el tipo de datos es un contenedor (puede tener hijos). Entre los ejemplos de contenedores se incluyen groupSet los grupos keySet de seguridad y los pares de claves (consulte el ejemplo siguiente). Los elementos de los elementos son elementos secundarios de los contenedores y su contenido varía según la función del contenedor.

Cada respuesta correcta incluye un identificador de solicitud en un requestId elemento y cada respuesta no satisfactoria incluye un identificador de solicitud en un RequestID elemento. El valor es una cadena única que se AWS asigna. Si alguna vez tienes problemas con una solicitud en particular, te AWS solicitará el identificador de la solicitud para ayudarte a solucionar el problema. A continuación se muestra un ejemplo de respuesta.

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

Consideraciones

• A partir del 31 de julio de 2024, para cualquier acción nueva de la API de Amazon EC2 o AWS regiones recientemente compatibles, las estructuras de datos XML de las respuestas no incluirán nuevas líneas ni sangrados. Si utiliza un cliente personalizado, asegúrese de que no se base en las respuestas, incluidas las nuevas líneas y sangrados.

• A partir del 31 de julio de 2025, las estructuras de datos XML de las respuestas dejarán de incluir nuevas líneas e indentaciones. Este cambio reducirá el tamaño de las respuestas. Si utilizas un cliente personalizado, asegúrate de que no se base en las respuestas, incluidas nuevas líneas e indentaciones.

• El orden de los elementos de la respuesta, incluidos los que se encuentran dentro de las estructuras anidadas, puede variar. Las aplicaciones no deben dar por sentado que los elementos aparecen en un orden determinado.

Paginación

Para las acciones que pueden devolver una larga lista de elementos, la API Amazon EC2 incluye parámetros para admitir la paginación:MaxResults, NextToken (entrada) y nextToken (salida). Con la paginación, se especifica un tamaño para los MaxResults elementos MaxResults y conjuntos y, a continuación, cada llamada devuelve 0. nextToken Si hay elementos adicionales que iterar, no nextToken es nulo y puede especificar su valor en el NextToken parámetro de una llamada posterior para obtener el siguiente conjunto de elementos. Con la paginación, puedes seguir convocando la acción hasta que nextToken sea nula, incluso si recibes menos de MaxResults elementos, incluidos cero.

Si ejecutas una acción de descripción de la API con una lista de identificadores y otraMaxResults, la solicitud fallará y aparecerá el errorInvalidParameterCombination.

Te recomendamos que utilices la paginación cuando utilices acciones de descripción que puedan arrojar una gran cantidad de resultados, comoDescribeInstances: El uso de la paginación limita el número de elementos devueltos y el tiempo que tardan estas llamadas en volver.

Para obtener más información, consulte Paginación en la Guía para desarrolladores de Amazon EC2.

Prevenir las solicitudes a través de HTTP

Si su carga de trabajo no requiere que utilice HTTP, le recomendamos que evite usarlo para evitar la transmisión y recepción de datos no cifrados y que utilice HTTPS en su lugar. Puedes usar la clave de condición de IAM aws:SecureTransportglobal en tus políticas de IAM para evitar que los usuarios envíen solicitudes a través de HTTP.

El siguiente ejemplo de política impide que los usuarios envíen solicitudes a través de HTTP.

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