Diese Seite wurde von der Cloud Translation API übersetzt.

Leistung optimieren

In diesem Dokument werden einige Techniken beschrieben, mit denen Sie die Leistung Ihrer Anwendung verbessern können. In einigen Fällen werden Beispiele aus anderen APIs oder generischen APIs verwendet, um die vorgestellten Ideen zu erläutern. Dieselben Konzepte gelten jedoch auch für die Google Drive API.

Komprimierung mit gzip

Durch Aktivierung der gzip-Komprimierung kann die für jede Anfrage benötigte Bandbreite einfach und bequem reduziert werden. Auch wenn die Dekomprimierung der Ergebnisse zusätzliche CPU-Zeit kostet, lohnt sie sich verglichen mit den Netzwerkkosten durchaus.

Sie müssen zwei Schritte ausführen, um eine mit gzip codierte Antwort zu erhalten: Legen Sie einen Header Accept-Encoding fest und ändern Sie den User-Agent so, dass er den String gzip enthält. Hier ein Beispiel für HTTP-Header im korrekten Format zur Aktivierung der gzip-Komprimierung:

Accept-Encoding: gzip
User-Agent: my program (gzip)

Mit Teilressourcen arbeiten

Eine andere Möglichkeit zur Verbesserung der Leistung der API-Aufrufe besteht darin, nur den Teil der Daten zu senden und zu empfangen, der für Sie interessant ist. Dadurch lassen sich in der Anwendung die Übertragung, Analyse und Speicherung nicht benötigter Felder vermeiden und so Ressourcen wie Netzwerke, CPU und Speicher effizienter nutzen.

Es gibt zwei Arten von Teilanfragen:

Teilantwort: Eine Anfrage, mit der Sie angeben, welche Felder in der Antwort enthalten sein sollen. Verwenden Sie dazu den Anfrageparameter fields.
Patch: Eine Aktualisierungsanfrage, bei der Sie nur die zu ändernden Felder senden. Verwenden Sie dazu das HTTP-Verb PATCH.

In den folgenden Abschnitten finden Sie weitere Informationen zu Teilanfragen.

Teilantwort

Standardmäßig wird vom Server nach der Verarbeitung einer Anfrage die komplette Darstellung einer Ressource zurückgeliefert. Sie können den Server zwecks Leistungsverbesserung aber auch anweisen, nur die Felder zu senden, die Sie wirklich benötigen, und erhalten dann eine Teilantwort.

Verwenden Sie zum Anfragen einer Teilantwort den Anfrageparameter fields, um anzugeben, welche Felder zurückgegeben werden sollen. Sie können diesen Parameter mit jeder beliebigen Anfrage verwenden, die Antwortdaten zurückgibt.

Beachten Sie, dass sich der fields-Parameter nur auf die Antwortdaten auswirkt. Er wirkt sich nicht auf die Daten aus, die Sie (gegebenenfalls) senden müssen. Verwenden Sie eine Patch-Anfrage, um die Datenmenge zu reduzieren, die bei der Änderung von Ressourcen gesendet wird.

Beispiel

Das folgende Beispiel zeigt die Verwendung des fields-Parameters mit einer allgemeinen (fiktiven) "Demo"-API.

Einfache Anfrage: Bei dieser HTTP-GET-Anfrage wird der Parameter fields weggelassen und die vollständige Ressource zurückgegeben.

https://www.googleapis.com/demo/v1

Antwort mit vollständiger Ressource: Die vollständigen Ressourcendaten umfassen folgende Felder sowie zahlreiche weitere Felder, die der Übersichtlichkeit halber ausgelassen wurden.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

Anfrage für eine Teilantwort: In der folgenden Anfrage für dieselbe Ressource wird der Parameter fields verwendet, um die zurückgegebene Datenmenge erheblich zu verringern.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Teilantwort: Als Antwort auf die obige Anfrage sendet der Server eine Antwort zurück, die zusammen mit einem einfachen Array nur die Art von Informationen enthält, die ausschließlich HTML-Titel und Längeneigenschaften in jedem Element umfassen.

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Bei der Antwort handelt es sich um ein JSON-Objekt, das nur die ausgewählten Felder und deren einschließende übergeordnete Objekte enthält.

