Batchanfragen

In diesem Dokument erfahren Sie, wie API-Aufrufe in einem Batch zusammengefasst werden, um die Anzahl der Verbindungen zu verringern, die Ihr Client herstellen muss. Durch die Batchverarbeitung können Sie die Effizienz einer Anwendung verbessern, da die Netzwerkumlaufzeiten verringert und der Durchsatz erhöht wird.

Übersicht

Jede Verbindung, die Ihr Client herstellt, führt zu einem gewissen Overhead. Die Google Docs API unterstützt die Batchverarbeitung, damit der Client mehrere Anfrageobjekte für jedes Batchobjekt in einer einzelnen Anfrage stellen kann. Mit einer Batchanfrage können Sie die Leistung steigern, indem Sie mehrere Unteranfragen in einem einzigen Aufruf an den Server zusammenfassen und eine einzelne Antwort abrufen.

Wir empfehlen unseren Nutzern, mehrere Anfragen immer zusammenzufassen. Hier sind einige Beispiele für Situationen, in denen Sie Batching verwenden können:

• Sie verwenden die API gerade erst und haben eine große Menge an Daten.
• Sie müssen Metadaten oder Eigenschaften, z. B. die Formatierung, für mehrere Objekte aktualisieren.
• Sie müssen viele Objekte löschen.

Überlegungen zu Limits, Autorisierungen und Abhängigkeiten

Bei der Batch-Aktualisierung sollten Sie außerdem folgende Punkte berücksichtigen:

• Jede Batchanfrage einschließlich aller Unteranfragen wird als eine API-Anfrage im Hinblick auf das Nutzungslimit gezählt.
• Eine Batchanfrage wird einmal authentifiziert. Diese einzelne Authentifizierung gilt für alle Batch-Update-Objekte in der Anfrage.
• Der Server verarbeitet die Unteranfragen in der Reihenfolge, in der sie in der Batchanfrage aufgeführt sind. 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 diesen dann formatieren.

Batchdetails

Eine Batchanfrage besteht aus einem batchUpdate-Methodenaufruf mit mehreren Unteranfragen, mit denen beispielsweise ein Dokument hinzugefügt und dann formatiert wird.

Jede Anfrage wird validiert, bevor sie angewendet wird. Alle Unteranfragen im Batch-Update werden atomar angewendet. Wenn also eine Anfrage ungültig ist, ist die gesamte Aktualisierung fehlgeschlagen und es werden keine (möglicherweise abhängigen) Änderungen angewendet.

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

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 mit mehreren verschachtelten Unteranfragen mit einem erforderlichen Attribut: requests. Die Anfragen werden in einem Array einzelner Anfragen erstellt. Jede Anfrage verwendet JSON, um das Anfrageobjekt darzustellen und seine Attribute zu enthalten.

Format einer Batchantwort

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

Die Eigenschaft des Haupt-JSON-Objekts heißt replies. Die Antworten werden in einem Array zurückgegeben, wobei jede Antwort auf eine der Anfragen dieselbe Indexreihenfolge wie die entsprechende Anfrage hat. Einige Anfragen haben keine Antworten und die Antwort bei diesem Array-Index ist leer.

Beispiel

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

Anfragen

Dieses Beispiel für eine Batchanfrage zeigt:

• Fügen Sie den Text „Hello World“ am Anfang eines vorhandenen Dokuments mit dem Index Location ein. Verwenden Sie dazu den InsertTextRequest.
• Aktualisieren Sie das Wort „Hallo“ mit UpdateTextStyleRequest. startIndex und endIndex definieren die range des formatierten Texts im Segment.
• Legen Sie mithilfe von textStyle den Schriftstil fett und die Farbe auf Blau fest.

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

Antwort

Diese Beispiel-Batchantwort enthält Informationen dazu, wie jede Unteranfrage innerhalb der Batchanfrage angewendet wurde. Beachten Sie, dass sowohl InsertTextRequest als auch UpdateTextStyleRequest keine Antwort enthalten. Die Indexwerte des Arrays bei [0] und [1] bestehen also aus leeren geschweiften Klammern. In der Batchanfrage wird WriteControl angezeigt, das zeigt, wie die Schreibanfragen ausgeführt wurden.

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