Batchanfragen

In diesem Dokument erfahren Sie, wie API-Aufrufe in einem Batch zusammengefasst werden, um die Anzahl von Verbindungen für den Client zu reduzieren. Durch Batchverarbeitung kann die Effizienz einer Anwendung verbessert werden, da Netzwerkumläufe reduziert und der Durchsatz erhöht werden.

Übersicht

Jede Verbindung, die der Client herstellt, führt zu einem bestimmten Overhead. Die Google Docs API unterstützt Batchanfragen, damit Ihr Client mehrere Anfrageobjekte in einer einzigen Batchanfrage zusammenfassen kann. Jedes Anfrageobjekt gibt dabei eine einzelne auszuführende Anfrage an. Mit einer Batchanfrage lässt sich die Leistung steigern, indem mehrere untergeordnete Anfragen in einem einzigen Serveraufruf kombiniert und eine einzelne Antwort zurückgegeben wird.

Wir empfehlen Nutzern, immer mehrere Anfragen gleichzeitig zu senden. Hier einige Beispiele für Situationen, in denen Sie Batchanfragen 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.

Einschränkungen, Autorisierung und Abhängigkeiten

Beachten Sie bei der Batch-Aktualisierung Folgendes:

  • Jede Batchanfrage, einschließlich aller untergeordneten Anfragen, wird als eine API-Anfrage auf Ihr Nutzungskontingent angerechnet.
  • Eine Batchanfrage wird einmal authentifiziert. Diese einmalige Authentifizierung gilt für alle Objekte in der Batchaktualisierungsanfrage.
  • Der Server verarbeitet die Teilanfragen in der Reihenfolge, in der sie in der Batchanfrage erscheinen. Letztere können von Aktionen abhängen, die bei früheren untergeordneten Anfragen ausgeführt wurden. So können Nutzer beispielsweise in derselben Batchanfrage Text in ein vorhandenes Dokument einfügen und dann formatieren.

Batchdetails

Eine Batchanfrage besteht aus einem batchUpdate-Methodenaufruf mit mehreren untergeordneten Anfragen, um beispielsweise ein Dokument hinzuzufügen und dann zu formatieren.

Jede Anfrage wird vor der Anwendung validiert. Alle untergeordneten Anfragen in der Batchaktualisierung werden in kleinstmöglichen Schritten angewendet. Wenn eine Anfrage ungültig ist, schlägt die gesamte Aktualisierung fehl und keine der (potenziell abhängigen) Änderungen werden angewendet.

Bei einigen Anfragen enthalten die Antworten Informationen zu den angewandten Anfragen. Beispielsweise werden für alle Batch-Update-Anfragen zum Hinzufügen von Objekten Antworten zurückgegeben, damit Sie auf die Metadaten des neu hinzugefügten Objekts zugreifen können, z. B. die ID oder den Titel.

Mit diesem Ansatz können Sie ein vollständiges Google-Dokument mit einer API-Batchaktualisierungsanfrage mit mehreren untergeordneten Anfragen erstellen.

Format einer Batchanfrage

Eine Anfrage ist eine einzelne JSON-Anfrage mit mehreren verschachtelten Unteranfragen mit einer erforderlichen Property: requests. Die Anfragen werden in einem Array von einzelnen Anfragen erstellt. Bei jeder Anfrage wird JSON verwendet, um das Anfrageobjekt darzustellen und seine Eigenschaften 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 Haupt-JSON-Objekts heißt replies. Die Antworten werden in einem Array zurückgegeben. Jede Antwort auf eine der Anfragen hat dieselbe Indexreihenfolge wie die entsprechende Anfrage. Einige Anfragen haben keine Antworten und die Antwort an diesem Arrayindex ist leer.

Beispiel

Das folgende Codebeispiel zeigt die Verwendung von Batch-Vorgängen mit der Docs API.

Anfrage

In dieser Beispiel-Batchanfrage wird Folgendes veranschaulicht:

  • Fügen Sie den Text „Hallo Welt“ mit dem Index location = 1 an den Anfang eines vorhandenen Dokuments ein. Verwenden Sie dazu InsertTextRequest.

  • Aktualisieren Sie das Wort „Hallo“ mit dem Befehl UpdateTextStyleRequest. startIndex und endIndex definieren die range des formatierten Texts innerhalb des Segments.

  • Verwenden Sie textStyle, um nur das Wort „Hallo“ fett und blau zu formatieren.

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

{
   "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"
  }
}

Ersetzen Sie TAB_ID und REQUIRED_REVISION_ID durch die Tab-ID bzw. die Revision-ID des Dokuments, auf das die Schreibanfrage angewendet wird.

Antwort

Diese Beispiel-Batchantwort enthält Informationen dazu, wie jede untergeordnete Anfrage innerhalb der Batchanfrage angewendet wurde. 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 WriteControl-Objekt angezeigt, das Aufschluss darüber gibt, wie die Anfragen ausgeführt wurden.

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