In diesem Dokument wird gezeigt, wie API-Aufrufe in einem Batch zusammengefasst werden, um die Anzahl der die der Client herstellen muss. Batching kann die durch Reduzierung der Netzwerkumläufe und erhöhten Durchsatz.
Übersicht
Jede Verbindung, die Ihr Client herstellt, führt zu einem bestimmten Overhead. Die Google Docs API unterstützt die Batchverarbeitung, damit Ihr Client mehrere Anforderungsobjekte, die jeweils einen einzelnen Typ von auszuführender Anforderung definieren, in einer einzelnen Batch-Anfrage zusammenfassen. Mit einer Batchanfrage kann die Leistung gesteigert werden, mehrere Teilanfragen zu einem einzigen Aufruf an den Server kombinieren, mit nur einer Antwort.
Wir empfehlen Nutzern, immer mehrere Anfragen in einem Batch zu verarbeiten. Hier sind einige Beispiele für Situationen, in denen Stapelanfragen verwendet werden können:
- Sie haben gerade begonnen, die API zu verwenden, und haben eine Menge Daten zum Hochladen.
- Du musst Metadaten oder Eigenschaften, z. B. die Formatierung, auf mehreren Objekte.
- Sie müssen viele Objekte löschen.
Limits, Autorisierung und Überlegungen zu Abhängigkeiten
Hier ist eine Liste weiterer Elemente, die bei der Batch-Aktualisierung zu berücksichtigen sind:
- Jede Batchanfrage, einschließlich aller Unteranfragen, wird als eine API gezählt. , um Ihr Nutzungslimit zu erhöhen.
- Eine Batchanfrage wird nur einmal authentifiziert. Diese einzelne Authentifizierung zu allen Batch-Update-Objekten in der Anfrage.
- Der Server verarbeitet die Teilanfragen in der Reihenfolge, in der sie im Batch-Anfrage. Letztere Teilanfragen können von Aktionen abhängig sein, die während früheren Unteranfragen. In derselben Batchanfrage können Nutzer beispielsweise Text in ein vorhandenes Dokument einfügen und ihn dann mit einem Stil versehen.
Batchdetails
Eine Batchanfrage besteht aus einem batchUpdate
-Methodenaufruf.
mit mehreren Unteranfragen, um beispielsweise
ein Dokument hinzuzufügen und zu formatieren.
Jede Anfrage wird überprüft, bevor sie angewendet wird. Alle Teilanfragen im Batch Aktualisierung atomar angewendet. Das heißt, wenn eine Anfrage ungültig ist, Das gesamte Update ist fehlgeschlagen und keiner der (möglicherweise abhängigen) Änderungen angewendet werden.
Einige Anfragen enthalten Antworten mit Informationen zu den angewendeten Anfragen. Beispielsweise geben alle Batch-Aktualisierungsanfragen zum Hinzufügen von Objekten Antworten zurück, können Sie auf die Metadaten des neu hinzugefügten Objekts zugreifen, z. B. die ID oder Titel.
Mit diesem Ansatz können Sie ein komplettes Google-Dokument über nur eine API erstellen. Batch-Update-Anfrage mit mehreren Unteranfragen.
Format einer Batchanfrage
Eine Anfrage ist eine einzelne JSON-Anfrage mit mehreren,
verschachtelte Unteranfragen mit einer erforderlichen Property: requests
. Die
-Anfragen werden in einem Array einzelner Anfragen konstruiert. Bei jeder Anfrage wird
JSON zur Darstellung des Anfrageobjekts und seiner Attribute.
Format einer Batchantwort
Das response-Format für eine Batchanfrage ähnelt dem Anfrageformat. Die Antwort des Servers enthält eine vollständige Antwort der Single -Antwortobjekt.
Das Attribut des JSON-Hauptobjekts heißt replies
. Die Antworten
werden in einem Array zurückgegeben, wobei jede Antwort auf eine der Anfragen
in derselben Indexreihenfolge wie in der entsprechenden Anfrage. Einige Anfragen enthalten nicht
und die Antwort bei diesem Array-Index leer ist.
Beispiel
Das folgende Codebeispiel zeigt die Verwendung der Stapelverarbeitung mit der Docs API.
Anfrage
In diesem Beispiel für eine Batchanfrage wird gezeigt, wie Sie:
Fügen Sie „Hello World“ ein Text an den Anfang eines vorhandenen Dokuments einfügen, wobei Index
location
von1
, unter Verwendung desInsertTextRequest
Das Wort „Hallo“ aktualisieren mithilfe der
UpdateTextStyleRequest
startIndex
undendIndex
definieren dierange
von formatiertem Text in auf das Segment ausgerichtet ist.Stellen Sie mit
textStyle
die Schriftart auf Fettdruck und die Farbe auf Blau ein, das Wort „Hallo“.WriteControl
verwenden können Sie steuern, wie Schreibanfragen ausgeführt werden. Weitere Informationen erhalten Sie unter Konsistenz zwischen Status und WriteControl.
{ "requests":[ { "insertText":{ "location":{ "index":1, "tabId":TAB_ID }, "text":"Hello World" } }, { "updateTextStyle":{ "range":{ "startIndex":1, "endIndex":6 }, "textStyle":{ "bold":true, "foregroundColor":{ "color":{ "rgbColor":{ "blue":1 } } } }, "fields":"bold,foreground_color" } } ], "writeControl": { "requiredRevisionId": "REQUIRED_REVISION_ID" } }
TAB_ID und REQUIRED_REVISION_ID ersetzen durch Die Tab-ID bzw. die Versions-ID des Dokuments, auf das sich die Schreibanfrage bezieht angewendet wird.
Antwort
Diese Beispiel-Batchantwort zeigt Informationen darüber an, wie jede Teilanfrage innerhalb
die Batchanfrage angewendet wurde. Weder die
InsertTextRequest
oder die
UpdateTextStyleRequest
eine Antwort enthalten, sodass die Indexwerte des Arrays bei [0] und [1] bestehen
geschweiften Klammern leer. In der Batchanfrage wird das Objekt WriteControl
angezeigt.
wie die Anfragen ausgeführt wurden.
{ "replies":[ {}, {} ], "writeControl":{ "requiredRevisionId":`REQUIRED_REVISION_ID` }, "documentId":`DOCUMENT_ID` }