Questo documento mostra come raggruppare le chiamate all'API JSON per ridurre il numero di connessioni HTTP che il client deve effettuare quando accede a Cloud Storage.
Panoramica
Ogni connessione HTTP stabilita dal client comporta un determinato ammontare di overhead. L'API JSON di Cloud Storage supporta il raggruppamento, per consentire al client di inserire più chiamate API in un'unica richiesta HTTP.
Esempi di situazioni in cui potresti voler utilizzare il raggruppamento:
- Aggiornamento dei metadati, ad esempio le autorizzazioni, su molti oggetti.
- Eliminazione di molti oggetti.
In ogni caso, anziché inviare ogni chiamata separatamente, puoi raggrupparle in una singola richiesta HTTP. Tutte le richieste interne devono essere inviate all'API JSON Cloud Storage.
Non devi includere più di 100 chiamate in una singola richiesta batch. Se hai bisogno di effettuare più chiamate, utilizza più richieste collettive. Il payload totale della richiesta di batch deve essere inferiore a 10 MB.
Dettagli del batch
Una richiesta batch è composta da più chiamate API combinate in un'unica richiesta HTTP, che può essere inviata all'endpoint batch di Cloud Storage, ovvero https://storage.googleapis.com/batch/storage/v1
. Questa sezione descrive la sintassi del batch in dettaglio. Di seguito è riportato un esempio.
Formato di una richiesta batch
Una richiesta batch è una singola richiesta HTTP standard contenente più chiamate API JSON di Cloud Storage. Questa richiesta principale utilizza il multipart/mixed
tipo di contenuto. All'interno della richiesta HTTP principale sono presenti più parti, ciascuna contenente una richiesta HTTP nidificata.
Ogni parte inizia con la propria intestazione HTTP Content-Type: application/http
.
La parte può anche avere un'intestazione Content-ID
facoltativa. Queste intestazioni contrassegnano l'inizio della parte, ma sono separate dalla richiesta HTTP nidificata. Ciò significa che, dopo che il server ha scompattato la richiesta batch in richieste separate, le intestazioni delle parti vengono ignorate.
Il corpo di ogni parte è una richiesta HTTP completa, con verbo, URL, intestazioni e corpo. Queste richieste HTTP devono contenere solo la parte del percorso dell'URL. Gli URL completi possono avere un comportamento non definito.
Le intestazioni HTTP per la richiesta batch esterna, ad eccezione delle intestazioni Content-
come Content-Type
, si applicano anche a ogni richiesta nidificata. Tuttavia, se specifichi una determinata intestazione HTTP sia nella richiesta esterna sia in una richiesta nidificata, il valore dell'intestazione della richiesta nidificata sostituisce il valore dell'intestazione della richiesta batch esterna per quella richiesta specifica.
Ad esempio, se fornisci un'intestazione Authorization
per una richiesta nidificata specifica, questa intestazione si applica solo alla richiesta che la specifica. Se fornisci un'intestazione Authorization
per la richiesta esterna, questa intestazione si applica a tutte le richieste nidificate, a meno che non vengano sostituite con un'intestazione Authorization
propria.
Quando Cloud Storage riceve la richiesta raggruppata, applica i parametri di ricerca e le intestazioni della richiesta esterna (se appropriato) a ogni parte e poi tratta ogni parte come se fosse una richiesta HTTP separata.
Risposta a una richiesta batch
La risposta di Cloud Storage è una singola risposta HTTP standard con un tipo di contenuti multipart/mixed
. Ogni parte di questa risposta principale è la risposta a una delle richieste nella richiesta raggruppata. L'ordine delle risposte è lo stesso delle richieste.
Come tutte le parti di una richiesta, ogni parte della risposta contiene una risposta HTTP completa, inclusi un codice di stato, le intestazioni e un corpo. Come le parti della richiesta, ogni parte della risposta è preceduta da un'intestazione Content-Type
che ne indica l'inizio. Per saperne di più sui codici di stato, consulta
Codici di stato e di errore HTTP per l'API JSON di Cloud Storage.
Se una determinata parte della richiesta aveva un'intestazione Content-ID
, la parte corrispondente della risposta ha un'intestazione Content-ID
corrispondente. L'intestazione Content-ID
della risposta inizia con response-
, seguita dal valore Content-ID
utilizzato nella richiesta, come mostrato nell'esempio.
Esempio
L'esempio batch seguente aggiorna i metadati personalizzati di tre oggetti
in example-bucket
.
Richiesta HTTP batch di esempio
HTTP
POST /batch/storage/v1 HTTP/1.1 Host: storage.googleapis.com Content-Length: 960 Content-Type: multipart/mixed; boundary="===============7330845974216740156==" Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg --===============7330845974216740156== Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+1> PATCH /storage/v1/b/example-bucket/o/obj1 HTTP/1.1 Content-Type: application/json accept: application/json content-length: 31 {"metadata": {"type": "tabby"}} --===============7330845974216740156== Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+2> PATCH /storage/v1/b/example-bucket/o/obj2 HTTP/1.1 Content-Type: application/json accept: application/json content-length: 32 {"metadata": {"type": "tuxedo"}} --===============7330845974216740156== Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+3> PATCH /storage/v1/b/example-bucket/o/obj3 HTTP/1.1 Content-Type: application/json accept: application/json content-length: 32 {"metadata": {"type": "calico"}} --===============7330845974216740156==--
Librerie client
C++
La libreria client C++ non supporta le richieste collettive.
C#
La libreria client C# non supporta le richieste collettive.
Vai
La libreria client Go non supporta le richieste collettive.
Java
Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Cloud Storage.
Node.js
La libreria client Node.js non supporta le richieste collettive.
PHP
La libreria client PHP non supporta le richieste collettive.
Python
Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Cloud Storage.
Ruby
Per scoprire come effettuare una richiesta batch utilizzando Ruby, consulta la documentazione di riferimento dell'API Ruby Cloud Storage.
Esempio di risposta HTTP batch
Questa è la risposta alla richiesta HTTP di esempio nella sezione precedente.
HTTP/1.1 200 OK Content-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q= Date: Mon, 22 Jan 2018 18:56:00 GMT Expires: Mon, 22 Jan 2018 18:56:00 GMT Cache-Control: private, max-age=0 Content-Length: 3767 --batch_pK7JBAk73-E=_AA5eFwv4m2Q= Content-Type: application/http Content-ID: <response-b29c5de2-0db4-490b-b421-6a51b598bd22+1> HTTP/1.1 200 OK ETag: "lGaP-E0memYDumK16YuUDM_6Gf0/V43j6azD55CPRGb9b6uytDYl61Y" Content-Type: application/json; charset=UTF-8 Date: Mon, 22 Jan 2018 18:56:00 GMT Expires: Mon, 22 Jan 2018 18:56:00 GMT Cache-Control: private, max-age=0 Content-Length: 846 { "kind": "storage#object", "id": "example-bucket/obj1/1495822576643790", . . . "metadata": { "type": "tabby" }, . . . } --batch_pK7JBAk73-E=_AA5eFwv4m2Q= Content-Type: application/http Content-ID: <response-b29c5de2-0db4-490b-b421-6a51b598bd22+2> HTTP/1.1 200 OK ETag: "lGaP-E0memYDumK16YuUDM_6Gf0/91POdd-sxSAkJnS8Dm7wMxBSDKk" Content-Type: application/json; charset=UTF-8 Date: Mon, 22 Jan 2018 18:56:00 GMT Expires: Mon, 22 Jan 2018 18:56:00 GMT Cache-Control: private, max-age=0 Content-Length: 846 { "kind": "storage#object", "id": "example-bucket/obj2/1495822576643790", . . . "metadata": { "type": "tuxedo" }, . . . } --batch_pK7JBAk73-E=_AA5eFwv4m2Q= Content-Type: application/http Content-ID: <response-b29c5de2-0db4-490b-b421-6a51b598bd22+3> HTTP/1.1 200 OK ETag: "lGaP-E0memYDumK16YuUDM_6Gf0/d2Z1F1_ZVbB1dC0YKM9rX5VAgIQ" Content-Type: application/json; charset=UTF-8 Date: Mon, 22 Jan 2018 18:56:00 GMT Expires: Mon, 22 Jan 2018 18:56:00 GMT Cache-Control: private, max-age=0 Content-Length: 846 { "kind": "storage#object", "id": "example-bucket/obj3/1495822576643790", . . . "metadata": { "type": "calico" }, . . . } --batch_pK7JBAk73-E=_AA5eFwv4m2Q=--
Se la richiesta complessiva non è formattata correttamente e Cloud Storage non è in grado di analizzarla in sottorichieste, viene visualizzato un errore 400
. In caso contrario,
Cloud Storage restituisce un codice di stato 200
, anche se alcune o tutte le
richieste secondarie non vanno a buon fine.
Quando la richiesta complessiva restituisce un codice di stato 200
, la risposta contiene i risultati per ogni richiesta secondaria, incluso un codice di stato per ciascuna, che indica se la richiesta secondaria è riuscita o meno. Ad esempio,
quando elimini oggetti in blocco, ogni richiesta secondaria riuscita contiene un
codice di stato 204 No Content
.