Tabellenkalkulationen können aus mehreren Tabellenblättern bestehen, wobei jedes Blatt eine beliebige Anzahl von Zeilen hat.
oder Spalten. Eine Zelle ist die Position im
einer bestimmten Zeile und Spalte
und kann einen Datenwert enthalten. Die
Die Google Sheets API bietet
spreadsheets.values
Ressource, um das Lesen und Schreiben von Werten zu ermöglichen.
Auf dieser Seite werden die Grundlagen zur Verwendung der Ressource spreadsheets.values
beschrieben. Wenn
müssen Sie Zeilen einfügen oder die Formatierung und andere Eigenschaften
müssen Sie die Methode
spreadsheets.batchUpdate
beschrieben, wie unter Tabellen aktualisieren beschrieben.
Methoden
Die Ressource spreadsheets.values
bietet die folgenden Methoden zum Lesen und Schreiben von Werten, jeweils für einen
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 Updates mit dem
batchGet
- bzw. batchUpdate
-Methoden, da sich dadurch
Effizienz.
Beispiele für diese Methoden finden Sie auf der Seite Basic Lesematerialien und Grundlagen zum Schreiben von Beispielseiten. Alle Beispiele finden Sie unter zur Übersichtsseite für Beispiele.
Lesen
Um Datenwerte aus einem Blatt zu lesen, benötigen Sie die Tabellen-ID und die Spalte A1
für den Bereich. Bereich ohne Tabellenblatt-ID angeben (A1:B2
)
bedeutet, dass die Anfrage auf dem ersten Tabellenblatt der Tabelle ausgeführt wird. Weitere Informationen
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 die valueRenderOption
ist nicht FORMATTED_VALUE
.
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. Für Beispiele von grundlegenden lesen, siehe Grundlegendes Lesen.
Einzelnen Bereich lesen
Um einen einzelnen Wertebereich aus einer Tabellenkalkulation zu lesen, 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 enthält.
Mehrere Bereiche lesen
Um mehrere nicht zusammenhängende Wertebereiche aus einer Tabellenkalkulation zu lesen, verwenden Sie eine
spreadsheets.values.batchGet
-Anforderung, 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
, das spreadsheetId
und eine Liste von
ValueRange
Objekte.
Schreiben
Um in ein Tabellenblatt zu schreiben, benötigen Sie die Tabellen-ID, den Zellenbereich in A1 und die Daten, die Sie schreiben möchten, in einen geeigneten Anfragetext -Objekt enthält. Weitere Informationen zu Tabellen-IDs und zur A1-Schreibweise finden Sie unter Google Sheets API – Übersicht
Aktualisierungen erfordern eine gültige
ValueInputOption
-Parameter.
Bei einzelnen Aktualisierungen ist dies ein erforderlicher Suchparameter. Bei Batch-Updates
Dieser Parameter ist im Anfragetext erforderlich. Die ValueInputOption
-Steuerelemente
wie Eingabedaten interpretiert werden sollten
und ob Eingabestrings geparst oder
nicht, wie in der folgenden Tabelle beschrieben:
ValueInputOption |
Beschreibung |
---|---|
RAW |
Die Eingabe wird nicht geparst und als String eingefügt. Beispiel: Die Eingabe „=1+2“ setzt den String, 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 würde sie in die Benutzeroberfläche von Google Tabellen eingegeben. Beispiel: „1. März 2016“ wird zu einem Datum und „=1+2“ wird eine Formel. Formate lassen sich auch ableiten, also „100,15 €“ wird zu einer Zahl mit Währungsformatierung. |
Die Methoden für die Singular- und die Batch-Aktualisierung werden unten beschrieben. Für Beispiele von grundlegenden Schreibvorgänge, siehe Grundlegende Schreibvorgänge.
In einen einzelnen Bereich schreiben
Um Daten in einen einzelnen Bereich zu schreiben, verwenden Sie eine
spreadsheets.values.update
Anfrage:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Der Text der Aktualisierungsanfrage muss ein
ValueRange
-Objekt enthält, obwohl das einzige Pflichtfeld values
ist. Wenn range
angegeben ist, gilt Folgendes:
muss mit dem Bereich in der URL übereinstimmen. In der ValueRange
können Sie optional
sein
majorDimension
Standardmäßig wird ROWS
verwendet. Wenn COLUMNS
angegeben ist, ist jedes innere Array
in eine Spalte
anstatt in eine Zeile geschrieben.
Beim Aktualisieren werden Werte ohne Daten übersprungen. Verwenden Sie zum Löschen von Daten ein leeres Feld String ("").
Mehrere Bereiche schreiben
Wenn Sie mehrere nicht zusammenhängende Bereiche schreiben möchten, können Sie einen
spreadsheets.values.batchUpdate
Anfrage:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Der Text der Anfrage zur Batch-Aktualisierung muss ein
BatchUpdateValuesRequest
-Objekt, das eine ValueInputOption
und eine Liste mit
ValueRange
-Objekte (eines für jeden geschriebenen Bereich). Jedes ValueRange
-Objekt gibt seine eigenen
range
, majorDimension
und Eingabedaten.
Werte anhängen
Um Daten nach einer Datentabelle in einem Tabellenblatt anzufügen, verwenden Sie eine
spreadsheets.values.append
Anfrage:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Der Text der Aktualisierungsanfrage muss ein
ValueRange
-Objekt enthält, obwohl das einzige Pflichtfeld values
ist. Wenn range
angegeben ist, gilt Folgendes:
muss mit dem Bereich in der URL übereinstimmen. In der ValueRange
können Sie optional
sein
majorDimension
Standardmäßig wird ROWS
verwendet. Wenn COLUMNS
angegeben ist, ist jedes innere Array
in eine Spalte
anstatt in eine Zeile geschrieben.
Der Eingabebereich wird verwendet, um nach vorhandenen Daten und einer „Tabelle“ zu suchen innerhalb von
Bereich. Werte werden an die nächste Zeile der Tabelle angehängt, beginnend mit
in 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
. Angehängte Werte würden
beginnen bei B7
für alle folgenden range
-Eingaben:
Sheet1
, da hiermit alle Daten im Tabellenblatt untersucht und 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 es die TabelleA1:C2
enthält).A3:G10
, da die letzte Tabelle im Bereich die TabelleB4:D6
ist (obwohl Sie davor beginnen und danach enden).
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 festlegen, ob Sie vorhandene Daten nach einem
oder fügen Sie neue Zeilen für die neuen Daten ein. Standardmäßig werden Daten durch die Eingabe überschrieben
nach der Tabelle ein. Um die neuen Daten in neue Zeilen zu schreiben, verwenden Sie die Methode
InsertDataOption
und geben Sie insertDataOption=INSERT_ROWS
an.
Weitere Informationen zu Zellen- und Zeilenlimits in Google Tabellen finden Sie unter In Google Drive speicherbare Dateien