Stapelanfragen

In diesem Dokument wird erklärt, wie Sie API-Aufrufe stapelweise verarbeiten können, um die Anzahl der HTTP-Verbindungen, die Ihr Client herstellen muss, zu reduzieren.

Insbesondere wird erläutert, wie Stapelanfragen mithilfe einer HTTP-Anfrage erstellt werden können. Wenn Sie stattdessen die Google-Clientbibliothek für Stapelanfragen verwenden, finden Sie weitere Informationen in der Dokumentation der Clientbibliothek.

Überblick

Jede HTTP-Verbindung, die der Client erstellt, führt zu einem bestimmten Overhead. Da die Google Cloud Deployment Manager V2-API Stapelanfragen unterstützt, kann Ihr Client mehrere API-Aufrufe in einer einzigen HTTP-Anfrage bündeln.

Beispiele für Situationen, in denen Stapelanfragen verwendet werden:

• Sie haben gerade mit der Verwendung der API begonnen und müssen viele Daten hochladen.
• Wenn ein Nutzer Datenänderungen vorgenommen hat, während Ihre Anwendung offline (vom Internet getrennt) war, und daher die lokalen Daten durch zahlreiche Aktualisierungs- und Löschvorgänge mit dem Server synchronisiert werden müssen.

In jedem dieser Fälle können Sie alle Aufrufe in einer einzigen HTTP-Anfrage bündeln, anstatt diese einzeln an den Server zu senden. Sie können sogar Anfragen für mehrere Nutzer oder Google APIs stapeln.

Jede Stapelanfrage ist auf maximal 1.000 Aufrufe begrenzt. Falls Sie eine höhere Anzahl an Aufrufen tätigen müssen, erstellen Sie mehrere Stapelanfragen.

Hinweis: Die Stapelverarbeitung der Google Cloud Deployment Manager V2-API verwendet dieselbe Syntax wie das Stapelverarbeitungssystem von OData, jedoch mit unterschiedlicher Semantik.

Stapeldetails

Eine Stapelanfrage besteht aus mehreren API-Aufrufen, die zu einer HTTP-Anfrage zusammengefasst wurden. In diesem Abschnitt wird die Stapelverarbeitungssyntax erörtert. Nachfolgend finden Sie ein Beispiel.

Hinweis: Eine Gruppe von n Anfragen in einem Stapel wird auf das Nutzungskontingent als n Anfragen angerechnet und nicht als eine Anfrage. Die Stapelanfrage wird vor der Verarbeitung in eine Reihe von Anfragen aufgeteilt.

Format einer Stapelanfrage

Eine Stapelanfrage ist eine einzige Standard-HTTP-Anfrage mit mehreren Google Cloud Deployment Manager V2-API-Aufrufen, die dem Inhaltstyp multipart/mixed entspricht. Jeder Teil der HTTP-Hauptanfrage enthält eine verschachtelte HTTP-Anfrage.

Jeder Teil beginnt mit einem eigenen Content-Type: application/http-HTTP-Header. Außerdem kann jeder Teil über einen optionalen Content-ID-Header verfügen. Allerdings kennzeichnen diese Teil-Header lediglich den Anfang des jeweiligen Teils und werden getrennt von der verschachtelten Anfrage aufgeführt. Nachdem der Server die Stapelanfrage in separate Anfragen zerlegt hat, werden die jeweiligen Teil-Header ignoriert.

Der Inhalt jedes Teils ist an sich eine vollständige HTTP-Anfrage mit eigenem Verb, URL, Header und Text. Die HTTP-Anfrage muss nur einen Pfadabschnitt der URL enthalten. Vollständige URLs sind bei Stapelanfragen nicht möglich.

Die HTTP-Header der äußeren Stapelanfrage – ausgenommen der Content--Header wie etwa Content-Type – gelten für alle Anfragen im Stapel. Wenn Sie sowohl für die äußere Anfrage als auch den jeweiligen Aufruf einen eigenen HTTP-Header definieren, überschreibt der Header des jeweiligen Aufrufs die Header-Werte der äußeren Anfrage. Der Header eines einzelnen Aufrufs gilt nur für den jeweiligen Aufruf.

Zum Beispiel, wenn Sie für einen spezifischen Aufruf einen Autorisierungs-Header angeben, gilt dieser Header nur für diesen Aufruf. Wird jedoch ein Autorisierungs-Header für die äußere Anfrage angegeben, gilt dieser für alle einzelnen Aufrufe, es sei denn, Sie überschreiben diesen mit eigenen Autorisierungs-Headern für jeden Aufruf.

Wenn der Server die Stapelanfrage erhält, wendet er die äußeren Abfrageparameter und Header (wenn zutreffend) auf jeden einzelnen Teil an und behandelt jeden Teil wie eine separate HTTP-Anfrage.

Antwort auf eine Stapelanfrage

Die Serverantwort ist eine einzige Standard-HTTP-Antwort mit Inhaltstyp multipart/mixed; für jeden einzelnen Aufruf in der Stapelanfrage gibt es eine eigene Antwort. Die Reihenfolge der Antworten richtet sich nach der Reihenfolge der Aufrufe in der Stapelanfrage.

Wie die Teile der Anfrage enthält auch jeder Teil der Antwort eine vollständige HTTP-Antwort mit Statuscode, Header und Text. Außerdem ist jedem Teil der Antwort – wie auch jedem Anfrageteil – ein Content-Type-Header vorangestellt, der den Anfang des jeweiligen Teils kennzeichnet.

Wenn ein bestimmter Teil der Anfrage über einen Content-ID-Header verfügt, beinhaltet der Teil der Antwort ebenfalls den entsprechenden Content-ID-Header mit dem ursprünglichen Wert und dem vorangestellten String response-. Dies ist im folgenden Beispiel dargestellt:

Hinweis: Der Server kann Ihre Aufrufe in beliebiger Reihenfolge durchführen. Rechnen Sie nicht damit, dass der Server Ihre Aufrufe in der von Ihnen festgelegten Abfolge verarbeitet. Wenn Sie sicherstellen möchten, dass zwei Aufrufe in einer bestimmten Reihenfolge durchgeführt werden, können diese nicht in einer einzigen Anfrage gesendet werden. In diesem Fall müssen Sie zuerst die erste Anfrage senden und auf die Antwort des Servers warten, bevor Sie mit der zweiten Anfrage beginnen.

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 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:[e-mail]>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:[e-mail]>

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:[e-mail]>

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

--batch_foobarbaz--

Beispielantwort auf eine Stapelanfrage

Hierbei handelt es sich um die Antwort auf die im vorherigen Abschnitt angeführte Beispiel-Stapelanfrage.

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:[e-mail]>

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:[e-mail]>

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:[e-mail]>

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

--batch_foobarbaz--