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 Slides 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
eine Präsentation 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 Batchverarbeitung mit dem Slides API
Anfrage
In diesem Beispiel für eine Batchanfrage wird gezeigt, wie Sie:
Fügen Sie ein
presentations.pages
Ressource zu einer vorhandenen Präsentation mit eineminsertionIndex
von1
unter dieCreateSlideRequest
.Fügen Sie mithilfe der Schaltflächen
shapeType
TEXT_BOX
zur neuen FolieCreateShapeRequest
.Fügen Sie „Hello World“ ein mithilfe der Methode
InsertTextRequest
.
{ "requests":[ { "createSlide":{ "insertionIndex":1, "objectId":"newSlide" } }, { "createShape":{ "elementProperties":{ "pageObjectId":"newSlide", "size":{ "height":{ "magnitude":50, "unit":"PT" }, "width":{ "magnitude":200, "unit":"PT" } } }, "shapeType":"TEXT_BOX", "objectId":"newTextBox" } }, { "insertText":{ "objectId":"newTextBox", "text":"Hello World" } } ] }
Antwort
Diese Beispiel-Batchantwort zeigt Informationen darüber an, wie jede Teilanfrage innerhalb
die Batchanfrage angewendet wurde. Beachten Sie die
InsertTextRequest
enthält keine Antwort, sodass der Indexwert des Arrays [2]
aus leeren geschweiften Klammern. In der Batchanfrage wird
WriteControl
die angibt, wie die Schreibanfragen ausgeführt wurden.
{ "requiredRevisionId": ID "presentationId": "", "replies":[ { "createSlide":{ "objectId":"newSlide" } }, { "createShape":{ "objectId":"newTextBox" } }, { } ], "writeControl":{ "requiredRevisionId": REVISION_ID } }