Batchanfragen

In diesem Dokument wird gezeigt, wie API-Aufrufe in einem Batch zusammengefasst werden, um die Anzahl der die der Client herstellen muss. Batching kann die durch Reduzierung der Netzwerkumläufe und erhöhten Durchsatz.

Übersicht

Jede Verbindung, die Ihr Client herstellt, führt zu einem bestimmten Overhead. Die Google Docs API unterstützt die Batchverarbeitung, damit Ihr Client mehrere Anforderungsobjekte, die jeweils einen einzelnen Typ von auszuführender Anforderung definieren, in einer einzelnen Batch-Anfrage zusammenfassen. Mit einer Batchanfrage kann die Leistung gesteigert werden, mehrere Teilanfragen zu einem einzigen Aufruf an den Server kombinieren, mit nur einer Antwort.

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

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

Limits, Autorisierung und Überlegungen zu Abhängigkeiten

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

  • Jede Batchanfrage, einschließlich aller Unteranfragen, wird als eine API gezählt. , um Ihr Nutzungslimit zu erhöhen.
  • Eine Batchanfrage wird nur einmal authentifiziert. Diese einzelne Authentifizierung zu allen Batch-Update-Objekten in der Anfrage.
  • Der Server verarbeitet die Teilanfragen in der Reihenfolge, in der sie im Batch-Anfrage. Letztere Teilanfragen können von Aktionen abhängig sein, die während früheren Unteranfragen. In derselben Batchanfrage können Nutzer beispielsweise Text in ein vorhandenes Dokument einfügen und ihn dann mit einem Stil versehen.

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 überprüft, bevor sie angewendet wird. Alle Teilanfragen im Batch Aktualisierung atomar angewendet. Das heißt, wenn eine Anfrage ungültig ist, Das gesamte Update ist fehlgeschlagen und keiner der (möglicherweise abhängigen) Änderungen angewendet werden.

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

Mit diesem Ansatz können Sie ein komplettes Google-Dokument über nur eine API erstellen. Batch-Update-Anfrage mit mehreren Unteranfragen.

Format einer Batchanfrage

Eine Anfrage ist eine einzelne JSON-Anfrage mit mehreren, verschachtelte Unteranfragen mit einer erforderlichen Property: requests. Die Anfragen werden in einem Array von einzelnen Anfragen erstellt. Bei jeder Anfrage wird JSON zur Darstellung des Anfrageobjekts und seiner Attribute.

Format einer Batchantwort

Das response-Format für eine Batchanfrage ähnelt dem Anfrageformat. Die Antwort des Servers enthält eine vollständige Antwort der Single -Antwortobjekt.

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 in der entsprechenden Anfrage. Einige Anfragen enthalten nicht und die Antwort bei diesem Array-Index leer ist.

Beispiel

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

Anfrage

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

  • Fügen Sie „Hello World“ ein Text an den Anfang eines vorhandenen Dokuments einfügen, wobei Index location von 1, unter Verwendung des InsertTextRequest

  • Das Wort „Hallo“ aktualisieren mithilfe der UpdateTextStyleRequest startIndex und endIndex definieren die range von formatiertem Text in auf das Segment ausgerichtet ist.

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

  • WriteControl verwenden können Sie steuern, wie Schreibanfragen ausgeführt werden. Weitere Informationen erhalten Sie unter Konsistenz zwischen Status und WriteControl.

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

TAB_ID und REQUIRED_REVISION_ID ersetzen durch Die Tab-ID bzw. die Versions-ID des Dokuments, auf das sich die Schreibanfrage bezieht angewendet wird.

Antwort

Diese Beispiel-Batchantwort zeigt Informationen darüber an, wie jede Teilanfrage innerhalb die Batchanfrage angewendet wurde. Weder die InsertTextRequest oder die UpdateTextStyleRequest eine Antwort enthalten, sodass die Indexwerte des Arrays bei [0] und [1] bestehen geschweiften Klammern leer. In der Batchanfrage wird das Objekt WriteControl angezeigt. wie die Anfragen ausgeführt wurden.

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