In diesem Dokument werden die Grundlagen der Verwendung der Ressource spreadsheets.values beschrieben.
Tabellen können mehrere Tabellenblätter mit einer beliebigen Anzahl von Zeilen oder Spalten enthalten. Eine Zelle ist die 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.
Wenn Sie Zeilen einfügen oder die Formatierung und andere Eigenschaften in einem Tabellenblatt aktualisieren möchten, müssen Sie die Methode batchUpdate der Ressource spreadsheets verwenden, wie unter Tabellen aktualisieren beschrieben.
Ressourcenmethoden
Die spreadsheets.values-Ressource bietet die folgenden Methoden zum Lesen und Schreiben von Werten, jeweils für eine bestimmte Aufgabe:
| Zugriff auf 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 steigert.
Codebeispiele für jede dieser Methoden finden Sie auf den Seiten mit Beispielen für einfaches Lesen und einfaches Schreiben. Alle Codebeispiele finden Sie auf der Übersichtsseite mit Beispielen.
Zellenwerte lesen
Wenn Sie Datenwerte aus einem Tabellenblatt lesen möchten, 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 in der Google Sheets API-Übersicht.
Mehrere optionale Abfrageparameter steuern das Format der Ausgabe:
| Format parameter | 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 in den folgenden Abschnitten beschrieben. Weitere Codebeispiele für grundlegende Lesevorgänge finden Sie unter Grundlegendes Lesen.
Werte aus einem 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, das Teil der spreadsheets.values-Ressource ist.
Werte aus mehreren Bereichen 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.
Zellenwerte schreiben
Wenn Sie Daten in ein Tabellenblatt schreiben möchten, benötigen Sie die Tabellenblatt-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.
Mehrere Abfrageparameter steuern, wie Daten geschrieben und wie die Antwort formatiert wird:
| Schreibparameter | Standardwert |
|---|---|
valueInputOption |
(Erforderlich) |
includeValuesInResponse |
false |
responseValueRenderOption |
FORMATTED_VALUE |
responseDateTimeRenderOption |
SERIAL_NUMBER |
Der erforderliche Parameter valueInputOption steuert, wie die Eingabedaten interpretiert werden sollen. Bei Batch-Updates wird dieser Parameter stattdessen im Anfragetext angegeben. Die unterstützten Optionen werden 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-String-Werte wie boolesche Werte oder Zahlen werden immer als RAW behandelt. |
USER_ENTERED |
Die Eingabe wird genau so geparst, als ob sie in der Google Sheets-Benutzeroberfläche eingegeben worden wäre. Beispiel: „1. März 2016“ wird zu einem Datum und „=1+2“ zu einer Formel. Formate können auch abgeleitet werden. So wird aus „$100.15“ eine Zahl mit Währungsformatierung. |
responseDateTimeRenderOption sollte nur verwendet werden, wenn responseValueRenderOption nicht FORMATTED_VALUE ist.
Die Methoden für Einzel- und Batch-Aktualisierungen werden in den folgenden Abschnitten beschrieben. Weitere Codebeispiele für grundlegende Schreibvorgänge finden Sie unter Grundlegendes Schreiben.
Werte 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. Wenn Sie Daten löschen möchten, verwenden Sie einen leeren String (""). Sie können auch Werte aus mehreren Bereichen löschen, ohne sie zu ersetzen, indem Sie die Methode spreadsheets.values.batchClear verwenden.
Wenn Sie Entwicklermetadaten verwenden, finden Sie in der Anleitung zu Entwicklermetadaten Informationen zum Lesen, Aktualisieren oder Löschen von Werten mit den Methoden spreadsheets.values.batchGetByDataFilter, spreadsheets.values.batchUpdateByDataFilter und spreadsheets.values.batchClearByDataFilter mithilfe von Datenfiltern.
Werte in 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:D6die letzte Tabelle ist.B4oderC5:D5, da beide in der TabelleB4:D6enthalten sind.B2:D4, da die letzte Tabelle im Bereich die TabelleB4:D6ist (obwohl sie auch die TabelleA1:C2enthält).A3:G10, da die letzte Tabelle im Bereich die TabelleB4:D6ist (obwohl sie davor beginnt und danach endet).
Bei den folgenden range-Eingaben wird nicht ab B7 geschrieben:
A1würde mit dem Schreiben beiA3beginnen, da sich dieser Wert in der TabelleA1:C2befindet.E4würde mit dem Schreiben beiE4beginnen, da es sich nicht in einer Tabelle befindet. (A4würde aus denselben Gründen auch mitA4beginnen.)
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.