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 die Batchverarbeitung kann die Effizienz einer Anwendung verbessert werden, da die Anzahl der Netzwerkumläufe reduziert und der Durchsatz erhöht wird.

Übersicht

Jede Verbindung, die Ihr Client herstellt, führt zu einem bestimmten Overhead. Die Google Docs API unterstützt Stapelanfragen, damit der Client mehrere Anfrageobjekte in einer einzelnen Batchanfrage platzieren kann. Jedes Objekt gibt einen bestimmten Anfragetyp an. Eine Batchanfrage kann die Leistung steigern, indem mehrere Unteranfragen zu einem einzigen Aufruf an den Server kombiniert und eine einzelne Antwort abgerufen wird.

Wir empfehlen Nutzern, mehrere Anfragen immer 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.

Limits, Autorisierungen und Abhängigkeiten

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

• Jede Batchanfrage, einschließlich aller Unteranfragen, wird als eine API-Anfrage auf Ihr Nutzungslimit angerechnet.
• Eine Batchanfrage wird einmal authentifiziert. Diese eine Authentifizierung gilt für alle Batch-Aktualisierungsobjekte in der Anfrage.
• Der Server verarbeitet die Unteranfragen in derselben Reihenfolge, in der sie in der Batchanfrage aufgeführt sind. Spätere Unteranfragen können von den Aktionen abhängen, die in früheren Unteranfragen ausgeführt wurden. Beispielsweise können Nutzer in derselben Batchanfrage Text in ein vorhandenes Dokument einfügen und dann mit einem Stil versehen.

Batchdetails

Eine Batchanfrage besteht aus einem Aufruf der Methode batchUpdate mit mehreren Unteranfragen, um beispielsweise ein Dokument hinzuzufügen und zu formatieren.

Jede Anfrage wird validiert, bevor sie angewendet wird. Alle Unteranfragen im Batch-Update werden in kleinstmöglichen Schritten angewendet. Wenn also eine Anfrage ungültig ist, ist die gesamte Aktualisierung fehlgeschlagen und keine der (potenziell abhängigen) Änderungen wird angewendet.

Einige Anfragen enthalten Antworten mit Informationen zu den angewendeten Anfragen. Alle Batch-Aktualisierungsanfragen zum Hinzufügen von Objekten geben beispielsweise 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 gesamtes Google-Dokument mit einer 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. Bei jeder Anfrage wird JSON verwendet, um das Anfrageobjekt darzustellen und seine Attribute zu enthalten.

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 Hauptattribut des JSON-Objekts heißt replies. Die Antworten werden in einem Array zurückgegeben. Dabei hat jede Antwort auf eine der Anfragen dieselbe Indexreihenfolge wie die entsprechende Anfrage. Einige Anfragen enthalten keine Antworten und die Antwort an diesem Array-Index ist leer.

Beispiel

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

Anfragen

Dieses Beispiel einer Batchanfrage zeigt, wie Sie:

• Fügen Sie am Anfang eines vorhandenen Dokuments „Hello World“-Text mit dem Index Location von 1 mithilfe von InsertTextRequest ein.
• Aktualisieren Sie das Wort „Hello“ mithilfe von UpdateTextStyleRequest. startIndex und endIndex definieren die range des formatierten Textes innerhalb des Segments.
• Legen Sie mithilfe von textStyle die Schriftart auf 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

Dieses Beispiel für eine Batchantwort enthält Informationen darüber, wie jede Unteranfrage innerhalb der Batchanfrage angewendet wurde. Beachten Sie, dass sowohl InsertTextRequest als auch UpdateTextStyleRequest keine Antwort enthalten. Daher bestehen die Indexwerte des Arrays bei [0] und [1] aus leeren geschweiften Klammern. In der Batchanfrage wird das WriteControl-Element angezeigt, das anzeigt, wie die Schreibanfragen ausgeführt wurden.

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