Batchanfragen

In diesem Dokument wird gezeigt, wie API-Aufrufe in einem Batch zusammengefasst werden, um die Anzahl der Verbindungen zu reduzieren, die der Client herstellen muss. Durch Batchverarbeitung kann die Effizienz einer Anwendung verbessert werden, da weniger Netzwerkumläufe und der Durchsatz erhöht werden.

Überblick

Jede Verbindung, die Ihr Client herstellt, führt zu einem bestimmten Overhead. Die Google Slides API unterstützt die Batchverarbeitung, sodass Ihr Client mehrere Anfrageobjekte in einer einzelnen Batchanfrage platzieren kann, wobei jedes Anfrageobjekt einen bestimmten Anfragetyp angibt. Mit einer Batchanfrage kann die Leistung gesteigert werden, indem mehrere Unteranfragen zu einem einzigen Aufruf an den Server kombiniert werden und eine einzelne Antwort abgerufen wird.

Wir empfehlen den Nutzern, immer mehrere Anfragen in einem Batch zusammenzufassen. Hier sind einige Beispiele für Situationen, in denen Sie die Batchverarbeitung verwenden können:

• Sie haben gerade mit der Verwendung der API begonnen und müssen viele Daten hochladen.
• Sie müssen Metadaten oder Eigenschaften wie die Formatierung für mehrere Objekte aktualisieren.
• Sie müssen viele Objekte löschen.

Überlegungen zu Limits, Autorisierungen und Abhängigkeiten

Im Folgenden finden Sie eine Liste weiterer Punkte, die bei der Batch-Aktualisierung zu berücksichtigen sind:

• Jede Batchanfrage, einschließlich aller Unteranfragen, wird als eine einzelne API-Anfrage auf Ihr Nutzungslimit angerechnet.
• Eine Batchanfrage wird einmal authentifiziert. Diese eine Authentifizierung gilt für alle Objekte für die Batch-Aktualisierung in der Anfrage.
• Der Server verarbeitet die Unteranfragen in derselben Reihenfolge, in der sie in der Batchanfrage vorkommen. Spätere Unteranfragen können von Aktionen abhängen, die während früherer Unteranfragen ausgeführt wurden. Beispielsweise können Nutzer in derselben Batchanfrage Text in ein vorhandenes Dokument einfügen und dann einen Stil dafür festlegen.

Batchdetails

Eine Batchanfrage besteht aus einem Aufruf der Methode batchUpdate mit mehreren Unteranfragen, um beispielsweise eine Präsentation hinzuzufügen und zu formatieren.

Jede Anfrage wird überprüft, bevor sie angewendet wird. Alle Unteranfragen im Batch-Update werden in kleinstmöglichen Schritten angewendet. Das heißt, wenn eine Anfrage ungültig ist, schlägt die gesamte Aktualisierung fehl und es wird keine der (potenziell abhängigen) Änderungen angewendet.

Einige Anfragen enthalten Antworten mit Informationen zu den angewendeten Anfragen. Beispielsweise geben alle Batch-Aktualisierungsanfragen zum Hinzufügen von Objekten Antworten zurück, sodass Sie auf die Metadaten des neu hinzugefügten Objekts zugreifen können, z. B. die ID oder den Titel.

Bei diesem Ansatz können Sie ein vollständiges Google-Dokument mithilfe einer einzigen API-Batch-Aktualisierungsanfrage mit mehreren Unteranfragen erstellen.

Format einer Batchanfrage

Eine Anfrage ist eine einzelne JSON-Anfrage, die mehrere verschachtelte Unteranfragen mit einem erforderlichen Attribut enthält: requests. Die Anfragen werden in einem Array einzelner Anfragen erstellt. In jeder Anfrage wird JSON verwendet, um das Anfrageobjekt darzustellen und seine Attribute zu enthalten.

Format einer Batchantwort

Das Antwortformat für eine Batchanfrage ähnelt dem Anfrageformat. Die Antwort des Servers enthält eine vollständige Antwort des einzelnen Antwortobjekts.

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 die entsprechende Anfrage ist. Einige Anfragen haben keine Antworten und die Antwort an diesem Arrayindex ist leer.

Beispiel

Im folgenden Codebeispiel wird die Verwendung der Batchverarbeitung mit der Slides API veranschaulicht.

Anfragen

Diese Beispiel-Batchanfrage zeigt, wie Sie:

• Fügen Sie einer vorhandenen Präsentation mit der Methode CreateSlideRequest eine presentations.pages-Ressource mit einem insertionIndex von 1 hinzu.

• Fügen Sie der neuen Folie mit der Methode CreateShapeRequest ein shapeType vom Typ TEXT_BOX hinzu.

• Fügen Sie mit der Methode InsertTextRequest „Hello World“-Text in das neue Feld ein.

{
   "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 exemplarische Batchantwort enthält Informationen darüber, wie jede Unteranfrage innerhalb der Batchanfrage angewendet wurde. Beachten Sie, dass die Methode InsertTextRequest keine Antwort enthält. Daher besteht der Indexwert des Arrays bei [2] aus leeren geschweiften Klammern. In der Batchanfrage wird das Attribut WriteControl angezeigt, das angibt, wie die Schreibanfragen ausgeführt wurden.

{
   "requiredRevisionId": ID
   "presentationId": "",
   "replies":[
      {
         "createSlide":{
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "objectId":"newTextBox"
         }
      },
      {
         
      }
   ],
   "writeControl":{
      "requiredRevisionId": REVISION_ID
   }
}