Details zur Formatierung des fields-Parameters werden als Nächstes beschrieben, gefolgt von weiteren Informationen zum genauen Inhalt, der in der Antwort zurückgegeben wird.

Parameter "Fields" – Syntaxzusammenfassung

Das Format des fields-Anfrageparameters basiert grob auf der XPath-Syntax. Die unterstützte Syntax wird unten zusammengefasst. Zusätzliche Beispiele finden Sie im darauffolgenden Abschnitt.

Zur Auswahl mehrerer Felder verwenden Sie eine durch Kommas getrennte Liste.
Verwenden Sie a/b, um ein Feld b auszuwählen, das im Feld a verschachtelt ist; verwenden Sie a/b/c, um ein Feld c auszuwählen, das in b verschachtelt ist.
Ausnahme: Bei API-Antworten mit "data"-Wrappern, bei denen die Antwort in einem Objekt vom Typ data in der Form data: { ... } verschachtelt ist, darf "data" nicht in die Spezifikation von fields aufgenommen werden. Die Aufnahme eines Datenobjekts in einer Feldspezifikation wie data/a/b führt zu einem Fehler. Verwenden Sie stattdessen eine fields-Angabe wie a/b.
Verwenden Sie ein untergeordnetes Auswahlzeichen, um eine Reihe von untergeordneten Feldern von Arrays oder Objekten anzufordern, indem Sie Ausdrücke in Klammern "( )" setzen.
Beispiel: fields=items(id,author/email) gibt nur die Element-ID und die E-Mail-Adresse des Autors für jedes Element im Array zurück. Sie können auch ein einzelnes Teilfeld angeben, in dem fields=items(id) fields=items/id entspricht.
Verwenden Sie gegebenenfalls Platzhalter bei der Feldauswahl.
Zum Beispiel: Mit fields=items/pagemap/* werden alle Objekte in einer Pagemap ausgewählt.

Weitere Beispiele zur Verwendung des Parameters "Fields"

In diesen Beispielen wird auch beschrieben, wie sich der Wert des Parameters fields auf die Antwort auswirkt.

Hinweis: Wie bei allen Abfrageparameterwerten muss der Wert des Parameters fields URL-codiert sein. Die Beispiele in diesem Dokument enthalten für eine bessere Lesbarkeit keine Codierung.

Identifizieren Sie die Felder, die zurückgegeben werden sollen, oder treffen Sie eine Feldauswahl.

Der Wert des Anfrageparameters fields besteht aus einer durch Kommas getrennten Liste mit Feldern. Jedes Feld muss relativ zum Stamm der Antwort angegeben werden. Wenn Sie also einen list-Vorgang ausführen, besteht die Antwort aus einer Sammlung und enthält im Allgemeinen ein Ressourcen-Array. Bei einem Vorgang, der eine einzelne Ressource zurückgibt, werden die Felder bezogen auf diese Ressource angegeben. Wenn das ausgewählte Feld ein Array (oder ein Teil eines Arrays) ist, gibt der Server den ausgewählten Teil aller Elemente in dem Array zurück.

Hier einige Beispiele für die Sammlungsebene:

Beispiele	Effekt
`items`	Gibt alle Elemente im Element-Array zurück, einschließlich aller Felder in jedem Element, jedoch keine anderen Felder.
`etag,items`	Gibt sowohl das `etag`-Feld als auch alle Elemente im Element-Array zurück.
`items/title`	Gibt nur das `title`-Feld für alle Elemente im Element-Array zurück. Wenn ein verschachteltes Feld zurückgegeben wird, umfasst die Antwort die einschließenden übergeordneten Objekte. Die übergeordneten Felder enthalten nur dann andere untergeordnete Felder, wenn diese ausdrücklich ausgewählt wurden.
`context/facets/label`	Gibt nur das Feld `label` für alle Mitglieder des Arrays `facets` zurück, das selbst unter dem Objekt `context` verschachtelt ist.
`items/pagemap/*/title`	Gibt für jedes Element im Element-Array nur das `title`-Feld (sofern vorhanden) aller Objekte zurück, die untergeordnete Objekte von `pagemap` sind.

Hier einige Beispiele für die Ressourcenebene:

Beispiele	Effekt
`title`	Gibt das Feld `title` der angeforderten Ressource zurück.
`author/uri`	Gibt das Unterfeld `uri` des Objekts `author` in der angeforderten Ressource zurück.
`links/*/href`	Gibt das Feld `href` aller Objekte zurück, die untergeordnete Objekte von `links` sind.

Mit der untergeordneten Auswahl fordern Sie nur Teile bestimmter Felder an.

Wenn in Ihrer Anfrage bestimmte Felder spezifiziert werden, gibt der Server standardmäßig die Objekte oder Array-Elemente in ihrer Gesamtheit zurück. Sie können eine Antwort angeben, die nur bestimmte untergeordnete Felder enthält. Dazu verwenden Sie die Syntax "( )" für die untergeordnete Auswahl wie im folgenden Beispiel dargestellt.

Beispiel	Effekt
`items(title,author/uri)`	Gibt nur die Werte von `title` und den `uri` des Autors für jedes Element im Element-Array zurück.

Umgang mit Teilantworten

Nachdem ein Server eine gültige Anfrage verarbeitet hat, die den fields-Abfrageparameter enthält, sendet er einen 200 OK-HTTP-Statuscode zusammen mit den angeforderten Daten zurück. Wenn der fields-Abfrageparameter einen Fehler enthält oder ungültig ist, gibt der Server einen 400 Bad Request-HTTP-Statuscode zusammen mit einer Fehlermeldung zurück, die den Nutzer darüber informiert, was bei seiner Feldauswahl falsch war (Beispiel: "Invalid field selection a/b").

Hier ein Beispiel für eine Teilantwort, die im einführenden Abschnitt oben dargestellt wurde. Mit dem Parameter fields gibt die Anfrage an, welche Felder zurückgegeben werden sollen.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Die Teilantwort sieht folgendermaßen aus:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Hinweis: Bei APIs, die Abfrageparameter für die Datenpaginierung (wie beispielsweise maxResults und nextPageToken) unterstützen, können Sie mit diesen Parametern die Ergebnisse der einzelnen Abfragen auf eine überschaubare Größe reduzieren. Andernfalls wären Leistungssteigerungen mit einer Teilantwort eventuell nicht realisierbar.

Patch (Teilaktualisierung)

Sie können auch das Senden von unnötigen Daten vermeiden, wenn Sie Ressourcen ändern. Um nur aktualisierte Daten für die Felder zu senden, die Sie ändern, verwenden Sie das HTTP-Verb PATCH. Die Patch-Semantik, die in diesem Dokument beschrieben wird, ist anders (und einfacher) als die der älteren GData-Implementierung einer Teilaktualisierung.

Das kurze Beispiel unten zeigt, wie mit einer Patch-Anfrage die Datenmenge minimiert wird, die Sie zur Durchführung eines kleinen Updates benötigen.

Beispiel

Dieses Beispiel zeigt eine einfache Patch-Anfrage, mit der nur der Titel einer allgemeinen (fiktiven) "Demo"-API-Ressource aktualisiert werden soll. Die Ressource enthält auch einen Kommentar, eine Reihe von Eigenschafts-, Status- und viele andere Felder. Diese Anfrage sendet jedoch nur das Feld title, da dieses Feld als einziges geändert wird:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

Antwort:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

Der Server gibt einen 200 OK-Statuscode zusammen mit der vollständigen Darstellung der aktualisierten Ressource zurück. Da nur das Feld title in der Patch-Anfrage enthalten war, ist dies der einzige Wert, der sich von den vorherigen Werten unterscheidet.

Hinweis: Wenn Sie den Parameter fields einer Teilantwort in Verbindung mit einem Patch verwenden, können Sie Aktualisierungsanfragen noch weiter optimieren. Mit einer Patch-Anfrage wird nur die Größe der Anfrage reduziert. Eine Teilantwort reduziert die Größe der Antwort. Um also die in beiden Richtungen gesendete Datenmenge zu reduzieren, verwenden Sie eine Patch-Anfrage mit dem fields-Parameter.

Semantik einer Patch-Anfrage

Der Text der Patch-Anfrage umfasst nur die Ressourcenfelder, die Sie ändern möchten. Bei der Angabe eines Feldes müssen Sie einschließende übergeordnete Objekte einbeziehen, da die einschließenden übergeordneten Objekte mit einer Teilantwort zurückgegeben werden. Die geänderten Daten, die Sie senden, werden mit den Daten für das übergeordnete Objekt, sofern vorhanden, zusammengeführt.

Hinzufügen: Um ein Feld hinzuzufügen, das noch nicht vorhanden ist, geben Sie das neue Feld und dessen Wert an.
Ändern: Um den Wert eines vorhandenen Feldes zu ändern, geben Sie das Feld an und legen es auf den neuen Wert fest.
Löschen: Geben Sie das zu löschende Feld an und setzen Sie es auf null. Beispiel: "comment": null. Sie können auch ein ganzes Objekt löschen (wenn es änderbar ist), indem Sie es auf null setzen. Bei der Java API-Clientbibliothek verwenden Sie stattdessen Data.NULL_STRING. Weitere Informationen finden Sie unter JSON null.

Hinweis zu Arrays: Patch-Anfragen, die Arrays enthalten, ersetzen das vorhandene Array durch das Array, das Sie angeben. Sie können ein Array nicht stückweise ändern, hinzufügen oder löschen.

Patch in einem Read-Modify-Write-Zyklus verwenden

Es kann in der Praxis sinnvoll sein, wenn Sie als Erstes eine Teilantwort mit den Daten abrufen, die Sie ändern möchten. Dies ist besonders wichtig bei Ressourcen, die ETags verwenden, weil Sie den aktuellen ETag-Wert im HTTP-Header If-Match angeben müssen, um die Ressource erfolgreich zu aktualisieren. Nachdem Sie die Daten abgerufen haben, können Sie die gewünschten Werte ändern und die geänderte Teildarstellung mit einer Patch-Anfrage wieder zurücksenden. Beim folgenden Beispiel wird davon ausgegangen, dass die Demo-Ressource ETags verwendet:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

Dies ist die Teilantwort:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

Die folgende Patch-Anfrage basiert auf dieser Antwort. Wie unten dargestellt, verwendet die Anfrage auch den Parameter fields, um die in der Patch-Antwort zurückgegebenen Daten zu begrenzen:

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

Der Server antwortet mit einem HTTP-Statuscode "200 OK" und der Teildarstellung der aktualisierten Ressource:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

Patch-Anfrage direkt erstellen

Einige Patch-Anfragen müssen auf den Daten aufbauen, die Sie vorher abgerufen haben. Beispiel: Wenn Sie ein Element einem Array hinzufügen und keines der vorhandenen Array-Elemente verlieren möchten, müssen Sie zuerst die vorhandenen Daten abrufen. Wenn eine API ETags verwendet, müssen Sie den vorherigen ETag-Wert mit der Anfrage senden, damit die Ressource erfolgreich aktualisiert werden kann.

Hinweis: Mit dem HTTP-Header "If-Match: *" können Sie einen Patch erzwingen, wenn ETags verwendet werden. In diesem Fall müssen Sie den Lesevorgang nicht vor dem Schreibvorgang ausführen.

In anderen Fällen können Sie die Patch-Anfrage direkt erstellen, ohne zuvor die vorhandenen Daten abzurufen. Beispiel: Sie können jederzeit eine Patch-Anfrage einrichten, die ein Feld mit einem neuen Wert aktualisiert oder ein neues Feld hinzufügt. Hier ein Beispiel:

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

Wenn das Kommentarfeld bei dieser Anfrage einen vorhandenen Wert hat, überschreibt der neue Wert diesen. Ansonsten wird er auf den neuen Wert festgelegt. Wenn eine Volumeneigenschaft vorhanden war, wird ihr Wert ebenfalls überschrieben; wenn nicht, wird sie erstellt. Das Genauigkeitsfeld, falls festgelegt, wird entfernt.

Umgang mit der Antwort auf ein Patch

Nachdem eine gültige Patch-Anfrage verarbeitet wurde, gibt die API einen HTTP-Antwortcode 200 OK zusammen mit der vollständigen Darstellung der geänderten Ressource zurück. Wenn ETags von der API verwendet werden, aktualisiert der Server ETag-Werte, sobald eine Patch-Anfrage erfolgreich verarbeitet wird, wie bei PUT.

Die Patch-Anfrage gibt die vollständige Ressourcendarstellung zurück, es sei denn, Sie verwenden den fields-Parameter, um die zurückgegebene Datenmenge zu reduzieren.

Wenn eine Patch-Anfrage zu einem neuen Ressourcenstatus führt, der syntaktisch oder semantisch ungültig ist, gibt der Server einen HTTP-Statuscode 400 Bad Request oder 422 Unprocessable Entity zurück und der Ressourcenstatus bleibt unverändert. Beispiel: Wenn Sie versuchen, den Wert für ein Pflichtfeld zu löschen, gibt der Server einen Fehler zurück.

Alternative Schreibweise, wenn das PATCH-HTTP-Verb nicht unterstützt wird

Wenn Ihre Firewall keine HTTP-PATCH-Anfragen unterstützt, führen Sie eine HTTP-POST-Anfrage aus und setzen Sie den Override-Header auf PATCH (wie unten dargestellt):

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

Unterschied zwischen Patch und Aktualisierung

Wenn Sie in der Praxis Daten für eine Aktualisierungsanfrage senden, die das HTTP-Verb PUT verwendet, müssen Sie nur die Felder senden, die erforderlich oder optional sind. Wenn Sie Werte für Felder senden, die vom Server festgelegt werden, werden diese ignoriert. Obwohl dies wie eine andere Möglichkeit für eine Teilaktualisierung aussieht, hat dieser Ansatz einige Einschränkungen. Mit Aktualisierungen, die das HTTP-Verb PUT verwenden, schlägt die Anfrage fehl, wenn Sie erforderliche Parameter nicht angeben. Vorher festgelegte Daten werden gelöscht, wenn Sie keine optionalen Parameter angeben.

Aus diesem Grund ist die Verwendung eines Patch wesentlich sicherer. Sie geben nur Daten für die Felder an, die Sie ändern möchten; Felder, die Sie weglassen, werden nicht gelöscht. Sich wiederholende Elemente oder Arrays sind die einzige Ausnahme zu dieser Regel. Wenn Sie diese alle weglassen, bleiben sie unverändert. Wenn Sie ein Element oder Array angeben, wird das ganze Set durch das Set ersetzt, das Sie angeben.

Batchanfragen

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, lesen Sie die Informationen in der Dokumentation der Clientbibliothek.

Übersicht

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

Fallbeispiele für den Einsatz von Batchanfragen:

Abrufen von Metadaten für eine große Anzahl von Dateien
Metadaten oder Properties im Bulk-Verfahren aktualisieren
Berechtigungen für eine große Anzahl von Dateien ändern, z. B. einen neuen Nutzer oder eine neue Gruppe hinzufügen
Synchronisierung lokaler Clientdaten zum ersten Mal oder nach einer längeren Offlinezeit

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 Google API gesendet werden.

Jede Batchanfrage ist auf maximal 100 Aufrufe begrenzt. Falls Sie eine größere Anzahl an Aufrufen benötigen, verwenden Sie mehrere Batchanfragen.

Hinweis: Die Batchverarbeitung der Google Drive API verwendet dieselbe Syntax wie die Batchverarbeitung von OData, jedoch mit einer anderen Semantik.

Weitere Einschränkungen:

Batchanfragen mit mehr als 100 Aufrufen können zu einem Fehler führen.
Die URL für jede innere Anfrage darf maximal 8.000 Zeichen lang sein.
In Google Drive werden keine Batch-Vorgänge für Medien unterstützt, weder für den Upload noch für den Download oder den Export von Dateien.

Batchdetails

Eine Batchanfrage besteht aus mehreren, in einer HTTP-Anfrage zusammengefassten API-Aufrufen. Sie kann an den im Discovery-Dokument der API 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 Batchanfrage

Eine Batchanfrage ist eine einzelne Standard-HTTP-Anfrage, die mehrere Google Drive API-Aufrufe enthält. Dabei wird der Inhaltstyp multipart/mixed verwendet. Jeder Teil der HTTP-Hauptanfrage enthält eine verschachtelte HTTP-Anfrage.

Jeder Teil beginnt mit seinem eigenen HTTP-Header Content-Type: application/http. Er kann auch einen optionalen Content-ID-Header haben. Die Header der einzelnen Teile sollen jedoch nur den Anfang des Teils markieren. Sie sind von der verschachtelten Anfrage getrennt. 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. Die HTTP-Anfrage darf nur den Pfadteil der URL enthalten; vollständige URLs sind in Batchanfragen nicht zulässig.

Die HTTP-Header für die äußere Batchanfrage gelten für jede Anfrage in dem Batch, 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 Batchanfrage

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

Das folgende Beispiel zeigt die Verwendung der Batchverarbeitung mit der Google Drive API.

Beispiel-Batchanfrage

POST https://www.googleapis.com/batch/drive/v3 Accept-Encoding: gzip User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip) Content-Type: multipart/mixed; boundary=END_OF_PART Content-Length: 963

--END_OF_PART Content-Length: 337 Content-Type: application/http content-id: 1 content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id Authorization: Bearer authorization_token Content-Length: 70 Content-Type: application/json; charset=UTF-8

{ "emailAddress":"example@appsrocks.com", "role":"writer", "type":"user" } --END_OF_PART Content-Length: 353 Content-Type: application/http content-id: 2 content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false Authorization: Bearer authorization_token Content-Length: 58 Content-Type: application/json; charset=UTF-8

{ "domain":"appsrocks.com", "role":"reader", "type":"domain" } --END_OF_PART--

Beispiel für eine Stapelantwort

Dies ist die Antwort auf die Beispielanfrage im vorherigen Abschnitt.

HTTP/1.1 200 OK Alt-Svc: quic=":443"; p="1"; ma=604800 Server: GSE Alternate-Protocol: 443:quic,p=1 X-Frame-Options: SAMEORIGIN Content-Encoding: gzip X-XSS-Protection: 1; mode=block Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk Transfer-Encoding: chunked X-Content-Type-Options: nosniff Date: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Vary: X-Origin Vary: Origin Expires: Fri, 13 Nov 2015 19:28:59 GMT

--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-1

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35

{ "id": "12218244892818058021i" }

--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-2

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35

{ "id": "04109509152946699072k" }

--batch_6VIxXCQbJoQ_AATxy_GgFUk--

Bestimmte Felder aus der Anfrage zurückgeben

Standardmäßig gibt der Server einen Standardsatz von Ressourcenfeldern zurück, die für die verwendete Methode spezifisch sind. Die Methode files.list gibt beispielsweise möglicherweise nur id, name und mimeType zurück. Diese Felder sind möglicherweise nicht genau die, die Sie benötigen. Wenn Sie andere Felder zurückgeben möchten, lesen Sie den Hilfeartikel Bestimmte Felder für eine Datei zurückgeben.