Tabellen können mehrere Tabellenblätter mit einer beliebigen Anzahl von Zeilen oder Spalten enthalten. Eine Zelle ist eine Position an der Schnittstelle zwischen einer bestimmten Zeile und Spalte und kann einen Datenwert enthalten. Die Google Sheets API bietet die spreadsheets.values
-Ressource zum Lesen und Schreiben von Werten.
Auf dieser Seite werden die Grundlagen der Verwendung der spreadsheets.values
-Ressource beschrieben. Wenn Sie Zeilen einfügen oder die Formatierung und andere Attribute in einem Tabellenblatt aktualisieren müssen, müssen Sie die Methode spreadsheets.batchUpdate
verwenden, die unter Tabellen aktualisieren beschrieben wird.
Methoden
Die spreadsheets.values
-Ressource bietet die folgenden Methoden zum Lesen und Schreiben von Werten, jeweils für eine bestimmte Aufgabe:
Zugriff auf den Bereich | Lesen | Schreiben |
---|---|---|
Einzelner Bereich | spreadsheets.values.get |
spreadsheets.values.update |
Mehrere Bereiche | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Anfügen | spreadsheets.values.append |
Im Allgemeinen ist es empfehlenswert, mehrere Lese- oder Aktualisierungsvorgänge mit den Methoden batchGet
bzw. batchUpdate
zu kombinieren, da dies die Effizienz verbessert.
Beispiele für jede dieser Methoden finden Sie auf den Seiten Einfaches Lesen und Einfaches Schreiben. Eine Übersicht über alle Beispiele finden Sie auf der Beispielübersichtsseite.
Lesen
Um Datenwerte aus einem Tabellenblatt zu lesen, benötigen Sie die Tabellen-ID und die A1-Notation für den Bereich. Wenn Sie den Bereich ohne die Tabellenblatt-ID (A1:B2
) angeben, wird die Anfrage für das erste Tabellenblatt der Tabelle ausgeführt. Weitere Informationen zu Tabellen-IDs und A1-Notation finden Sie unter Google Sheets API – Übersicht.
Mehrere optionale Abfrageparameter steuern das Format der Ausgabe:
Parameter für das Format | Standardwert |
---|---|
majorDimension |
ROWS |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
dateTimeRenderOption
sollten Sie nur verwenden, wenn valueRenderOption
nicht FORMATTED_VALUE
ist.
Es gibt kein explizites Limit für die Menge der zurückgegebenen Daten. Bei Fehlern werden keine Daten zurückgegeben. Leere nachfolgende Zeilen und Spalten werden ausgelassen.
Die Methoden zum Abrufen einzelner und mehrerer Ressourcen werden unten beschrieben. Beispiele für einfache Lesevorgänge finden Sie unter Einfaches Lesen.
Einzelnen Bereich lesen
Wenn Sie einen einzelnen Wertebereich aus einer Tabelle lesen möchten, verwenden Sie eine spreadsheets.values.get
-Anfrage:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Die Antwort auf diese Anfrage wird als ValueRange
-Objekt zurückgegeben.
Mehrere Bereiche lesen
Wenn Sie mehrere nicht zusammenhängende Wertebereiche aus einer Tabelle lesen möchten, verwenden Sie eine spreadsheets.values.batchGet
-Anfrage, mit der Sie mehrere abzurufende Bereiche angeben können:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Die Antwort auf diese Anfrage wird als BatchGetValuesResponse
-Objekt zurückgegeben, das die spreadsheetId
und eine Liste von ValueRange
-Objekten enthält.
Schreiben
Wenn Sie Daten in ein Tabellenblatt schreiben möchten, benötigen Sie die Tabellen-ID, den Zellbereich in A1-Notation und die Daten, die Sie in ein entsprechendes Anfragetextobjekt schreiben möchten. Weitere Informationen zu Tabellen-IDs und A1-Notation finden Sie unter Google Sheets API – Übersicht.
Für Aktualisierungen ist ein gültiger Parameter ValueInputOption
erforderlich.
Für einzelne Aktualisierungen ist dies ein erforderlicher Abfrageparameter. Bei Batch-Aktualisierungen ist dieser Parameter im Anfragetext erforderlich. Mit ValueInputOption
wird gesteuert, wie Eingabedaten interpretiert werden sollen und ob Eingabestrings geparst werden, wie in der folgenden Tabelle beschrieben:
ValueInputOption |
Beschreibung |
---|---|
RAW |
Die Eingabe wird nicht geparst, sondern als String eingefügt. Wenn Sie beispielsweise „=1+2“ eingeben, wird der String „=1+2“ in die Zelle eingefügt, nicht die Formel. Nicht stringartige Werte wie boolesche Werte oder Zahlen werden immer als RAW behandelt. |
USER_ENTERED |
Die Eingabe wird genau so geparst, als wäre sie in der Sheets-Benutzeroberfläche eingegeben worden. Beispiel: „1. März 2016“ wird zu einem Datum und „=1+2“ zu einer Formel. Formate können auch abgeleitet werden. So wird „$100.15“ zu einer Zahl mit Währungsformatierung. |
Die Methoden für Einzel- und Batch-Updates werden unten beschrieben. Beispiele für einfache Schreibvorgänge finden Sie unter Einfaches Schreiben.
In einen einzelnen Bereich schreiben
Verwenden Sie eine spreadsheets.values.update
-Anfrage, um Daten in einen einzelnen Bereich zu schreiben:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Der Text der Aktualisierungsanfrage muss ein ValueRange
-Objekt sein. Das einzige erforderliche Feld ist values
. Wenn range
angegeben ist, muss es mit dem Bereich in der URL übereinstimmen. Im ValueRange
können Sie optional die majorDimension
angeben.
Standardmäßig wird ROWS
verwendet. Wenn COLUMNS
angegeben ist, wird jedes innere Array in eine Spalte anstelle einer Zeile geschrieben.
Beim Aktualisieren werden Werte ohne Daten übersprungen. Verwenden Sie einen leeren String („“), um Daten zu löschen.
Mehrere Bereiche schreiben
Wenn Sie mehrere nicht zusammenhängende Bereiche schreiben möchten, können Sie eine spreadsheets.values.batchUpdate
-Anfrage verwenden:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Der Text der Batch-Update-Anfrage muss ein BatchUpdateValuesRequest
-Objekt sein, das ein ValueInputOption
und eine Liste von ValueRange
-Objekten (eines für jeden geschriebenen Bereich) enthält. Jedes ValueRange
-Objekt gibt eigene range
-, majorDimension
- und Eingabedaten an.
Werte anhängen
Wenn Sie Daten nach einer Datentabelle in einem Tabellenblatt anhängen möchten, verwenden Sie eine spreadsheets.values.append
-Anfrage:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Der Text der Aktualisierungsanfrage muss ein ValueRange
-Objekt sein. Das einzige erforderliche Feld ist values
. Wenn range
angegeben ist, muss es mit dem Bereich in der URL übereinstimmen. Im ValueRange
können Sie optional die majorDimension
angeben.
Standardmäßig wird ROWS
verwendet. Wenn COLUMNS
angegeben ist, wird jedes innere Array in eine Spalte anstelle einer Zeile geschrieben.
Der Eingabebereich wird verwendet, um nach vorhandenen Daten zu suchen und eine „Tabelle“ in diesem Bereich zu finden. Die Werte werden an die nächste Zeile der Tabelle angehängt, beginnend mit der ersten Spalte der Tabelle. Nehmen wir beispielsweise an, Sheet1
sieht so aus:
A | B | C | D | E | |
1 | x | y | z | ||
2 | x | y | z | ||
3 | |||||
4 | x | y | |||
5 | y | z | |||
6 | x | y | z | ||
7 |
Das Tabellenblatt enthält zwei Tabellen: A1:C2
und B4:D6
. Angehängte Werte beginnen bei B7
für alle folgenden range
-Eingaben:
Sheet1
, da alle Daten im Tabellenblatt untersucht werden und festgestellt wird, dass die Tabelle unterB4:D6
die letzte Tabelle ist.B4
oderC5:D5
, da sich beide in der TabelleB4:D6
befinden.B2:D4
, da die letzte Tabelle im Bereich die TabelleB4:D6
ist (obwohl sie auch die TabelleA1:C2
enthält).A3:G10
, da die letzte Tabelle im Bereich die TabelleB4:D6
ist (obwohl sie davor beginnt und danach endet).
Bei den folgenden range
-Eingaben wird nicht bei B7
mit dem Schreiben begonnen:
A1
würde mit dem Schreiben beiA3
beginnen, da sich dieser Wert in der TabelleA1:C2
befindet.E4
würde mit dem Schreiben beiE4
beginnen, da es sich in keiner Tabelle befindet.A4
würde aus denselben Gründen auch mit dem Schreiben beiA4
beginnen.
Außerdem können Sie auswählen, ob vorhandene Daten nach dem Erstellen einer Tabelle überschrieben oder neue Zeilen für die neuen Daten eingefügt werden sollen. Standardmäßig werden Daten nach der Tabelle durch die Eingabe überschrieben. Wenn Sie die neuen Daten in neue Zeilen schreiben möchten, verwenden Sie InsertDataOption
und geben Sie insertDataOption=INSERT_ROWS
an.
Weitere Informationen zu Zellen- und Zeilenlimits in Google Sheets finden Sie unter In Google Drive speicherbare Dateien.