Tabellenkalkulationen können aus mehreren Tabellenblättern bestehen, wobei jedes Tabellenblatt eine beliebige Anzahl von Zeilen oder Spalten haben kann. Eine Zelle ist eine Stelle an der Kreuzung einer bestimmten Zeile und Spalte. Sie kann einen Datenwert enthalten. Die Google Sheets API bietet die Ressource spreadsheets.values
, mit der Werte gelesen und geschrieben werden können.
Auf dieser Seite werden die Grundlagen zur Verwendung der Ressource spreadsheets.values
beschrieben. Wenn Sie in einem Tabellenblatt Zeilen einfügen oder die Formatierung und andere Eigenschaften aktualisieren müssen, müssen Sie die unter Tabellen aktualisieren beschriebene Methode spreadsheets.batchUpdate
verwenden.
Methoden
Die Ressource spreadsheets.values
bietet die folgenden Methoden zum Lesen und Schreiben von Werten, jeweils für eine bestimmte Aufgabe:
Bereichszugriff | Leseliste | Schreiben |
---|---|---|
Einzelner Bereich | spreadsheets.values.get |
spreadsheets.values.update |
Mehrere Bereiche | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Anfügen | spreadsheets.values.append |
Im Allgemeinen empfiehlt es sich, mehrere Lesevorgänge oder Aktualisierungen mit den Methoden batchGet
und batchUpdate
zu kombinieren, da dies die Effizienz verbessert.
Beispiele für diese Methoden finden Sie auf den Beispielseiten Grundlegende Lesematerialien und Grundlegendes Schreiben. Alle Beispiele finden Sie auf der Übersichtsseite für Beispiele.
Lesen
Zum Lesen von Datenwerten aus einem Tabellenblatt benötigen Sie die Tabellen-ID und die A1-Notation für den Bereich. Wenn Sie einen 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 zur A1-Notation finden Sie unter Google Sheets API – Übersicht.
Das Format der Ausgabe wird über mehrere optionale Suchparameter gesteuert:
Formatparameter | Standardwert |
---|---|
majorDimension |
ROWS |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
Sie sollten dateTimeRenderOption
nur verwenden, wenn valueRenderOption
nicht FORMATTED_VALUE
ist.
Es gibt keine explizite Begrenzung für die Menge der zurückgegebenen Daten. Bei Fehlern werden keine Daten zurückgegeben. Leere nachgestellte Zeilen und Spalten werden weggelassen.
Die get-Methoden für Singular und Batch werden nachfolgend beschrieben. Beispiele für grundlegende Lesevorgänge finden Sie unter Grundlegende Lesematerialien.
Einzelnen Bereich lesen
Verwenden Sie eine spreadsheets.values.get
-Anfrage, um einen einzelnen Wertebereich aus einer Tabelle zu lesen:
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
Zum Schreiben in ein Tabellenblatt benötigen Sie die Tabellen-ID, den Zellenbereich in A1-Notation und die Daten, die in ein entsprechendes Anfragetextobjekt geschrieben werden sollen. Weitere Informationen zu Tabellen-IDs und zur A1-Schreibweise finden Sie unter Google Sheets API – Übersicht.
Für Aktualisierungen ist ein gültiger ValueInputOption
-Parameter erforderlich.
Bei einzelnen Aktualisierungen ist dies ein erforderlicher Suchparameter. Bei Batchaktualisierungen ist dieser Parameter im Anfragetext erforderlich. ValueInputOption
steuert, wie Eingabedaten interpretiert werden sollen und ob Eingabestrings geparst werden oder nicht, wie in der folgenden Tabelle beschrieben:
ValueInputOption |
Beschreibung |
---|---|
RAW |
Die Eingabe wird nicht geparst und als String eingefügt. Wenn Sie beispielsweise „=1+2“ eingeben, wird der String, nicht die Formel, in die Zelle eingefügt. Werte, die keine Strings sind, wie boolesche Werte oder Zahlen, werden immer als RAW behandelt. |
USER_ENTERED |
Die Eingabe wird genau so geparst, als würde sie in die Benutzeroberfläche von Google Tabellen eingegeben. So wird beispielsweise „1. März 2016“ zu einem Datum und „=1+2“ zu einer Formel. Formate können auch abgeleitet werden, sodass „100,15 €“ zu einer Zahl mit Währungsformatierung wird. |
Die Methoden für die Singular- und die Batch-Aktualisierung werden unten beschrieben. Beispiele für grundlegende Schreibvorgänge finden Sie unter Grundlegendes 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 Pflichtfeld ist jedoch values
. Wenn range
angegeben ist, muss er mit dem Bereich in der URL übereinstimmen. Im ValueRange
können Sie optional dessen majorDimension
angeben.
Standardmäßig wird ROWS
verwendet. Wenn COLUMNS
angegeben ist, wird jedes innere Array in eine Spalte statt in eine Zeile geschrieben.
Beim Aktualisieren werden Werte ohne Daten übersprungen. Verwenden Sie zum Löschen von Daten einen leeren String ("").
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-Aktualisierungsanfrage 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 seine eigenen range
-, majorDimension
- und Eingabedaten an.
Werte anhängen
Verwenden Sie eine spreadsheets.values.append
-Anfrage, um Daten nach einer Datentabelle in einem Tabellenblatt anzufügen:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Der Text der Aktualisierungsanfrage muss ein ValueRange
-Objekt sein. Das einzige Pflichtfeld ist jedoch values
. Wenn range
angegeben ist, muss er mit dem Bereich in der URL übereinstimmen. Im ValueRange
können Sie optional dessen majorDimension
angeben.
Standardmäßig wird ROWS
verwendet. Wenn COLUMNS
angegeben ist, wird jedes innere Array in eine Spalte statt in eine Zeile geschrieben.
Der Eingabebereich wird verwendet, um nach vorhandenen Daten und einer „Tabelle“ innerhalb dieses Bereichs zu suchen. Werte werden an die nächste Zeile der Tabelle angehängt, beginnend mit der ersten Spalte der Tabelle. Ein Sheet1
sieht zum Beispiel 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
. Die angehängten Werte beginnen für alle folgenden range
-Eingaben bei B7
:
Sheet1
, da alle Daten im Tabellenblatt untersucht und festgestellt werden, dass die Tabelle unterB4:D6
die letzte Tabelle ist.B4
oderC5:D5
, da sie 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 (auch wenn sie davor beginnt und danach endet).
Die folgenden range
-Eingaben würden nicht ab B7
schreiben:
A1
beginnt beiA3
zu schreiben, weil dies in der TabelleA1:C2
ist.E4
beginnt beiE4
mit dem Schreiben, weil er zu keiner Tabelle gehört.A4
würde aus denselben Gründen auch abA4
schreiben.
Außerdem können Sie auswählen, ob Sie vorhandene Daten nach einer Tabelle überschreiben oder neue Zeilen für die neuen Daten einfügen möchten. Standardmäßig überschreibt die Eingabe Daten nach der Tabelle. Verwenden Sie InsertDataOption
und geben Sie insertDataOption=INSERT_ROWS
an, um die neuen Daten in neue Zeilen zu schreiben.
Weitere Informationen zu Zellen- und Zeilenlimits in Google Tabellen finden Sie unter In Google Drive speicherbare Dateien.