Invio di richieste batch

Questo documento mostra come raggruppare le chiamate API JSON per ridurre il numero di connessioni HTTP che il client deve effettuare quando accede a Cloud Storage.

Panoramica

Ogni connessione HTTP realizzata dal client determina un determinato sovraccarico. L'API JSON di Cloud Storage supporta il batch, per consentire al tuo client di inserire diverse chiamate API in una singola richiesta HTTP.

Esempi di situazioni in cui potresti voler utilizzare la creazione in batch:

  • Aggiornare i metadati, ad esempio le autorizzazioni, su molti oggetti.
  • Eliminazione di molti oggetti.

In ogni caso, invece di inviare ogni chiamata separatamente, puoi raggrupparle in un'unica richiesta HTTP. Tutte le richieste interne devono andare all'API JSON Cloud Storage.

Non devi includere più di 100 chiamate in una singola richiesta batch. Se devi effettuare più chiamate, utilizza più richieste batch. Il payload totale della richiesta batch deve essere inferiore a 10 MB.

Dettagli 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 dettagliatamente la sintassi batch; più avanti troverai 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 tipo di contenuti multipart/mixed. All'interno della richiesta HTTP principale sono presenti più parti, ognuna contiene 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 segnalano l'inizio della parte, ma sono separate dalla richiesta HTTP nidificata. Ciò significa che, dopo che il server ha annullato il wrapping della 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 specifici. Queste richieste HTTP devono contenere solo la parte del percorso dell'URL; gli URL completi possono avere un comportamento indefinito.

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 che in una richiesta nidificata, il valore dell'intestazione della richiesta nidificata sostituisce il valore dell'intestazione della richiesta batch esterna per quella specifica richiesta.

Ad esempio, se fornisci un'intestazione Authorization per una specifica richiesta nidificata, l'intestazione si applica solo alla richiesta che l'ha specificata. Se fornisci un'intestazione Authorization per la richiesta esterna, questa verrà applicata a tutte le richieste nidificate, a meno che non la sostituiscano con un'intestazione Authorization propria.

Quando Cloud Storage riceve la richiesta in batch, applica i parametri di query e le intestazioni della richiesta esterna (a seconda dei casi) a ogni parte, 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 contenuto multipart/mixed; ogni parte di questa risposta principale è la risposta a una delle richieste della richiesta in batch. L'ordine delle risposte è lo stesso delle richieste.

Come tutte le parti in una richiesta, ogni parte della risposta contiene una risposta HTTP completa, inclusi un codice di stato, intestazioni e un corpo. E, come le parti nella richiesta, ogni parte della risposta è preceduta da un'intestazione Content-Type che contrassegna l'inizio. Per maggiori informazioni sui codici di stato, consulta Stato HTTP e codici di errore per l'API JSON di Cloud Storage.

Se una determinata parte della richiesta aveva un'intestazione Content-ID, la parte corrispondente della risposta avrà un'intestazione Content-ID corrispondente. L'intestazione Content-ID della risposta inizia con response-, seguito dal valore Content-ID utilizzato nella richiesta, come mostrato nell'esempio.

Esempio

Il seguente esempio batch aggiorna i metadati personalizzati per tre oggetti in example-bucket.

Esempio di richiesta HTTP batch

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 in batch.

C#

La libreria client C# non supporta le richieste in batch.

Go

La libreria client Go non supporta le richieste in batch.

Java

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Cloud Storage.

import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageBatch;
import com.google.cloud.storage.StorageOptions;
import java.util.HashMap;
import java.util.Map;

public class BatchSetObjectMetadata {
  public static void batchSetObjectMetadata(
      String projectId, String bucketName, String directoryPrefix) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The directory prefix. All objects in the bucket with this prefix will have their metadata
    // updated
    // String directoryPrefix = "yourDirectory/";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Map<String, String> newMetadata = new HashMap<>();
    newMetadata.put("keyToAddOrUpdate", "value");
    Page<Blob> blobs =
        storage.list(
            bucketName,
            Storage.BlobListOption.prefix(directoryPrefix),
            Storage.BlobListOption.currentDirectory());
    StorageBatch batchRequest = storage.batch();

    // Add all blobs with the given prefix to the batch request
    for (Blob blob : blobs.iterateAll()) {
      batchRequest.update(blob.toBuilder().setMetadata(newMetadata).build());
    }

    // Execute the batch request
    batchRequest.submit();

    System.out.println(
        "All blobs in bucket "
            + bucketName
            + " with prefix '"
            + directoryPrefix
            + "' had their metadata updated.");
  }
}

Node.js

La libreria client Node.js non supporta le richieste in batch.

PHP

La libreria client PHP non supporta le richieste in batch.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Cloud Storage.


from google.cloud import storage

def batch_request(bucket_name, prefix=None):
    """
    Use a batch request to patch a list of objects with the given prefix in a bucket.

    Note that Cloud Storage does not support batch operations for uploading or downloading.
    Additionally, the current batch design does not support library methods whose return values
    depend on the response payload.
    See https://cloud.google.com/python/docs/reference/storage/latest/google.cloud.storage.batch
    """
    # The ID of your GCS bucket
    # bucket_name = "my-bucket"
    # The prefix of the object paths
    # prefix = "directory-prefix/"

    client = storage.Client()
    bucket = client.bucket(bucket_name)

    # Accumulate in a list the objects with a given prefix.
    blobs_to_patch = [blob for blob in bucket.list_blobs(prefix=prefix)]

    # Use a batch context manager to edit metadata in the list of blobs.
    # The batch request is sent out when the context manager closes.
    # No more than 100 calls should be included in a single batch request.
    with client.batch():
        for blob in blobs_to_patch:
            metadata = {"your-metadata-key": "your-metadata-value"}
            blob.metadata = metadata
            blob.patch()

    print(
        f"Batch request edited metadata for all objects with the given prefix in {bucket.name}."
    )

Ruby

Per informazioni su 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 richieste secondarie, 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 viene restituita con 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 è andata a buon fine o meno.