Uso dell'API query

Parametri di query

Le richieste basate su query HTTP sono richieste HTTP che utilizzano i verbi HTTP GET oppure POST e un parametro di query denominato Action.

Ogni richiesta di query deve includere alcuni parametri comuni per gestire l'autenticazione e la selezione di un'azione.

Alcune operazioni accettano elenchi di parametri. Questi elenchi sono specificati usando l'annotazione param.n. I valori di n sono numero a partire da 1.

Autenticazione delle richieste di query

È possibile inviare richieste di query solo tramite HTTPS ed è necessario includere una firma in ogni richiesta di query. Questa sezione descrive come creare la firma. Il metodo descritto nella seguente procedura è noto come Signature Version 4.

Di seguito sono riportate le fasi di base utilizzate per l'autenticazione delle richieste in AWS. Si presuppone che abbia eseguito la registrazione in AWS e disponga di un ID chiave di accesso e di una chiave di accesso segreta.

Processo di autenticazione delle query

1. Il mittente crea una richiesta in AWS.

2. Il mittente calcola la firma della richiesta, un hash con chiave per il codice di autenticazione di messaggi basati su hash (HMAC) con una funzione hash SHA-1, come definito nella successiva sezione di questo argomento.

3. Il mittente della richiesta invia ad AWS i dati della richiesta, la firma e l'ID chiave di accesso, ovvero l'identificatore per la chiave di accesso segreta in uso.

4. AWS utilizza l'ID chiave di accesso per cercare la chiave di accesso segreta.

5. AWS genera una firma a partire dai dati della richiesta e dalla chiave di accesso segreta utilizzando lo stesso algoritmo con cui viene calcolata la firma nella richiesta.

6. Se le firme corrispondono, la richiesta viene considerata autentica. Se il confronto non va a buon fine, la richiesta viene scartata e AWS invia una risposta di errore.

Nota

Se una richiesta contiene un parametro Timestamp, la firma calcolata per la richiesta scade 15 minuti dopo il relativo valore.

Se una richiesta contiene un parametro Expires, la firma scade in corrispondenza dell'ora specificata dal parametro Expires.

Per calcolare la firma della richiesta

1. Creare la stringa di query in forma canonica necessaria successivamente durante questa procedura:

   1. Ordinare i componenti della stringa di query UTF-8 per nome di parametro in base a un ordine naturale dei byte. I parametri possono avere fonte da GET URI o dal corpo POST (quando Content-Type è application/x-www-form-urlencoded).

   2. Codificare in formato URL il nome e i valori di parametro in base alle seguenti regole:

      1. Non codificare in formato URL i caratteri non riservati definiti da RFC 3986. I caratteri non riservati sono A-Z, a-z, 0-9, trattino (-), trattino basso (_), punto (.) e tilde (~).

      2. Codificare con codifica percentuale tutti gli altri caratteri con %XY, dove X e Y sono caratteri esadecimali (0-9 e A-F maiuscole).

      3. Codificare con codifica percentuale i caratteri UTF-8 estesi nel formato %XY%ZA....

      4. Codificare con codifica percentuale il carattere di spazio come %20 (non utilizzare +, come negli schemi di codifica comuni).

   3. Separare i nomi di parametro codificati dai rispettivi valori codificati con il segno di uguale (=), ovvero il carattere ASCII 61, anche se il valore del parametro è vuoto.

   4. Separare le coppie nome-valore con una E commerciale (&), codice ASCII 38.

2. Creare la stringa di firma in base al seguente esempio di grammatica ("\n" rappresenta una nuova riga ASCII).

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

   Il componente HTTPRequestURI è il componente del percorso assoluto HTTP dell'URI fino alla stringa di query (senza includerla). Se HTTPRequestURI è vuoto, utilizzare una barra (/).

3. Calcolare una firma HMAC compatibile con RFC 2104 utilizzando la stringa appena creata, la chiave di accesso segreta come chiave e SHA256 o SHA1 come algoritmo hash.

   Per ulteriori informazioni, consulta https://www.ietf.org/rfc/rfc2104.txt.

4. Convertire il valore risultante in base64.

5. Includere il valore come valore del parametro Signature nella richiesta.

Di seguito è riportata una richiesta di esempio (le interruzioni di riga sono aggiunte per chiarezza).

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

Per la stringa di query precedente, è necessario calcolare la firma HMAC sulla seguente stringa.

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:

Il risultato è la richiesta firmata seguente.

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
 

Per informazioni dettagliate sul processo di firma e sul calcolo della firma della richiesta, consulta l'argomento Processo di firma Signature Version 4 e i relativi argomenti secondari.