Tabellen können aus mehreren Blättern bestehen, wobei jedes Blatt eine beliebige Anzahl von Zeilen oder Spalten hat. Eine Zelle ist eine Stelle an der Kreuzung einer bestimmten Zeile und Spalte und kann einen Datenwert enthalten. Die Google Sheets API bietet die Ressource spreadsheets.values
, um das Lesen und Schreiben von Werten zu ermöglichen.
Auf dieser Seite werden die Grundlagen der Verwendung der Ressource spreadsheets.values
beschrieben. Wenn Sie Zeilen einfügen oder die Formatierung und andere Eigenschaften in einem Tabellenblatt aktualisieren möchten, müssen Sie die Methode spreadsheets.batchUpdate
verwenden, die unter Tabellen aktualisieren beschrieben wird.
Methoden
Die Ressource spreadsheets.values
bietet die folgenden Methoden zum Lesen und Schreiben von Werten, jeweils für eine bestimmte Aufgabe:
Bereichszugriff | 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 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 Seite Beispiele – Übersicht.
Lesen
Zum Lesen von Datenwerten aus einem Tabellenblatt 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 zur A1-Notation finden Sie unter Übersicht über die Google Sheets API.
Mehrere optionale Abfrageparameter steuern das Format der Ausgabe:
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 Beschränkung für die zurückgegebene Datenmenge. Bei Fehlern werden keine Daten zurückgegeben. Leere nachgestellte Zeilen und Spalten werden ausgelassen.
Die Singular- und Batch-Abrufmethoden werden unten beschrieben. Beispiele für grundlegende Lesevorgänge finden Sie unter Grundlegende Lesevorgänge.
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:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Die Antwort auf diese Anfrage wird als BatchGetValuesResponse
-Objekt zurückgegeben, das 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 Sie in ein entsprechendes Anfragetextobjekt schreiben möchten. Weitere Informationen zu Tabellen-IDs und zur A1-Notation finden Sie unter Übersicht über die Google Sheets API.
Für Aktualisierungen ist ein gültiger Parameter ValueInputOption
erforderlich.
Bei einzelnen Aktualisierungen ist dies ein erforderlicher Suchparameter. Bei Batch-Updates ist dieser Parameter im Anfragetext erforderlich. Mit ValueInputOption
wird festgelegt, wie Eingabedaten interpretiert werden 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. Die Eingabe „=1+2“ fügt beispielsweise die Zeichenfolge und nicht die Formel „=1+2“ in die Zelle ein. Werte, die keine Strings sind, wie boolesche Werte oder Zahlen, werden immer als RAW behandelt. |
USER_ENTERED |
Die Eingabe wird genau so geparst, als ob sie in die Google Tabellen-Benutzeroberfläche eingegeben worden wäre. 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ährungsformat wird. |
Die Methoden für die Singular- und die Batch-Aktualisierung werden unten beschrieben. Beispiele für einfache 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 values
. Wenn range
angegeben ist, muss dies mit dem Bereich in der URL übereinstimmen. In der ValueRange
können Sie optional die 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
-Objekt und eine Liste von ValueRange
-Objekten (eines für jeden geschriebenen Bereich) enthält. Jedes ValueRange
-Objekt gibt seine eigenen range
- und majorDimension
-Werte sowie Eingabedaten an.
Werte anhängen
Um Daten nach einer Datentabelle in einem Tabellenblatt anzuhängen, 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 Pflichtfeld ist values
. Wenn range
angegeben ist, muss dies mit dem Bereich in der URL übereinstimmen. In der ValueRange
können Sie optional die 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. Die Werte werden an die nächste Zeile der Tabelle angehängt, beginnend mit der ersten Spalte der Tabelle. Sehen Sie sich beispielsweise Sheet1
an, das so aussieht:
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 für alle folgenden range
-Eingaben bei B7
:
Sheet1
, da sie alle Daten im Tabellenblatt prüft und ermittelt, dass die Tabelle unterB4:D6
die letzte Tabelle ist.B4
oderC5:D5
, weil beide in der Tabelle „B4:D6
“ enthalten sind.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 beginnen nicht bei B7
zu schreiben:
A1
würde umA3
schreiben, weil dieser Wert in der TabelleA1:C2
enthalten ist.E4
würde mit dem Schreiben beiE4
beginnen, da es sich in keiner Tabelle befindet. (Aus den gleichen Gründen würde auchA4
beiA4
schreiben.)
Außerdem können Sie festlegen, ob Sie vorhandene Daten nach einer Tabelle überschreiben oder neue Zeilen für die neuen Daten einfügen möchten. Standardmäßig werden durch die Eingabe Daten nach der Tabelle überschrieben. Verwenden Sie den 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.