Le richieste canoniche definiscono gli elementi di una richiesta che un utente deve includere durante l'invio di richieste V4 con autenticazione autenticata con firma, come URL firmati. in Cloud Storage.
Panoramica
Una richiesta canonica è una stringa che rappresenta una richiesta HTTP specifica di di archiviazione ideale in Cloud Storage. Utilizzi una richiesta canonica insieme a una richiesta ad esempio una chiave RSA, per creare una firma che venga poi inclusa nella richiesta effettiva come autenticazione.
Una richiesta canonica include informazioni quali il verbo HTTP e la stringa di query i parametri e le intestazioni che dovrebbero essere usati nella richiesta effettiva, nonché l'oggetto, il bucket o altra risorsa da richiedere.
Una richiesta canonica assicura che, quando Cloud Storage riceve richiesta, può calcolare la stessa firma che hai calcolato. Se le tue e la versione calcolata da Cloud Storage non corrispondono, la richiesta non va a buon fine.
Strutturazione
Le richieste canoniche hanno la seguente struttura, incluso l'utilizzo di a capo tra ogni elemento:
HTTP_VERB PATH_TO_RESOURCE CANONICAL_QUERY_STRING CANONICAL_HEADERS SIGNED_HEADERS PAYLOAD
Verbi HTTP
Le richieste firmate possono utilizzare i seguenti verbi HTTP, che devono essere specificati come della richiesta canonica:
DELETE
GET
HEAD
POST
1PUT
1 Gli URL firmati possono essere utilizzati solo per le richieste POST
che avviano una
caricamento ripristinabile. Per saperne di più, consulta Utilizzare URL firmati con caricamenti ripristinabili
informazioni.
Percorso della risorsa
Le richieste canoniche includono il percorso della risorsa a cui si applica la richiesta. Il percorso della risorsa è costituito da tutto ciò che segue il nome host, ma precede qualsiasi stringa di query.
Ad esempio, se l'URL di Cloud Storage è
https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg
,
il percorso della risorsa sarà /example-bucket/cat-pics/tabby.jpeg
.
Se usi un URL di Cloud Storage alternativo come
https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg
il percorso della risorsa sarà /cat-pics/tabby.jpeg
.
Per ulteriori endpoint URL che possono essere utilizzati con gli URL firmati, consulta Endpoint per richieste API XML.
Quando definisci il percorso della risorsa, devi eseguire la codifica a percentuale
seguenti caratteri riservati: ?=!#$&'()*+,:;@[]"
Qualsiasi altra codifica percentuale
utilizzata nell'URL deve essere inclusa anche nel percorso della risorsa.
Stringa di query canonica
Le richieste canoniche specificano ogni parametro della stringa di query che verrà successivamente
incluse in qualsiasi richiesta firmata che utilizzi la firma pertinente, con
eccezione del parametro della stringa di query X-Goog-Signature
o X-Amz-Signature
.
La stringa di query specificata nella richiesta canonica è denominata
stringa di query canonica
La stringa di query è tutto ciò che segue il punto interrogativo (?
) alla fine
del percorso della risorsa.
Ad esempio, se l'URL di Cloud Storage è
https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?generation=1360887697105000&userProject=my-project
,
la stringa di query sarà generation=1360887697105000&userProject=my-project
.
Al momento di creare la stringa di query canonica:
I parametri nella stringa di query devono essere ordinati per nome utilizzando un l'ordinamento grammaticale per valore in punti di codice.
Ogni parametro nella stringa di query deve essere separato da
&
.Se la stringa di query canonica è vuota, questa parte della query richiesta canonica è solo una nuova riga (
\n
).
Parametri stringa di query obbligatori
La maggior parte dei parametri delle stringhe di query viene aggiunta in base alle esigenze, ma i seguenti devono includere nella tua richiesta canonica quando intendi utilizzarla per effettuare una URL firmato:
X-Goog-Algorithm
: l'algoritmo che utilizzerai per firmare l'URL. Valori validi sonoGOOG4-RSA-SHA256
eGOOG4-HMAC-SHA256
.X-Goog-Credential
: le credenziali che userai per firmare l'URL. Credenziali composta da un autorizzato e da un ambito delle credenziali specificati nel formato:AUTHORIZER%2FCREDENTIAL_SCOPE
. La autorizzato può essere un nome account di servizio o un ID di accesso alla chiave HMAC.X-Goog-Date
: la data e l'ora in cui l'URL firmato diventa utilizzabile, nel Formato di base ISO 8601YYYYMMDD'T'HHMMSS'Z'
.X-Goog-Expires
: la durata dell'URL firmato, misurata in secondi daX-Goog-Date
. Il valore di scadenza più lungo è 604.800 secondi (7 giorni).X-Goog-SignedHeaders
: un elenco di nomi delle intestazioni separati da punto e virgola definita nella richiesta canonica. Sono anche note come intestazioni firmate.host
deve essere uno dei nomi delle intestazioni.
Questi parametri della stringa di query in seguito devono essere utilizzati nell'URL firmato
insieme al parametro della stringa di query X-Goog-Signature
, che contiene
la firma che autentica la richiesta.
Intestazioni canoniche
Le richieste canoniche includono qualsiasi intestazione che deve essere successivamente inclusa nella le richieste firmate che usano la firma pertinente. Tuttavia, le richieste firmate può includere intestazioni aggiuntive che non sono state specificate nella versione canonica tranne che per quanto indicato nelle intestazioni obbligatorie. Intestazioni specificate nella richiesta canonica sono chiamate intestazioni canoniche.
Le intestazioni canoniche possono includere intestazioni personalizzate nonché intestazioni delle estensioni
che iniziano con x-goog-
.
Quando specifichi le intestazioni canoniche, tieni presente quanto segue:
- Rendi tutti i nomi delle intestazioni in minuscolo.
- Ordina tutte le intestazioni per nome utilizzando un ordinamento lessicografico per punto di codice valore.
- Separa ogni intestazione con una nuova riga (
\n
). - Elimina i nomi delle intestazioni duplicati creandone solo un nome con un elenco di valori separati da virgole. Assicurati che non ci siano spazi vuoti tra e assicurati che l'ordine dell'elenco separato da virgole corrisponda ai valori in modo che le intestazioni vengano visualizzate nella richiesta. Per ulteriori informazioni, vedi RFC 7230 sezione 3.2.
- Sostituisci eventuali spazi vuoti pieghevoli o nuove righe (CRLF o LF) con un singolo spazio. Per ulteriori informazioni su come comprimere lo spazio vuoto, RFC 7230, sezione 3.2.4..
Rimuovi gli spazi vuoti intorno ai due punti visualizzati dopo il nome dell'intestazione.
Ad esempio, se utilizzi l'intestazione personalizzata
x-goog-acl: private
senza rimuoverla lo spazio dopo i due punti restituisce un errore403 Forbidden
, perché la richiesta di firma calcolata non corrisponde alla firma Cloud Storage esegue i calcoli.
Esempio
Se hai il seguente insieme di intestazioni:
host: storage.googleapis.com content-type: text/plain x-goog-meta-reviewer: jane x-goog-meta-reviewer: john
La struttura delle intestazioni canoniche nella richiesta canonica sarebbe:
content-type:text/plain host:storage.googleapis.com x-goog-meta-reviewer:jane,john
Intestazioni canoniche obbligatorie
La maggior parte delle intestazioni, ad esempio content-type
, viene aggiunta secondo necessità, ma quanto segue
e devono sempre essere definite nelle intestazioni canoniche, se intendi utilizzare
nella richiesta firmata:
host
: l'URI utilizzato per accedere a Cloud Storage.- Intestazioni con prefisso
x-goog-
. L'unica intestazione di questo tipo che è facoltativa includi come intestazione canonica èx-goog-content-sha256
. - Intestazioni con prefisso
x-amz-
. L'unica intestazione di questo tipo che è facoltativa includi come intestazione canonica èx-amz-content-sha256
.
Intestazioni firmate
Un'intestazione firmata è la parte relativa al nome di un'intestazione canonica.
Per creare l'elenco delle intestazioni firmate, converti tutti i nomi delle intestazioni in lettere minuscole, ordina
specificandoli in base al codice di carattere e utilizza un punto e virgola (;
) per separarli.
Esempio
Se hai il seguente insieme di intestazioni:
host: storage.googleapis.com content-type: text/plain x-goog-meta-reviewer: jane x-goog-meta-reviewer: john
La struttura delle intestazioni firmate nella richiesta canonica sarebbe:
content-type;host;x-goog-meta-reviewer
Payload
Se la tua richiesta canonica verrà utilizzata per creare un URL firmato, questo valore dovrebbe essere la stringa
UNSIGNED-PAYLOAD
.Se la tua richiesta canonica verrà utilizzata nell'ambito di una richiesta che utilizza un Intestazione
Authorization
:Utilizza
UNSIGNED-PAYLOAD
se vuoi consentire payload arbitrari come parte di la richiesta. Quando si avvia una richiesta di caricamento ripristinabile, viene ti consigliamo di utilizzareUNSIGNED-PAYLOAD
. Qualsiasi valore sha256 incluso viene ignorato per i caricamenti ripristinabili.Se vuoi consentire solo un payload specifico, questo valore deve essere un l'hash SHA-256 minuscolo e con codifica esadecimale del payload desiderato. Per richiedere un payload vuoto, utilizza una stringa vuota come input per la funzione hash. Un esempio di payload con hash (in questo caso un payload vuoto) è:
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Esempio
Di seguito è riportato un esempio di richiesta canonica formata correttamente, con
nuove righe mostrate come nuove righe e non \n
:
GET /example-bucket/tabby.jpeg host:storage.googleapis.com x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 x-amz-date:20190301T190859Z host;x-amz-content-sha256;x-amz-date e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Passaggi successivi
- Scopri di più sulle firme e su come utilizzano le richieste canoniche.
- Crea una richiesta che utilizza una richiesta canonica.
- Creare URL firmati, che utilizzano richieste canoniche.
- Scopri di più sugli URL firmati.