Uso de la API de consultas

Parámetros de consulta

Las solicitudes basadas en consultas HTTP son solicitudes HTTP que utilizan el verbo HTTP GET o POST y un parámetro de consulta denominado Action.

Cada solicitud de consulta debe incluir algunos parámetros comunes para realizar la autenticación y la selección de una acción.

Algunas operaciones toman listas de parámetros. Estas listas se especifican utilizando la notación param.n. Los valores de n son números enteros a partir de 1.

Autenticación de solicitudes de consulta

Solo se pueden enviar solicitudes de consulta a través de HTTPS y cada una de ellas debe incluir una firma. En esta sección se describe cómo crear la firma. El método que se describe en el procedimiento siguiente se conoce como firma versión 4.

A continuación se indican los pasos básicos que se utilizan para autenticar las solicitudes en AWS. En este proceso se presupone que se ha registrado en AWS y que dispone de un ID de clave de acceso y una clave de acceso secreta.

Proceso de autenticación de consulta

1. El remitente crea una solicitud para AWS.

2. El remitente calcula la firma de la solicitud, una operación hash para código de autenticación de mensajes (HMAC) basado en hash mediante una función hash SHA-1, tal y como se define en la siguiente sección de este tema.

3. El remitente de la solicitud envía a AWS los datos de la misma, la firma y el ID de clave de acceso (el identificador de clave de la clave de acceso secreta utilizada).

4. AWS utiliza el ID de clave de acceso para buscar la clave de acceso secreta.

5. AWS genera una firma a partir de los datos de la solicitud y la clave de acceso secreta con el mismo algoritmo que se utilizó para calcular la firma de la solicitud.

6. Si las firmas coinciden, se considera que la solicitud es auténtica. Si la comparación falla, se descarta la solicitud y AWS devuelve una respuesta de error.

nota

Si una solicitud contiene un parámetro Timestamp, la firma calculada para la solicitud caduca 15 minutos después de su valor.

Si una solicitud contiene un parámetro Expires, la firma caduca en el momento especificado por el parámetro Expires.

Para calcular la firma de la solicitud

1. Cree la cadena de consulta canónica que necesitará más adelante en este procedimiento:

   1. Ordene los componentes UTF-8 de la cadena de consulta por nombre de parámetro con el orden de bytes natural. Los parámetros pueden proceder de GET URI o del cuerpo de la solicitud POST (cuando Content-Type es application/x-www-form-urlencoded).

   2. Codifique como dirección URL el nombre y los valores del parámetro, aplicando las reglas siguientes:

      1. No incluya en la codificación de la dirección URL ninguno de los caracteres no reservados definidos en la norma RFC 3986. Estos caracteres no reservados son A–Z, a–z, 0–9, guion (-), carácter de subrayado (_), punto (.) y tilde (~).

      2. Codifique con signos de porcentaje el resto de los caracteres con %XY, donde X e Y son caracteres hexadecimales (0-9 y A-F mayúsculas).

      3. Codifique con signos de porcentaje los caracteres extendidos UTF-8 con el formato %XY%ZA...

      4. Codifique con el signo de porcentaje el carácter de espacio como %20 y no como + (lo que se hace en las codificaciones comunes).

   3. Separe los nombres de los parámetros codificados de sus valores codificados con el signo igual (=) (carácter ASCII 61), aunque el valor del parámetro esté vacío.

   4. Separe los pares de nombre-valor con el carácter ampersand (&) (código ASCII 38).

2. Cree la cadena para firmar según la siguiente pseudogramática ("\n" representa un carácter de nueva línea ASCII).

   StringToSign = HTTPVerb + "\n" +
   ValueOfHostHeaderInLowercase + "\n" +
   HTTPRequestURI + "\n" +
   CanonicalizedQueryString <from the preceding step>
                           

   El componente HTTPRequestURI es el componente de la ruta absoluta HTTP del URI hasta la cadena de consulta, pero sin incluirla. Si HTTPRequestURI está vacío, utilice una barra diagonal (/).

3. Calcule una HMAC conforme con RFC 2104 con la cadena que acaba de crear, su clave de acceso secreta como la clave y SHA256 o SHA1 como algoritmo de hash.

   Para obtener más información, consulte https://www.ietf.org/rfc/rfc2104.txt.

4. Convierta el valor resultante en base 64.

5. Incluya el valor como valor del parámetro Signature de la solicitud.

A continuación se muestra una solicitud de muestra (se han agregado saltos de línea para facilitar la lectura).

https://elasticache.us-west-2.amazonaws.com/
    ?Action=DescribeCacheClusters
    &CacheClusterIdentifier=myCacheCluster
    &SignatureMethod=HmacSHA256
    &SignatureVersion=4
    &Version=2014-12-01
 

Para la cadena de consulta anterior, debería calcular la firma HMAC de la siguiente cadena.

GET\n
    elasticache.amazonaws.com\n
    Action=DescribeCacheClusters
    &CacheClusterIdentifier=myCacheCluster
    &SignatureMethod=HmacSHA256
    &SignatureVersion=4
    &Version=2014-12-01
    &X-Amz-Algorithm=&AWS;4-HMAC-SHA256
    &X-Amz-Credential=AKIADQKE4SARGYLE%2F20140523%2Fus-west-2%2Felasticache%2Faws4_request
    &X-Amz-Date=20141201T223649Z
    &X-Amz-SignedHeaders=content-type%3Bhost%3Buser-agent%3Bx-amz-content-sha256%3Bx-amz-date
        content-type:
        host:elasticache.us-west-2.amazonaws.com
        user-agent:CacheServicesAPICommand_Client
    x-amz-content-sha256:
    x-amz-date:

El resultado es la siguiente solicitud firmada.

https://elasticache.us-west-2.amazonaws.com/
    ?Action=DescribeCacheClusters
    &CacheClusterIdentifier=myCacheCluster
    &SignatureMethod=HmacSHA256
    &SignatureVersion=4
    &Version=2014-12-01
    &X-Amz-Algorithm=&AWS;4-HMAC-SHA256
    &X-Amz-Credential=AKIADQKE4SARGYLE/20141201/us-west-2/elasticache/aws4_request
    &X-Amz-Date=20141201T223649Z
    &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date
    &X-Amz-Signature=2877960fced9040b41b4feaca835fd5cfeb9264f768e6a0236c9143f915ffa56
 

Para obtener información detallada acerca del proceso de firma y el cálculo de la firma de la solicitud, consulte el tema Proceso de firma Signature Version 4 y sus subtemas.