Batchanfragen

In diesem Dokument wird beschrieben, wie API-Aufrufe in einem Batch zusammengefasst werden, um die Anzahl der Verbindungen zu verringern, die der Client herstellen muss. Batching kann die Effizienz einer Anwendung verbessern, da die Netzwerkumläufe reduziert und der Durchsatz erhöht werden.

Überblick

Jede Verbindung, die Ihr Client herstellt, führt zu einem bestimmten Overhead. Die Google Docs API unterstützt die Batchverarbeitung, damit Ihr Client mehrere Anfrageobjekte mit jeweils einem Typ von auszuführender Anfrage in einer einzelnen Batchanfrage platzieren kann. Eine Batchanfrage kann die Leistung steigern, indem mehrere Unteranfragen zu einem einzigen Aufruf an den Server kombiniert und eine einzelne Antwort abgerufen werden.

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

  • Sie haben gerade begonnen, die API zu verwenden, und haben eine Menge Daten zum Hochladen.
  • Sie müssen Metadaten oder Attribute wie die Formatierung für mehrere Objekte aktualisieren.
  • Sie müssen viele Objekte löschen.

Überlegungen zu Limits, Autorisierungen und Abhängigkeiten

Hier ist eine Liste weiterer Elemente, die bei der Batch-Aktualisierung zu berücksichtigen sind:

  • Jede Batchanfrage, einschließlich aller Teilanfragen, wird als eine API-Anfrage auf Ihr Nutzungslimit angerechnet.
  • Eine Batchanfrage wird nur einmal authentifiziert. Diese einzelne Authentifizierung gilt für alle Batch-Update-Objekte in der Anfrage.
  • Der Server verarbeitet die Teilanfragen in der Reihenfolge, in der sie in der Batchanfrage aufgeführt sind. Letztere Unteranfragen können von Aktionen abhängig sein, die bei früheren Unteranfragen ausgeführt wurden. In derselben Batchanfrage können Nutzer beispielsweise Text in ein vorhandenes Dokument einfügen und diesen dann mit einem Stil versehen.

Batchdetails

Eine Batchanfrage besteht aus einem Aufruf der batchUpdate-Methode mit mehreren Unteranfragen, beispielsweise zum Hinzufügen und Formatieren eines Dokuments.

Jede Anfrage wird überprüft, bevor sie angewendet wird. Alle Teilanfragen in der Batchaktualisierung werden in kleinstmöglichen Schritten angewendet. Wenn also eine Anfrage ungültig ist, schlägt die gesamte Aktualisierung fehl und keine der (möglicherweise abhängigen) Änderungen wird 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. auf die ID oder den Titel.

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

Format einer Batchanfrage

Eine Anfrage ist eine einzelne JSON-Anfrage, die mehrere verschachtelte Unteranfragen mit einer erforderlichen Property enthält: requests. Die Anfragen werden in einem Array aus einzelnen Anfragen konstruiert. Bei jeder Anfrage wird JSON zur Darstellung des Anfrageobjekts und zum Aufnehmen seiner Attribute verwendet.

Format einer Batchantwort

Das response-Format 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 dieselbe Indexreihenfolge wie die entsprechende Anfrage belegt. Einige Anfragen haben keine Antworten und die Antwort bei diesem Array-Index ist leer.

Beispiel

Das folgende Codebeispiel zeigt die Verwendung der Stapelverarbeitung mit der Docs API.

Anfragen

In diesem Beispiel für eine Batchanfrage wird gezeigt, wie Sie:

  • Fügen Sie am Anfang eines vorhandenen Dokuments „Hello World“-Text mit dem Index location 1 ein. Verwenden Sie dazu InsertTextRequest.

  • Aktualisieren Sie das Wort „Hello“ mit dem UpdateTextStyleRequest. Mit startIndex und endIndex wird die range von formatiertem Text im Segment definiert.

  • Legen Sie mit textStyle die Schriftart für das Wort „Hello“ auf Fett und die Farbe auf Blau fest.

  • Mit dem Feld WriteControl können Sie steuern, wie Schreibanfragen ausgeführt werden. Weitere Informationen finden Sie unter Statuskonsistenz mit WriteControl einrichten.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1
            },
            "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"
  }
}

Ersetzen Sie REQUIRED_REVISION_ID durch die Überarbeitungs-ID des Dokuments, auf das die Schreibanfrage angewendet wird.

Antwort

Diese Beispiel-Batchantwort zeigt Informationen darüber, wie die einzelnen Teilanfragen innerhalb der Batchanfrage angewendet wurden. Weder InsertTextRequest noch UpdateTextStyleRequest enthalten eine Antwort. Daher bestehen die Indexwerte des Arrays bei [0] und [1] aus leeren geschweiften Klammern. In der Batchanfrage wird das Objekt WriteControl angezeigt, das angibt, wie die Anfragen ausgeführt wurden.

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}