Como usar a API de consulta

Parâmetros de consulta

As solicitações baseadas em consulta HTTP são solicitações HTTP que usam o verbo HTTP GET ou POST e um parâmetro de consulta chamado Action.

Cada solicitação de consulta deve incluir alguns parâmetros comuns para lidar com a autenticação e a seleção de uma ação.

Algumas operações levam listas de parâmetros. Essas listas são especificadas usando a notação param.n. Os valores de n são inteiros a partir de 1.

Autenticação de solicitação de consulta

Só é possível enviar solicitações de consulta por meio de HTTPS, e é preciso incluir uma assinatura em todas as solicitações de consulta. Esta seção descreve como criar a assinatura. O método descrito no procedimento a seguir é conhecido como versão de assinatura 4.

As etapas básicas a seguir são usadas para autenticar as solicitações à AWS. Isso presume que você esteja registrado na AWS e possua um ID de chave de acesso e uma chave de acesso secreta.

Processo de autenticação de consulta

1. O remetente elabora uma solicitação à AWS.

2. O remetente calcula a assinatura da solicitação, um hash codificado para o HMAC (Hash-based Message Authentication Code) com uma função de hash SHA-1, conforme definido na próxima seção deste tópico.

3. O remetente da solicitação envia os dados da solicitação, a assinatura e o ID da chave de acesso (o identificador da chave de acesso secreta usada) à AWS.

4. A AWS usa o ID de chave de acesso para pesquisar pela chave de acesso secreta.

5. A AWS gera uma assinatura a partir dos dados da solicitação e da chave de acesso secreta usando o mesmo algoritmo usado para calcular a assinatura enviada na solicitação.

6. Se as assinaturas coincidirem, a solicitação será considerada autêntica. Se a comparação falhar, a solicitação será descartada e a AWS retornará uma resposta de erro.

nota

Se uma solicitação contiver um parâmetro Timestamp, a assinatura calculada para a solicitação expirará 15 minutos após o valor.

Se uma solicitação contiver um parâmetro Expires, a assinatura expirará no horário especificado pelo parâmetro Expires.

Para calcular a assinatura da solicitação

1. Crie a query string canonizada de que você precisará posteriormente neste procedimento:

   1. Classifique os componentes query string UTF-8 por nome do parâmetro com o ordenamento natural de bytes. Os parâmetros podem vir do URI GET ou do corpo POST (quando Content-Type for application/x-www-form-urlencoded).

   2. Codificar em URL o nome do parâmetro e os valores de acordo com as seguintes regras:

      1. Não codificar em URL nenhum dos caracteres não reservados que definem o RFC 3986. Esses caracteres não reservados são A–Z, a–z, 0–9, hífen ( - ), sublinhado ( _ ), ponto ( . ) e til ( ~ ).

      2. Codificar em percentual todos os outros caracteres com %XY, onde X e Y são caracteres hexadecimais de 0 a 9 e maiúsculas de A a F.

      3. Codificar em percentual os caracteres UTF-8 estendidos na forma %XY%ZA...

      4. Codificar em percentual o caractere de espaço como %20 (e não +, como em esquemas de codificação comuns).

   3. Separe os nomes de parâmetro codificados a partir de seus valores codificados com o sinal de igual ( = ) (caractere ASCII 61), mesmo se o valor do parâmetro estiver vazio.

   4. Separe os pares de nome-valor por um "&" (e comercial) (código 38 em ASCII).

2. Crie a string para assinar de acordo com a seguinte pseudogramática ("\n" representa uma nova linha em ASCII).

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

   O componente HTTPRequestURI é o componente de caminho absoluto HTTP do URI até a query string (não incluída). Se o HTTPRequestURI estiver vazio, use uma barra ( / ).

3. Calcule um HMAC compatível com RFC 2104 com a string recém-criada, sua chave de acesso secreta como chave e SHA256 ou SHA1 como algoritmo de hash.

   Para obter mais informações, consulte https://www.ietf.org/rfc/rfc2104.txt.

4. Converta o valor resultante para base64.

5. Inclua o valor como o valor do parâmetro Signature na solicitação.

Por exemplo, a seguir você encontra um exemplo de solicitação (as quebras de linha foram adicionadas para maior clareza).

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

Quanto à string de consulta anterior, você calcularia a assinatura HMAC na seguinte string.

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:

O resultado é a seguinte solicitação assinada.

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 obter informações detalhadas sobre o processo de assinatura e o cálculo da assinatura da solicitação, consulte o tópico Processo de assinatura do Signature Version 4 e seus subtópicos.