Batchanfragen

Wie im www.googleapis.com/batch angekündigt, funktionieren globale HTTP-Batchendpunkte (www.googleapis.com/batch) ab dem 25. März 2019 nicht mehr. Die Anleitung im Blogpost zeigt, wie Sie stattdessen homogene Batchanfragen an die entsprechenden API-Endpunkte (www.googleapis.com/batch/api/version) senden.

In diesem Dokument erfahren Sie, wie API-Aufrufe in einem Batch zusammengefasst werden, um die Anzahl von HTTP-Verbindungen für den Client zu reduzieren.

In diesem Dokument wird ausschließlich das Erstellen einer Batchanfrage durch Senden einer HTTP-Anfrage behandelt. Wenn Sie stattdessen eine Google-Clientbibliothek für die Batchanfrage verwenden, finden Sie Informationen dazu in der Dokumentation der Clientbibliothek.

Übersicht

Jede HTTP-Verbindung, die Ihr Client herstellt, ist mit einem gewissen Overhead verbunden. Die Google Compute Engine API unterstützt Stapelanfragen, damit der Client mehrere API-Aufrufe in einer einzelnen HTTP-Anfrage zusammenfassen kann.

Fallbeispiele für den Einsatz von Stapelanfragen:

  • Sie haben gerade mit der Verwendung der API begonnen und müssen viele Daten hochladen.
  • Ein Nutzer hat Änderungen an Daten vorgenommen, während Ihre Anwendung offline (nicht mit dem Internet verbunden) war, sodass Ihre Anwendung die lokalen Daten mit dem Server synchronisieren und dazu viele Aktualisierungs- und Löschvorgänge senden muss.

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

Jeder Batch-Request ist auf maximal 1.000 Aufrufe begrenzt. Falls Sie eine höhere Anzahl an Aufrufen tätigen müssen, erstellen Sie mehrere Batch-Requests.

Hinweis: Das Batchsystem der Google Compute Engine API verwendet dieselbe Syntax wie das Batchverarbeitungssystem von OData, aber mit einer anderen Semantik.

Batchdetails

Eine Batchanfrage besteht aus mehreren, in einer HTTP-Anfrage zusammengefassten API-Aufrufen. Sie kann an den im batchPath angegebenen batchPath gesendet werden. Der Standardpfad ist /batch/api_name/api_version. In diesem Abschnitt wird die Batchsyntax im Detail beschrieben. Anschließend finden Sie ein Beispiel.

Hinweis: Wenn n Anfragen zu einem Batch zusammengefasst sind, werden auch n Anfragen auf Ihr Nutzungskontingent angerechnet, nicht nur eine einzige Anfrage. Die Batchanfrage wird vor der Verarbeitung in eine Reihe von Anfragen aufgeteilt.

Format einer Stapelanfrage

Eine Stapelanfrage ist eine einzige Standard-HTTP-Anfrage mit mehreren Google Compute Engine API-Aufrufen, die dem Inhaltstyp multipart/mixed entspricht. Jeder Teil dieser HTTP-Hauptanfrage enthält eine verschachtelte HTTP-Anfrage.

Jeder Teil beginnt mit seinem eigenen HTTP-Header Content-Type: application/http. Er kann auch über einen optionalen Content-ID-Header verfügen. Die Teile-Header sollen jedoch nur den Anfang des Teils markieren; sie sind von der verschachtelten Anfrage getrennt. Nachdem der Server die Stapelanfrage in separate Anfragen aufgeteilt hat, werden die Teile-Header ignoriert.

Der Text jedes Teils ist an sich eine vollständige HTTP-Anfrage mit eigenem Verb, eigener URL, eigenen Headern und eigenem Text. Die HTTP-Anfrage darf nur den Pfadteil der URL enthalten; vollständige URLs sind in Stapelanfragen nicht zulässig.

Die HTTP-Header für die äußere Stapelanfrage gelten für jede Anfrage in dem Stapel, ausgenommen Content--Header wie Content-Type. Wenn Sie einen bestimmten HTTP-Header sowohl in der äußeren Anfrage als auch in einem individuellen Aufruf verwenden, überschreibt der Wert des individuellen Aufrufheaders den Wert des Headers der äußeren Stapelanfrage. Die Header für einen individuellen Aufruf gelten nur für diesen Aufruf.

Beispiel: Wenn Sie einen Autorisierungsheader für einen bestimmten Aufruf angeben, gilt dieser Header nur für diesen Aufruf. Wenn Sie einen Autorisierungsheader für die äußere Anfrage angeben, gilt dieser Header für alle einzelnen Aufrufe, es sei denn, diese überschreiben ihn mit eigenen Autorisierungsheadern.

Wenn der Server die Stapelanfrage empfängt, wendet er (nach Bedarf) die Abfrageparameter und Header der äußeren Anfrage für jeden Teil an, und behandelt jeden Teil dann so, als wäre er eine separate HTTP-Anfrage.

Antwort auf eine Stapelanfrage

Die Antwort des Servers ist eine einzelne Standard-HTTP-Antwort mit einem Inhaltstyp multipart/mixed; jeder Teil ist die Antwort auf eine der Anfragen in der Stapelanfrage in derselben Reihenfolge wie die einzelnen Anfragen.

Wie die Teile in der 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.

Wenn ein bestimmter Teil einer Anfrage einen Content-ID-Header enthielt, enthält der entsprechende Teil der Antwort einen übereinstimmenden Content-ID-Header, wobei dem ursprünglichen Wert der String response- vorangestellt ist, wie im folgenden Beispiel dargestellt.

Hinweis: Der Server kann die Aufrufe in beliebiger Reihenfolge ausführen. Die Aufrufe werden nicht unbedingt in der Reihenfolge ausgeführt, in der Sie sie angegeben haben. Wenn Sie sicherstellen möchten, dass zwei Aufrufe in einer bestimmten Reihenfolge ausgeführt werden, können Sie sie nicht in einer einzelnen Anfrage senden. Senden Sie stattdessen den ersten Aufruf für sich alleine und warten Sie auf die Antwort auf den ersten Aufruf, bevor Sie den zweiten Aufruf senden.

Beispiel

Im nachfolgenden Beispiel wird gezeigt, wie Stapelanfragen mittels einer generischen (fiktionalen) Demo-API, auch Farm-API genannt, durchgeführt werden können. Die gleichen Konzepte sind jedoch auch auf die Google Compute Engine-API anwendbar.

Beispiel für eine Stapelanfrage

POST /batch/farm/v1 HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item1:12930812@barnyard.example.com>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:12930812@barnyard.example.com>

PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"

{
  "animalName": "sheep",
  "animalAge": "5"
  "peltColor": "green",
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item3:12930812@barnyard.example.com>

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

Beispiel für eine Stapelantwort

Dies ist die Antwort auf die Beispielanfrage im vorherigen Abschnitt.

HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:12930812@barnyard.example.com>

HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"

{
  "kind": "farm#animal",
  "etag": "etag/pony",
  "selfLink": "/farm/v1/animals/pony",
  "animalName": "pony",
  "animalAge": 34,
  "peltColor": "white"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:12930812@barnyard.example.com>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"

{
  "kind": "farm#animal",
  "etag": "etag/sheep",
  "selfLink": "/farm/v1/animals/sheep",
  "animalName": "sheep",
  "animalAge": 5,
  "peltColor": "green"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:12930812@barnyard.example.com>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--
Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...

Compute Engine-Dokumentation