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.

Hinweis: Die Batchverarbeitung der Cloud Storage JSON API nutzt dieselbe Syntax wie die OData-Batchverarbeitung, jedoch mit einer anderen Semantik.

Hinweis: Cloud Storage unterstützt keine Batchvorgänge beim Hoch- oder Herunterladen.

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.

Hinweis: Eine Reihe von n-Anfragen, die zusammengefasst sind, gelten für Ihr Nutzungslimit und Ihre Vorgangskosten als n-Anfragen, nicht als einzelne Anfrage. Die Batchanfrage wird vor der Verarbeitung in eine Reihe von n-Anfragen aufgeteilt.

Format einer Batchanfrage

Eine Batchanfrage ist eine einzelne Standard-HTTP-Anfrage, die mehrere Cloud Storage JSON API-Aufrufe enthält. Für diese Hauptanfrage wird der Inhaltstyp multipart/mixed verwendet. Die HTTP-Hauptanfrage enthält mehrere Teile, 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.

Achtung :Der Server kann Ihre Anfragen in beliebiger Reihenfolge ausführen. Verlassen Sie sich nicht darauf, dass Anfragen in der von Ihnen angegebenen Reihenfolge ausgeführt werden. Wenn Sie sicherstellen möchten, dass zwei Aufrufe in einer bestimmten Reihenfolge ausgeführt werden, senden Sie den ersten Aufruf für sich alleine und warten Sie auf die Antwort auf den ersten Aufruf, bevor Sie den zweiten Aufruf senden.

Beispiel

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

Beispiel für eine HTTP-Batchanfrage

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

Clientbibliotheken

C++

Die C++-Clientbibliothek unterstützt keine Batchanfragen.

C#

Die C#-Clientbibliothek unterstützt keine Batchanfragen.

Go

Die Go-Clientbibliothek unterstützt keine Batchanfragen.

Java

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Java API.

import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageBatch;
import com.google.cloud.storage.StorageBatchResult;
import com.google.cloud.storage.StorageException;
import com.google.cloud.storage.StorageOptions;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.stream.Collectors;

public class BatchSetObjectMetadata {
  public static void batchSetObjectMetadata(
      String projectId, String bucketName, String pathPrefix) {
    // 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 pathPrefix = "yourPath/";

    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(pathPrefix),
            Storage.BlobListOption.delimiter("/"));
    StorageBatch batchRequest = storage.batch();

    // Add all blobs with the given prefix to the batch request
    List<StorageBatchResult<Blob>> batchResults =
        blobs
            .streamAll()
            .map(blob -> batchRequest.update(blob.toBuilder().setMetadata(newMetadata).build()))
            .collect(Collectors.toList());

    // Execute the batch request
    batchRequest.submit();
    List<StorageException> failures =
        batchResults.stream()
            .map(
                r -> {
                  try {
                    BlobInfo blob = r.get();
                    return null;
                  } catch (StorageException e) {
                    return e;
                  }
                })
            .filter(Objects::nonNull)
            .collect(Collectors.toList());

    System.out.println(
        (batchResults.size() - failures.size())
            + " blobs in bucket "
            + bucketName
            + " with prefix '"
            + pathPrefix
            + "' had their metadata updated successfully.");

    if (!failures.isEmpty()) {
      System.out.println("While processing, there were " + failures.size() + " failures");

      for (StorageException failure : failures) {
        failure.printStackTrace(System.out);
      }
    }
  }
}

Node.js

Die Node.js-Clientbibliothek unterstützt keine Batchanfragen.

PHP

Die PHP-Clientbibliothek unterstützt keine Batchanfragen.

Python

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Python API.

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

Informationen zum Erstellen einer Batchanfrage mit Ruby finden Sie in der Referenzdokumentation zur Cloud Storage Ruby API.

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 untergeordnete Anfragen 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.