In diesem Dokument erfahren Sie, wie Sie API-Aufrufe in einem Batch zusammenfassen, um die Anzahl der Verbindungen zu reduzieren, die Ihr Client herstellen muss. Durch Batchverarbeitung kann die Effizienz einer Anwendung verbessert werden, da die Anzahl der Netzwerk-Roundtrips verringert und der Durchsatz erhöht wird.
Übersicht
Jede Verbindung, die der Client herstellt, führt zu einem bestimmten Overhead. Die Google Sheets API unterstützt Batchanfragen, damit Ihr Client mehrere Anfrageobjekte, die jeweils einen einzelnen auszuführenden Anfragetyp angeben, in einer einzelnen Batchanfrage zusammenfassen kann. Eine Batchanfrage kann die Leistung steigern, indem mehrere untergeordnete Anfragen in einem einzigen Aufruf an den Server kombiniert werden, der dann eine einzige Antwort zurückgibt.
Wir empfehlen Nutzern, immer mehrere Anfragen zusammenzufassen. 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.
Beschränkungen, Autorisierung und Abhängigkeiten
Hier finden Sie eine Liste mit weiteren Aspekten, die Sie bei der Batch-Aktualisierung berücksichtigen sollten:
- Jede Batchanfrage, einschließlich aller untergeordneten Anfragen, wird auf Ihr Nutzungskontingent als eine API-Anfrage angerechnet.
- Eine Batchanfrage wird nur einmal authentifiziert. Diese einmalige Authentifizierung gilt für alle Batch-Update-Objekte in der Anfrage.
- Der Server verarbeitet die untergeordneten Anfragen in derselben Reihenfolge, in der sie in der Batchanfrage aufgeführt sind. Letztere untergeordnete Anfragen können von Aktionen abhängen, die bei früheren untergeordneten Anfragen ausgeführt wurden. Nutzer können beispielsweise in derselben Batchanfrage Text in ein vorhandenes Dokument einfügen und ihn dann formatieren.
Batchdetails
Eine Batchanfrage besteht aus einem batchUpdate-Methodenaufruf mit mehreren untergeordneten Anfragen, um beispielsweise eine Tabelle hinzuzufügen und dann zu formatieren.
Jede Anfrage wird validiert, bevor sie angewendet wird. Alle untergeordneten Anfragen im Batch-Update werden in kleinstmöglichen Schritten angewendet. Wenn eine Anfrage ungültig ist, schlägt die gesamte Aktualisierung fehl und keine der (möglicherweise abhängigen) Änderungen wird angewendet.
Bei einigen Anfragen werden Antworten mit Informationen zu den angewendeten Anfragen zurückgegeben. Beispielsweise geben alle Batch-Update-Anfragen 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.
Mit diesem Ansatz können Sie ein ganzes Google-Dokument mit einer API-Batchaktualisierungsanfrage mit mehreren untergeordneten Anfragen 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 erstellt. In jeder Anfrage wird JSON verwendet, um das Anfrageobjekt und seine Attribute darzustellen.
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 denselben Index wie die entsprechende Anfrage. Einige Anfragen haben keine Antworten und die Antwort an diesem Arrayindex ist leer.
Beispiel
Das folgende Beispiel zeigt die Verwendung der Batchverarbeitung mit der Sheets API.
Anfrage
In dieser Beispiel-Batchanfrage wird Folgendes gezeigt:
- Fügen Sie einer vorhandenen Tabelle mit der
AddSheetRequestein Tabellenblatt mit dersheetId12345 hinzu. - Fügen Sie dem neuen Tabellenblatt Daten hinzu, beginnend mit Zelle A1, indem Sie
UpdateCellsRequestverwenden. - Fügen Sie dem neuen Tabellenblatt eine
namedRangeoder Filteransicht hinzu.
Wenn die Tabellenblatt-ID in die Anfrage aufgenommen wird, können Nutzer sie für andere untergeordnete Anfragen im selben API-Aufruf verwenden. Dadurch wird die Leistung verbessert, da ein Schreib-/Lese-/Schreibzyklus vermieden wird.
Eine Liste der Batchaktualisierungsanfragetypen, gruppiert in verschiedene Kategorien, finden Sie in der Tabelle unter Batchaktualisierungsvorgänge.
{
"requests":[
{
"addSheet":{
"properties":{
"sheetId":123456
}
}
},
{
"updateCells":{
"start":{
"sheetId":123456
},
"rows":[
{
"values":[
{
"userEnteredValue":{
"stringValue":"hello"
}
}
]
},
{
"values":[
{
"userEnteredValue":{
"stringValue":"world"
}
}
]
}
],
"fields":"userEnteredValue"
}
},
{
"addNamedRange":{
"namedRange":{
"name":"newRange",
"range":{
"sheetId":123456,
"endRowIndex":2
}
}
}
}
]
}Antwort
In dieser Beispiel-Batchantwort sehen Sie, wie die einzelnen untergeordneten Anfragen in der Batchanfrage angewendet wurden. Beachten Sie, dass UpdateCellsRequest keine Antwort enthält. Der Indexwert des Arrays bei [1] besteht daher aus leeren geschweiften Klammern.
"replies":[
{
"addSheet":{
"properties":{
"sheetId":123456,
"title":"Sheet3",
"index":2,
"sheetType":"GRID",
"gridProperties":{
"rowCount":1000,
"columnCount":26
}
}
}
},
{
},
{
"addNamedRange":{
"namedRange":{
"namedRangeId":"2104325079",
"name":"newRange",
"range":{
"sheetId":123456,
"startRowIndex":0,
"endRowIndex":2,
"startColumnIndex":0,
"endColumnIndex":26
}
}
}
}
]