View a markdown version of this page

Solicitudes de consulta para Amazon EC2 - Amazon Elastic Compute Cloud
Estructura de una solicitud GETParámetros de consultaAutenticación mediante la APIEstructuras de respuesta a consultasPaginaciónImpedir solicitudes a través de HTTP

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

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 de Amazon EC2, consulte Acciones.

Estructura de una solicitud GET

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

nota

Como las solicitudes GET son 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 consiste en 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, utilizarla RunInstances para lanzar una instancia.

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

  • Versión: la versión de la 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 la autenticidad de la solicitud. Amazon EC2 admite la versión de firma 2 y la versión de firma 4. Le recomendamos utilizar la versión de firma 4 de . Para obtener más información, consulte Firmar solicitudes de AWS API en la guía del usuario de IAM.

Se pueden incluir los siguientes parámetros opcionales en su solicitud:

  • DryRun: Comprueba si tienes los permisos necesarios para la acción, sin realizar realmente la solicitud. Si tienes los permisos necesarios, la solicitud se devuelveDryRunOperation; 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 para las solicitudes de API, consulte 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. https://docs.aws.amazon.com/AWSEC2/latest/APIReference/query-apis.html Las líneas restantes especifican parámetros adicionales para la solicitud.

En los ejemplos de solicitudes de consulta que presentamos en la documentación de la API de Amazon EC2, omitimos los encabezados, los parámetros obligatorios más 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, revisa y sigue las instrucciones que aparecen en 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 entre mayúsculas y minúsculas.

Algunas operaciones toman listas de parámetros. Estas listas se especifican con la notación param.n, donde n es un número entero que empieza por 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

Autenticación mediante la API

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

Independientemente del protocolo que utilices, debes incluir una firma en cada solicitud de consulta. Amazon EC2 admite la versión de firma 2 y la versión de firma 4. Le recomendamos utilizar la versión de firma 4 de . Para obtener más información, consulte Firmar solicitudes de AWS API en la guía del usuario de IAM.

Las solicitudes de firma de la versión 4 permiten especificar todos los parámetros de autorización en un único 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 denominan en función de la operación realizada y de si el tipo de datos es un contenedor (puede tener elementos secundarios). 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 artículos 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 fallida incluye un identificador de solicitud en un RequestID elemento. El valor es una cadena única que AWS asigna. Si alguna vez tienes problemas con una solicitud en particular, te AWS pediremos el identificador de la solicitud para ayudar 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, en el caso de las nuevas acciones de la API de Amazon EC2 o de AWS las regiones recientemente admitidas, las estructuras de datos XML de las respuestas no incluirán líneas ni indentaciones nuevas. Si utiliza un cliente personalizado, asegúrese de que no se base en las respuestas, incluidas las nuevas líneas e indentaciones.

  • 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 las nuevas líneas e indentaciones.

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

Paginación

En el caso de las acciones que pueden arrojar una lista larga de artículos, la API de Amazon EC2 incluye parámetros que permiten la paginación:MaxResults, NextToken (entrada) y nextToken (salida). Con la paginación, usted especifica un tamaño para los MaxResults elementos MaxResults y conjuntos y, a continuación, cada llamada devuelve 0. nextToken Si hay elementos adicionales para 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, continúas llamando a la acción hasta que nextToken sea nula, incluso si recibes menos de MaxResults elementos, incluido cero.

Si ejecutas una acción de descripción de la API con una lista de identificadores yMaxResults, la solicitud falla y aparece el errorInvalidParameterCombination.

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

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

Impedir 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 sin cifrar y que, en su lugar, utilice HTTPS. Puedes usar la clave de condición de IAM aws:SecureTransport global 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"
                }
            }
        }
    ]
}