Uso dell'API query

Parametri di query

Query-based Le richieste HTTP sono richieste HTTP che utilizzano il verbo HTTP GET o POST e un parametro di Query denominatoAction.

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 numeri interi 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. Ciò presuppone che tu sia registrato 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 a. AWS

2. Il mittente calcola la firma della richiesta, un Keyed-Hashing per Hash-based Message Authentication Code (HMAC) con una funzione SHA-1 hash, come definito nella sezione successiva di questo argomento.

3. Il mittente della richiesta invia i dati della richiesta, la firma e l'ID della chiave di accesso (l'identificatore della chiave di accesso segreta utilizzata) a. AWS

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

5. AWS genera una firma dai dati della richiesta e dalla chiave di accesso segreta utilizzando lo stesso algoritmo utilizzato per calcolare 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. Ordina i componenti della stringa di UTF-8 query in base al nome del parametro con un ordinamento naturale dei byte. I parametri possono provenire dall'URI GET 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. Questi caratteri non riservati sono a-z, 0-9 A-Z, trattino (-), trattino basso (_), punto (.) e tilde (~).

      2. La percentuale codifica tutti gli altri caratteri con %XY, dove X e Y sono caratteri esadecimali da 0 a 9 e maiuscoli. A-F

      3. Codifica percentuale dei caratteri estesi nel formato %XY%ZA UTF-8 ...

      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.