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 Netzwerkumläufe reduziert und der Durchsatz erhöht werden kann.
Überblick
Jede Verbindung, die Ihr Client herstellt, führt zu einem bestimmten Aufwand. Die Google Sheets API unterstützt Batchanfragen, damit der Client mehrere Anfrageobjekte in einer einzelnen Batchanfrage platzieren kann. Jedes Objekt gibt dabei einen bestimmten Anfragetyp an. Bei einer Batchanfrage kann die Leistung gesteigert werden, indem mehrere Unteranfragen zu einem einzigen Aufruf an den Server kombiniert werden und eine einzelne Antwort zurückgeholt wird.
Wir empfehlen den Nutzern, mehrere Anfragen immer in einem Batch zusammenzufassen. Hier sind einige Beispiele für Situationen, in denen Sie Batching 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.
Überlegungen zu Limits, Autorisierungen und Abhängigkeiten
Hier ist eine Liste weiterer Punkte, die bei der Batch-Aktualisierung zu berücksichtigen sind:
- Jede Batchanfrage, einschließlich aller Unteranfragen, wird als eine API-Anfrage auf Ihr Nutzungslimit angerechnet.
- Eine Batchanfrage wird einmal authentifiziert. Diese Authentifizierung gilt für alle Batch-Aktualisierungsobjekte in der Anfrage.
- Der Server verarbeitet die Unteranfragen in der gleichen Reihenfolge, in der sie in der Batchanfrage vorkommen. Letzte Unteranfragen können von Aktionen abhängen, die bei 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 batchUpdate-Methodenaufruf mit mehreren Unteranfragen, um beispielsweise eine Tabelle hinzuzufügen und zu formatieren.
Jede Anfrage wird überprüft, bevor sie angewendet wird. Alle Unteranfragen in der Batch-Aktualisierung 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. Beispielsweise geben alle Batch-Aktualisierungsanfragen zum Hinzufügen von Objekten 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 ganzes Google-Dokument erstellen, indem Sie eine API-Batch-Aktualisierungsanfrage mit mehreren Unteranfragen verwenden.
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. In jeder Anfrage wird JSON verwendet, um das Anfrageobjekt darzustellen und seine Eigenschaften 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.
Die Eigenschaft 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 die entsprechende Anfrage liegt. Einige Anfragen enthalten keine Antworten und die Antwort bei diesem Arrayindex ist leer.
Beispiel
Das folgende Beispiel zeigt die Verwendung der Batchverarbeitung mit der Sheets API.
Anfragen
Diese beispielhafte Batchanfrage zeigt, wie Sie:
- Fügen Sie einer vorhandenen Tabelle ein Tabellenblatt mit einer
sheetIdvon 12345 hinzu. Verwenden Sie dazu dieAddSheetRequest. - Fügen Sie dem neuen Tabellenblatt Daten hinzu. Beginnen Sie mit Zelle A1 und verwenden Sie den
UpdateCellsRequest. - Fügen Sie dem neuen Tabellenblatt eine
namedRangeoder eine Filteransicht hinzu.
Durch das Hinzufügen der Tabellen-ID in der Anfrage können Nutzer die Tabellen-ID für andere Unteranfragen im selben API-Aufruf verwenden. Dies verbessert die Leistung, da ein Schreib-Lese-Schreib-Zyklus vermieden wird.
Eine Liste der Anfragetypen für Batch-Updates nach verschiedenen Kategorien finden Sie in der Tabelle unter Batch-Update-Vorgä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
Diese beispielhafte Batchantwort enthält Informationen darüber, wie jede Unteranfrage innerhalb der Batchanfrage angewendet wurde. Beachten Sie, dass UpdateCellsRequest keine Antwort enthält, sodass der Indexwert des Arrays bei [1] aus leeren geschweiften Klammern besteht.
"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
}
}
}
}
]