Batchanfragen senden

In diesem Dokument erfahren Sie, wie Sie JSON API-Aufrufe in einem Batch zusammenfassen, um die Anzahl der vom Client beim Zugriff auf Cloud Storage aufzubauenden HTTP-Verbindungen zu reduzieren.

Übersicht

Jede HTTP-Verbindung, die der Client erstellt, führt zu einem bestimmten Overhead. Die Cloud Storage JSON API unterstützt Batchanfragen. Entsprechend kann Ihr Client damit mehrere API-Aufrufe in einer einzelnen HTTP-Anfrage zusammenfassen.

Fallbeispiele für den Einsatz von Batchanfragen:

• Metadaten wie Berechtigungen für viele Objekte aktualisieren.
• Viele Objekte löschen.

In jedem Fall können Sie, anstatt jeden Aufruf einzeln zu senden, mehrere Aufrufe in einer einzigen HTTP-Anfrage zusammenfassen. Alle internen Anfragen müssen an dieselbe Cloud Storage JSON API gesendet werden.

Sie sollten nie mehr als 100 Aufrufe in eine einzelne Batchanfrage einbeziehen. Falls Sie eine größere Anzahl an Aufrufen benötigen, verwenden Sie mehrere Batchanfragen. Die gesamte Anfragebatch muss kleiner als 10 MiB sein.

Batchdetails

Eine Batchanfrage besteht aus mehreren in einer HTTP-Anfrage zusammengefassten API-Aufrufen. Sie kann an den Batchendpunkt von Cloud Storage gesendet werden, nämlich https://storage.googleapis.com/batch/storage/v1. In diesem Abschnitt wird die Batchsyntax im Detail beschrieben. Anschließend finden Sie ein Beispiel.

Format einer Batchanfrage

Eine Batchanfrage ist eine einzelne Standard-HTTP-Anfrage, die mehrere Cloud Storage JSON API-Aufrufe enthält. Diese Hauptanfrage verwendet den Inhaltstyp multipart/mixed. Die Haupt-HTTP-Anfrage besteht aus mehreren Teilen, die jeweils eine verschachtelte HTTP-Anfrage enthalten.

Jeder Teil beginnt mit seinem eigenen HTTP-Header Content-Type: application/http. Der Teil kann auch einen optionalen Content-ID-Header haben. Diese Header markieren den Anfang des Teils, sind aber von der verschachtelten HTTP-Anfrage getrennt. Das bedeutet nachdem der Server die Batchanfrage in separate Anfragen aufgeteilt hat, werden die Header der einzelnen Teile ignoriert.

Der Text jedes Teils ist an sich eine vollständige HTTP-Anfrage mit eigenem Verb, eigener URL, eigenen Headern und eigenem Text. Diese HTTP-Anfragen dürfen nur den Pfadteil der URL enthalten. Vollständige URLs können ein nicht definiertes Verhalten haben.

Die HTTP-Header für die äußere Batchanfrage gelten auch für alle verschachtelten Anfragen, nur nicht für Content--Header wie Content-Type. Wenn Sie jedoch einen bestimmten HTTP-Header sowohl in der äußeren als auch in einer verschachtelten Anfrage angeben, überschreibt der Headerwert der verschachtelten Anfrage den Wert des Headers der äußeren Batchanfrage für diese bestimmte Anfrage.

Beispiel: Wenn Sie einen Authorization-Header für eine bestimmte verschachtelte Anfrage angeben, gilt dieser Header nur für die Anfrage, die ihn angegeben hat. Wenn Sie einen Authorization-Header für die äußere Anfrage angeben, gilt dieser Header für alle verschachtelten Anfragen, es sei denn, diese überschreiben ihn mit einem eigenen Authorization-Header.

Wenn Cloud Storage die im Batch verpackte Anfrage empfängt, wendet es (nach Bedarf) die Abfrageparameter und Header der äußeren Anfrage auf jeden Teil an, und behandelt jeden dieser Teile dann so, als wäre er eine separate HTTP-Anfrage.

Antwort auf eine Batchanfrage

Die Cloud Storage-Antwort ist eine einzelne Standard-HTTP-Antwort mit einem multipart/mixed-Inhaltstyp. Jeder Teil dieser Hauptantwort ist die Antwort auf eine der Anfragen in der Batchanfrage. Die Reihenfolge der Antworten entspricht der Reihenfolge der Anfragen.

Wie alle Teile in einer Anfrage enthält jeder Antwortteil eine vollständige HTTP-Antwort, einschließlich Statuscode, Headern und Text. Wie auch bei den Teilen in der Anfrage ist jedem Antwortteil ein Content-Type-Header vorangestellt, der den Beginn des Teils markiert. Weitere Informationen zu Statuscodes finden Sie unter HTTP-Status- und -Fehlercodes für die Cloud Storage JSON API.

Wenn ein bestimmter Teil einer Anfrage einen Content-ID-Header enthält, enthält der entsprechende Teil der Antwort einen entsprechenden Content-ID-Header. Der Content-ID-Header der Antwort beginnt mit response-, gefolgt vom in der Anfrage verwendeten Content-ID-Wert, wie im Beispiel gezeigt.

Beispiel

In folgendem Batchbeispiel werden benutzerdefinierte Metadaten für drei Objekte in example-bucket aktualisiert.

Beispiel für eine HTTP-Batchanfrage

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==--

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.");
  }
}

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}."
    )

Beispiel für eine Batch-HTTP-Antwort

Dies ist die Antwort auf die HTTP-Beispielanfrage im vorherigen Abschnitt.

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=--

Wenn die Gesamtanfrage nicht richtig formatiert ist und Cloud Storage sie nicht in Teilanfragen parsen kann, erhalten Sie den Fehler 400. Andernfalls gibt Cloud Storage den Statuscode 200 zurück, auch wenn einige oder alle Unteranfragen fehlschlagen.

Wenn die Gesamtanfrage mit dem Statuscode 200 zurückgegeben wird, enthält die Antwort Ergebnisse für jede Unteranfrage, einschließlich eines Statuscodes für jede davon, der angibt, ob die Unteranfrage erfolgreich war oder fehlgeschlagen ist. Wenn Sie beispielsweise Objekte im Batch löschen, enthält jede erfolgreiche Unteranfrage den Statuscode 204 No Content.