Batchanfragen

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 von Batchverarbeitung mit dem Präsentationen 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 einem insertionIndex von 1 unter die CreateSlideRequest .

• Fügen Sie mithilfe der Schaltflächen shapeType TEXT_BOX zur neuen Folie CreateShapeRequest .

• 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
   }
}