Wenn Sie bereits Apps haben, die auf der Google Sheets API v3 basieren, können Sie zu Google Sheets API v4 migrieren. Die Version 4 ist JSON-basiert, hat eine nutzerfreundlichere Oberfläche und bietet eine große Anzahl von Funktionen, die in der Version 3 nicht möglich sind.
Auf dieser Seite finden Sie eine Zuordnung zwischen den älteren Befehlen der Google Tabellen API v3 und den entsprechenden Vorgängen in der Google Tabellen API v4. Die Zuordnung konzentriert sich hauptsächlich auf die Sammlung spreadsheets.values, die direkte Lese- und Schreibfunktionen für Zellen bietet. Andere Aspekte wie das Hinzufügen von Tabellen oder das Aktualisieren von Tabelleneigenschaften werden von der Sammlung spreadsheets verarbeitet. Die JSON-Strukturen der API-Version 4 sind nicht abwärtskompatibel mit den XML-Strukturen, die in Version 3 verwendet werden.
Weitere Informationen zu den in der Google Tabellen API 4 verfügbaren Ressourcen finden Sie in der API-Referenz.
Notation und Begriffe
In der V3 API werden Tabellen innerhalb einer bestimmten Tabelle als „worksheets“ (Tabellenblätter) bezeichnet. Dies ist ein Synonym für den Begriff „Tabellen“, der in der V4 API verwendet wird.
Für die APIs müssen Sie häufig die Tabellen-ID der Tabelle angeben, mit der Sie arbeiten. Außerdem ist oft die ID des manipulierten Tabellenblatts erforderlich. Diese Werte werden entweder als Teil der API-Endpunkt-URL, als Abfrageparameter oder als Teil des Anfragetextes angezeigt. Auf dieser Seite beziehen sich die Platzhalter spreadsheetId und sheetId auf die Tabellen- und Tabellen-IDs. Wenn Sie die auf dieser Seite beschriebenen Methoden verwenden, ersetzen Sie an diesen Stellen die Platzhalter durch die tatsächlichen IDs.
Die v3 API weist Zeilen, die über den Listenfeed abgerufen werden, auch eine ID zu. Diese wird auf dieser Seite durch den Platzhalter rowId dargestellt.
Anfragen autorisieren
Wenn Ihre App ausgeführt wird, werden Nutzer aufgefordert, bestimmte Berechtigungen zu gewähren. Welche Berechtigungen angefordert werden, hängt von den Bereichen ab, die Sie in Ihrer App angeben.
v3 API
Für die Sheets API v3 gibt es nur einen Autorisierungsbereich:
https://spreadsheets.google.com/feeds
ein Alias für
https://www.googleapis.com/auth/spreadsheets
Es kann jedes Gültigkeitsbereichsformat verwendet werden.
v4 API
Für die Google Tabellen API 4 werden mindestens einer der folgenden Bereiche verwendet:
https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/drive
Verwenden Sie Lesezugriffsbereiche, wenn Ihre Anwendung keine Änderungen an den Tabellen oder Tabelleneigenschaften eines Nutzers vornehmen muss. Verwenden Sie Tabellenbereiche anstelle von Drive-Bereichen, wenn die Anwendung keinen allgemeinen Drive-Zugriff benötigt.
Sichtbarkeit
In älteren Versionen der API bezieht sich der Begriff Sichtbarkeit auf die Verfügbarkeit einer bestimmten Tabelle.
v3 API
Die Sichtbarkeit wird in der Sheets API v3 direkt in den Endpunkten angegeben. Eine public-Tabelle wurde „Im Web veröffentlicht“ und kann daher von der API ohne Autorisierung aufgerufen werden. Für eine private-Tabelle ist dagegen eine Authentifizierung erforderlich. Die Sichtbarkeit wird im Endpunkt nach der Tabellen-ID angegeben:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
v4 API
In der neuen Google Tabellen API 4 gibt es keine explizite Sichtbarkeitsdeklaration. API-Aufrufe werden mit Tabellen-IDs ausgeführt. Wenn die Anwendung keine Berechtigung zum Zugriff auf die angegebene Tabelle hat, wird ein Fehler zurückgegeben. Andernfalls wird der Anruf fortgesetzt.
Projektion
Der Begriff Projektion wird in der Google Tabellen API 3 für den Datensatz verwendet, der von einem bestimmten API-Aufruf zurückgegeben wird – entweder der gesamte Datensatz oder ein fester Teilsatz, der in der API definiert ist. Die Google Tabellen API 4 verwendet keine Projektion, sondern bietet Ihnen mehr Kontrolle darüber, welche Daten zurückgegeben werden.
v3 API
In der Google Tabellen API v3 gibt es nur zwei mögliche Projektionseinstellungen. Bei der full-Projektion werden alle verfügbaren Informationen zurückgegeben, während bei basic eine kleinere, feste Teilmenge der Daten zurückgegeben wird (für die Tabellenblätter, Listen und Zellenfeeds).
Wie bei der Sichtbarkeit muss die Projektion im API-Endpunkt angegeben werden (nach der Sichtbarkeitseinstellung):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
Die kleinere Datenmenge, die durch die basic-Projektion bereitgestellt wird, ist hilfreich, um den Code effizienter zu gestalten, kann aber nicht angepasst werden.
v4 API
Die Google Tabellen API 4 kann zwar einen vollständigen Datensatz zurückgeben, definiert aber keine festen Teilmengen analog zur Sichtbarkeitseinstellung basic der Google Tabellen API 3.
Methoden in der Sammlung Tabelle beschränken die zurückgegebene Datenmenge mithilfe des Abfrageparameters Felder.
Die folgende Abfrage gibt beispielsweise nur die Titel aller Tabellen in einer bestimmten Tabelle zurück:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Tabelle erstellen
v3 API
Die Sheets API v3 bietet keine Möglichkeit, neue Tabellen zu erstellen. Stattdessen kann die Methode Drive API Files.create verwendet werden, um neue Tabellendateien zu erstellen. Dazu muss die Anwendung den https://www.googleapis.com/auth/drive-Umfang angeben.
v4 API
Die Methode Drive API Files.create kann auch mit der Google Tabellen API v4 verwendet werden. Die Anwendung muss jedoch den Bereich https://www.googleapis.com/auth/drive angeben.
Als gleichwertige Alternative bietet die Sheets API v4 die Methode spreadsheets.create, mit der Sie optional auch Tabellen hinzufügen, die Tabellen- und Tabelleneigenschaften festlegen und benannte Bereiche hinzufügen können. Mit dem folgenden Befehl wird beispielsweise eine neue Tabelle mit dem Namen „NewTitle“ erstellt:
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Tabellen für den authentifizierten Nutzer auflisten
v3 API
Über den Feed der Sheets API v3 kann eine Anwendung eine Liste aller Tabellen abrufen, auf die der authentifizierte Nutzer zugreifen kann. Der Endpunkt des Tabellenfeeds lautet:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
v4 API
Dieser Vorgang ist in der Sheets API v4 nicht verfügbar. Wir empfehlen, Ihre App so zu migrieren, dass der Bereich „drive.file“ in Kombination mit der Google-Bildergalerie für die Tabellenauswahl verwendet wird.
Wenn Tabellen aufgelistet werden müssen, kann dies mithilfe der Methode Drive API Files.list und einer mimeType-Abfrage repliziert werden:
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'
Wenn Sie mit der Drive API-Methode „files.list“ alle Tabellen eines Nutzers auflisten möchten, ist ein eingeschränkter Umfang erforderlich.
Tabellenmetadaten abrufen
Die Sheets API v3 bietet einen Feed für den Zugriff auf die Tabellenmetadaten einer bestimmten Tabelle. Auf Zeilen- und Zellendaten wird über einen separaten Feed zugegriffen. Die Metadaten enthalten Informationen wie Tabellentitel und Größeninformationen.
Die Methode spreadsheets.get der Sheets API v4 bietet Zugriff auf diese und viele weitere Informationen.
v3 API
Der Tabellenfeed ist über diesen API-Endpunkt zugänglich (mit einem geeigneten Autorisierungsheader):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
Die Antwort auf diese Anfrage hat eine ähnliche Struktur. Die Daten der einzelnen Tabellen befinden sich in einer separaten <entry>:
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:gs="http://schemas.google.com/spreadsheets/2006"
xmlns:gd="http://schemas.google.com/g/2005"
gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Groceries R Us</title>
<link rel="alternate" type="text/html"
href="https://spreadsheets.google.com/ccc?key=spreadsheetId"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<author>
<name>Fitzwilliam Darcy</name>
<email>fitz@example.com</email>
</author>
<openSearch:totalResults>1</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>1</openSearch:itemsPerPage>
<entry gd:etag='"YDwqeyI."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Sheet1</title>
<content type="text">Sheet1</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>100</gs:rowCount>
<gs:colCount>20</gs:colCount>
</entry>
</feed>
v4 API
Mit der Methode spreadsheets.get können Tabelleneigenschaften und andere Metadaten abgerufen werden, was mit der Sheets API v3 nicht möglich ist. Wenn Sie nur die Tabelleneigenschaften lesen möchten, setzen Sie den Abfrageparameter includeGridData auf false, um das Einschließen der Tabellenzelldaten zu verhindern:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
Die Spreadsheet-Antwort enthält ein Array von Sheet-Objekten. Die Titel und Größeninformationen der Tabellen finden Sie im Element SheetProperties dieser Objekte. Beispiel:
{
"spreadsheetId": spreadsheetId,
"sheets": [
{"properties": {
"sheetId": sheetId,
"title": "Sheet1",
"index": 0,
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1,
"frozenColumnCount": 0,
"hideGridlines": false
},
...
},
...
},
...
],
...
}Tabellenblätter zu einer Tabelle hinzufügen
Mit beiden APIs können Sie einer vorhandenen Tabelle neue Blätter hinzufügen.
v3 API
Mit der Sheets API v3 können Sie einer Tabelle neue Tabellenblätter hinzufügen, indem Sie die folgende (authentifizierte) POST-Anfrage senden. Sie können die Größe des neuen Tabellenblatts so festlegen:
POST https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<title>Expenses</title>
<gs:rowCount>50</gs:rowCount>
<gs:colCount>10</gs:colCount>
</entry>
v4 API
Sie können neue Tabellen hinzufügen, indem Sie über die Methode spreadsheets.batchUpdate eine AddSheet-Anfrage stellen. Im Anfragetext können Sie die Tabellenblatteigenschaften für das neue Tabellenblatt angeben. Alle Eigenschaften sind optional. Es ist ein Fehler, einen Titel anzugeben, der für eine vorhandene Tabelle verwendet wird.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [{
"addSheet": {
"properties": {
"title": "Expenses",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 50,
"columnCount": 10
}
}
}
}],
}Titel und Größe eines Tabellenblatts ändern
Mit der Google Tabellen API v3 können Sie Tabellentitel und -größe aktualisieren. Das ist auch mit der Google Tabellen API v4 möglich. Mit dieser API können Sie aber auch andere Tabelleneigenschaften aktualisieren. Wenn Sie die Größe eines Tabellenblatts verkleinern, werden die Daten in den zugeschnittenen Zellen möglicherweise ohne Warnung gelöscht.
v3 API
Wenn Sie den Titel oder die Größe eines Tabellenblatts ändern möchten, rufen Sie zuerst den Tabellenblattfeed ab und suchen Sie den gewünschten Tabellenblatteintrag, der eine edit-URL enthält.
Aktualisieren Sie die Metadaten des Tabellenblatts und senden Sie sie als Anfragetext einer PUT-Anfrage an die Bearbeitungs-URL. Beispiel:
PUT https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
<entry>
<id>
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId
</id>
<updated>2007-07-30T18:51:30.666Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#worksheet"/>
<title type="text">Expenses</title>
<content type="text">Expenses</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>45</gs:rowCount>
<gs:colCount>15</gs:colCount>
</entry>
v4 API
Wenn Sie Größe, Titel und andere Eigenschaften von Tabellen aktualisieren möchten, senden Sie eine updateSheetProperties-Anfrage in der Methode spreadsheets.batchUpdate. Der Anfragetext von POST sollte die zu ändernden Properties enthalten und der Parameter fields sollte diese Properties explizit auflisten. Wenn Sie alle Properties aktualisieren möchten, verwenden Sie fields:"*" als Kurzform für die Auflistung aller Properties. Im folgenden Beispiel wird beispielsweise angegeben, dass die Eigenschaften „Tabellentitel“ und „Größe“ für das Tabellenblatt mit der angegebenen ID aktualisiert werden sollen:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"updateSheetProperties": {
"properties": {
"sheetId": sheetId,
"title": "Expenses",
"gridProperties": {
"rowCount": 45,
"columnCount": 15,
}
},
"fields": "title,gridProperties(rowCount,columnCount)"
}
}
],
}
Wenn Sie die sheetId einer Tabelle abrufen möchten, verwenden Sie die Methode spreadsheets.get.
Tabellenblatt löschen
Mit beiden APIs können Sie Tabellen aus einer bestimmten Tabelle entfernen.
v3 API
Wenn Sie ein Tabellenblatt löschen möchten, rufen Sie zuerst den Tabellenblattfeed ab und senden Sie dann eine DELETE-Anfrage an die edit-URL des Zieltabellenblatteintrags.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
v4 API
Wenn Sie ein Tabellenblatt löschen möchten, senden Sie eine DeleteSheet-Anfrage in der Methode spreadsheets.batchUpdate. Der Anfragetext für POST sollte nur die sheetId für das zu löschende Tabellenblatt enthalten. Beispiel:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}
Wenn Sie die sheetId eines einzelnen Tabellenblatts abrufen möchten, verwenden Sie die Methode spreadsheets.get für Tabellenblätter.
Zeilendaten abrufen
Der Listenzeilenfeed ist eine der beiden Methoden, die die Google Tabellen API v3 zum Zugriff auf Daten in den Zellen einer Tabelle bietet (die andere ist der Zellenfeed). Der Zeilenfeed soll gängige Tabellenfunktionen unterstützen (Zeilenzeilenweise lesen, Zeilen anhängen, sortieren). Er geht jedoch von bestimmten Annahmen aus, die ihn für einige Aufgaben ungeeignet machen. Im Listenfeed wird davon ausgegangen, dass leere Zeilen das Ende des Feeds markieren und dass in der ersten Zeile einer Tabelle die Pflichtüberschriften vorhanden sind.
Im Gegensatz dazu verwendet die Sheets API v4 keine zeilenspezifischen Zugriffsmethoden. Stattdessen wird auf die Daten in Tabellenzellen durch Verweisen auf die erforderlichen Bereiche mithilfe der A1-Notation zugegriffen. Die Bereiche können Zellenblöcke, ganze Zeilen, ganze Spalten oder ganze Tabellen sein. Die API kann auch auf nicht zusammenhängende Zellengruppen zugreifen.
v3 API
Wenn Sie die URL eines listenbasierten Feeds für ein bestimmtes Tabellenblatt ermitteln möchten, rufen Sie den Tabellenblattfeed ab und suchen Sie im entsprechenden Tabellenblatteintrag nach der URL des Listenfeeds.
Wenn Sie einen listenbasierten Feed abrufen möchten, senden Sie eine GET-Anfrage an die URL des Listenfeeds und verwenden Sie dabei einen geeigneten Autorisierungsheader. Beispiel:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Die Antwort auf diese Anfrage enthält unter anderem Einträge, die bestimmten Zeilen entsprechen. Auf einzelne Zellen wird über die Namen verwiesen, die in der (obligatorischen) Kopfzeile der Tabelle angegeben sind. Hier ist beispielsweise ein Eintrag mit einer einzelnen Zeile:
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>10</gsx:hours>
<gsx:items>2</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
Standardmäßig werden die im Listenfeed zurückgegebenen Zeilen in Zeilenreihenfolge zurückgegeben. Die Google Tabellen API 3 bietet Abfrageparameter, mit denen sich diese Reihenfolge ändern lässt.
Umgekehrte Reihenfolge:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Nach einer bestimmten Spalte sortieren:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastname
Mit der Google Tabellen API v3 können Sie auch bestimmte Zeilen über eine strukturierte Abfrage filtern, auf die über Spaltenüberschriften verwiesen wird:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175v4 API
Mit der Google Tabellen API 4 können Zeilen mithilfe der Methoden spreadsheets.values.get oder spreadsheets.values.batchGet nach Bereich abgerufen werden. Mit dem folgenden Code werden beispielsweise alle Zeilen in „Tabelle1“ zurückgegeben:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
Die Antwort auf diese Anfrage hat ungefähr folgende Struktur:
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}
Leere Zellen am Ende werden nicht in die Antwort aufgenommen, wenn ganze Zeilen, Spalten oder Tabellen abgerufen werden.
Die Sheets API v4 hat keine Entsprechungen für die Abfrageparameter für die Zeilenreihenfolge, die von der Sheets API v3 bereitgestellt werden. Die umgekehrte Reihenfolge ist ganz einfach: Bearbeiten Sie das zurückgegebene values-Array einfach in umgekehrter Reihenfolge. Die Sortierung nach Spalte wird für Lesevorgänge nicht unterstützt. Sie können die Daten in der Tabelle jedoch mithilfe einer SortRange-Anfrage sortieren und dann lesen.
Die Sheets API v4 hat derzeit kein direktes Äquivalent für die strukturierten Abfragen der Sheets API v3. Sie können jedoch die relevanten Daten abrufen und nach Bedarf in Ihrer Anwendung sortieren.
Neue Datenzeile hinzufügen
Mit beiden APIs können Sie einem Tabellenblatt eine neue Datenzeile hinzufügen.
v3 API
Wenn Sie die URL eines listenbasierten Feeds für ein bestimmtes Tabellenblatt ermitteln möchten, rufen Sie den Tabellenblattfeed ab und suchen Sie im gewünschten Tabellenblatteintrag nach der Post-URL.
Wenn Sie eine Datenzeile hinzufügen möchten, senden Sie eine POST-Anfrage an die POST-URL und verwenden Sie dabei einen geeigneten Autorisierungsheader. Beispiel:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Der Textkörper der POST-Anfrage sollte einen Eintrag für die hinzuzufügenden Zeilendaten enthalten, wobei auf einzelne Zellen über Spaltenüberschriften verwiesen wird:
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gsx="http://schemas.google.com/spreadsheets/2006/extended">
<gsx:hours>2</gsx:hours>
<gsx:ipm>0.5</gsx:ipm>
<gsx:items>60</gsx:items>
<gsx:name>Elizabeth</gsx:name>
</entry>
Neue Zeilen werden am Ende des angegebenen Tabellenblatts angehängt.
v4 API
Mit der Google Tabellen API 4 können Sie Zeilen mit der Methode spreadsheets.values.append anhängen. Im folgenden Beispiel wird eine neue Datenzeile unter der letzten Tabelle in „Tabelle1“ einer Tabelle geschrieben.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
Außerdem können Sie mit der Sheets API v4 Zellen mit bestimmten Eigenschaften und Formatierungen anhängen. Verwenden Sie dazu die AppendCells-Anfragen in einer spreadsheets.batchUpdate.
Zeile mit neuen Daten bearbeiten
Mit beiden APIs können Zeilendaten mit neuen Werten aktualisiert werden.
v3 API
Wenn Sie eine Datenzeile bearbeiten möchten, suchen Sie im Listenfeed nach dem Eintrag für die Zeile, die Sie aktualisieren möchten. Aktualisieren Sie den Inhalt dieses Eintrags nach Bedarf. Der ID-Wert im verwendeten Eintrag muss genau mit der ID des vorhandenen Eintrags übereinstimmen.
Nachdem der Eintrag aktualisiert wurde, senden Sie eine PUT-Anfrage mit dem Eintrag als Anfragekörper an die in diesem Zeileneintrag angegebene edit-URL. Verwenden Sie dabei einen geeigneten Autorisierungsheader. Beispiel:
PUT https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>20</gsx:hours>
<gsx:items>4</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
v4 API
Mit der Google Tabellen API 4 können Sie eine Zeile mithilfe der A1-Notation der Zeile bearbeiten, die Sie bearbeiten möchten, und eine spreadsheets.values.update-Anfrage senden, um diese Zeile zu überschreiben. Der angegebene Bereich muss sich nur auf die erste Zelle in der Zeile beziehen. Die API leitet die zu aktualisierenden Zellen anhand der mit der Anfrage bereitgestellten Werte ab. Wenn Sie stattdessen einen Bereich mit mehreren Zellen angeben, müssen die angegebenen Werte in diesen Bereich passen. Andernfalls gibt die API einen Fehler zurück.
In der folgenden Beispielanfrage und dem Anfragetext werden der vierten Zeile von „Tabelle1“ Daten hinzugefügt:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
Sie können Zeilendaten auch mit der Methode spreadsheet.values.batchUpdate aktualisieren. Diese Methode ist effizienter, wenn Sie mehrere Zeilen- oder Zellenaktualisierungen vornehmen.
Außerdem können Sie mit der Google Tabellen API 4 die Zelleneigenschaften und die Formatierung von Zellen mithilfe der Anfragen UpdateCells oder RepeatCell in einer spreadsheets.batchUpdate bearbeiten.
Zeile löschen
Beide APIs unterstützen das Löschen von Zeilen. Eine gelöschte Zeile wird aus der Tabelle entfernt und die Zeilen darunter werden um eine Position nach oben verschoben.
v3 API
Wenn Sie eine Zeile löschen möchten, rufen Sie sie zuerst aus dem Listenfeed ab und senden Sie dann eine DELETE-Anfrage an die edit-URL, die im Eintrag der Zeile angegeben ist.
Dies ist dieselbe URL, die zum Aktualisieren der Zeile verwendet wurde.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Wenn Sie sicherstellen möchten, dass Sie keine Zeile löschen, die seit dem Abrufen durch einen anderen Client geändert wurde, fügen Sie einen HTTP-Header vom Typ „If-Match“ mit dem ETag-Wert der ursprünglichen Zeile hinzu. Sie können den ETag-Wert der ursprünglichen Zeile anhand des Attributs „gd:etag“ des Eintragelements ermitteln.
Wenn Sie die Zeile unabhängig davon löschen möchten, ob sie seit dem Abrufen durch eine andere Person aktualisiert wurde, verwenden Sie „If-Match: *“ und geben Sie kein ETag an. In diesem Fall müssen Sie die Zeile nicht abrufen, bevor Sie sie löschen.
v4 API
Das Löschen von Zeilen mit der Google Tabellen API 4 wird über einen spreadsheet.batchUpdate-Methodenaufruf mit einer DeleteDimension-Anfrage verarbeitet. Mit dieser Anfrage können auch Spalten entfernt werden. Entwickler können auch nur einen Teil einer Zeile oder Spalte entfernen. Mit dem folgenden Code wird beispielsweise die 6. Zeile eines Tabellenblatts mit der angegebenen ID entfernt. Die Zeilenindexe beginnen bei null, wobei startIndex eingeschlossen und endIndex ausgeschlossen ist:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}
Die sheetId eines Tabellenblatts kann mit der Methode spreadsheet.get abgerufen werden.
Zellendaten abrufen
Die Sheets API v3 bietet einen Zellenfeed für den grundlegenden Zugriff auf alle in einer Tabelle gespeicherten Daten. Bei Lesezugriff kann der Zellenfeed den gesamten Tabelleninhalt oder einen Bereich der Zellen der Tabelle enthalten, der durch eine Reihe von Abfrageparametern definiert ist. Er muss jedoch als einzelner Block bereitgestellt werden. Nicht zusammenhängende Bereiche müssen mithilfe zusätzlicher GET-Anfragen separat abgerufen werden.
Mit der Google Tabellen API 4 können beliebige Zellendaten aus einem Tabellenblatt abgerufen werden, einschließlich mehrerer nicht zusammenhängender Bereiche. Die Google Tabellen API 3 kann Zelleninhalte nur als Eingabewerte (wie sie von einem Nutzer auf der Tastatur eingegeben würden) und/oder als Formelergebnisse (wenn sie numerisch sind) zurückgeben. Die Google Tabellen API 4 gewährt vollen Zugriff auf Werte, Formeln, Formatierungen, Hyperlinks, Datenvalidierung und andere Eigenschaften.
v3 API
Wenn Sie die URL eines zellenbasierten Feeds für ein bestimmtes Tabellenblatt ermitteln möchten, sehen Sie sich den Tabellenblattfeed an und suchen Sie im entsprechenden Tabellenblatteintrag nach der URL des Zellenfeeds.
Wenn Sie einen zellenbasierten Feed abrufen möchten, senden Sie eine GET-Anfrage an die URL des Zellenfeeds und verwenden Sie dabei einen geeigneten Autorisierungsheader. Beispiel:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Zellen werden anhand der Zeilen- und Spaltennummer referenziert. Mit den Abfrageparametern max-row, min-row, max-col und min-col können Sie einen bestimmten Bereich abrufen. Mit dem folgenden Beispiel werden beispielsweise alle Zellen in Spalte 4 (D) ab Zeile 2 abgerufen:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4
Die Google Tabellen API v3 gibt die inputValue der abgerufenen Zellen zurück. Das ist der Wert, den ein Nutzer sonst in die Benutzeroberfläche von Google Tabellen eingeben würde, um die Zelle zu bearbeiten. inputValue kann ein Literalwert oder eine Formel sein. Manchmal gibt die API auch eine numericValue zurück, z. B. wenn eine Formel zu einer Zahl führt. Eine Antwort kann beispielsweise Zelleneinträge mit einer ähnlichen Struktur wie der folgenden enthalten:
<entry gd:etag='"ImB5CBYSRCp7"'>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4</id>
<updated>2006-11-17T18:27:32.543Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#cell"/>
<title type="text">D4</title>
<content type="text">5</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4/srevc"/>
<gs:cell row="4" col="4" inputValue="=FLOOR(C4/(B4*60),.0001)"
numericValue="5.0">5</gs:cell>
</entry>
v4 API
Rufen Sie die Methode spreadsheets.values.get oder spreadsheets.values.batchGet für den gewünschten Bereich bzw. die gewünschten Bereiche auf, um Zellendaten abzurufen. Mit der folgenden Formel werden beispielsweise die Zellen in Spalte D von „Tabelle 2“ ab Zeile 2 in spaltenübergreifender Reihenfolge zurückgegeben. Dabei werden die eingegebenen Formeln zurückgegeben (leere Zellen am Ende werden ignoriert):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
Die Antwort auf diese Anfrage ähnelt in der Struktur folgendem Beispiel:
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}
Wenn Sie mehrere Zellenbereiche abrufen möchten, ist es effizienter, spreadsheet.values.batchGet zu verwenden. Wenn Sie auf Zelleneigenschaften wie die Formatierung zugreifen möchten, ist die Methode spreadsheet.get erforderlich.
Zelle bearbeiten
Mit der Google Tabellen API v3 können Sie Zelleninhalte bearbeiten, indem Sie einen PUT-Befehl an den Zellenfeed mit dem geänderten Zelleneintrag als Anfragetext senden.
Die Sheets API V4 bietet dagegen die Methoden spreadsheets.values.update und spreadsheets.values.batchUpdate zum Ändern von Zelleninhalten.
v3 API
Wenn Sie den Inhalt einer einzelnen Zelle bearbeiten möchten, suchen Sie zuerst den Eintrag der Zelle im Zellenfeed.
Der Eintrag enthält eine Bearbeitungs-URL. Aktualisieren Sie den Eintrag mit dem gewünschten Inhalt der Zelle und senden Sie dann eine PUT-Anfrage an die Bearbeitungs-URL mit dem aktualisierten Zelleneintrag als Anfragetext. Mit dem folgenden Beispiel wird beispielsweise Zelle D2 (R2C4) mit einer SUM-Formel aktualisiert:
PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gs="http://schemas.google.com/spreadsheets/2006"> <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id> <link rel="edit" type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/> <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/> </entry>
v4 API
Die Bearbeitung einzelner Zellen in der Google Tabellen API v4 ist mit der Methode spreadsheets.values.update möglich. Für diese Methode ist ein ValueInputOption-Abfrageparameter erforderlich, mit dem angegeben wird, ob die Eingabedaten so behandelt werden, als wären sie in die Google Tabellen-Benutzeroberfläche eingegeben worden (USER_ENTERED), oder ob sie nicht geparst und unverändert übernommen werden (RAW). Mit der folgenden Formel wird beispielsweise Zelle D2 mit einer Formel aktualisiert:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}
Wenn Sie mehrere Zellen bearbeiten möchten, verwenden Sie die Methode spreadsheets.values.batchUpdate, um sie in einer einzigen Anfrage auszuführen.
Mehrere Zellen über eine Batchanfrage bearbeiten
Mit beiden APIs können Sie mit einer einzigen (Batch-)Anfrage Änderungen am Inhalt mehrerer Zellen vornehmen. Die Zellen, auf die in einer Batchanfrage verwiesen wird, müssen sich nicht in einem zusammenhängenden Bereich befinden.
Wenn eine oder mehrere Zellenänderungen im Batch fehlschlagen, können andere mit der Sheets API v3 ausgeführt werden. Die Sheets API v4 gibt jedoch einen Fehler zurück, wenn eines der Batch-Updates fehlschlägt, und wendet in diesem Fall keines davon an.
v3 API
Wenn Sie mehrere Zellen bearbeiten möchten, rufen Sie zuerst einen Zellenfeed für das Tabellenblatt ab. Der Eintrag enthält eine Batch-URL. Senden Sie eine POST-Anfrage an diese URL zusammen mit einem Anfragetext, in dem die Zellen beschrieben werden, die Sie aktualisieren möchten, und der neue Zelleninhalt. Die POST-Anfrage und der Anfragetext haben eine ähnliche Struktur:
POST https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/batch
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:batch="http://schemas.google.com/gdata/batch"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full</id>
<entry>
<batch:id>request1</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4/version"/>
<gs:cell row="2" col="4" inputValue="newData"/>
</entry>
...
<entry>
<batch:id>request2</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5/version"/>
<gs:cell row="5" col="2" inputValue="moreInfo"/>
</entry>
</feed>
Das Feld batch:id sollte die Anfrage innerhalb des Batches eindeutig identifizieren.
Das Feld batch:operation sollte für Zellenbearbeitungen update lauten. gs:cell identifiziert die Zelle anhand der Zeilen- und Spaltennummer und gibt die neuen Daten an, die dort eingefügt werden sollen. id enthält die vollständige URL der Zelle, die aktualisiert werden soll.
link muss ein href-Attribut haben, das den vollständigen Pfad zur ID der Zelle enthält. Alle diese Felder sind für jeden Eintrag erforderlich.
v4 API
Die Google Tabellen API 4 bietet die Batch-Bearbeitung von Zellenwerten über die Methode spreadsheets.values.batchUpdate.
Wenn Sie mehrere Zellen bearbeiten möchten, senden Sie eine POST-Anfrage mit den Datenänderungen, die im Anfragetext angegeben sind. Beispiel:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{
"valueInputOption": "USER_ENTERED"
"data": [
{"range": "D4",
"majorDimension": "ROWS",
"values": [["newData"]]
},
{"range": "B5",
"majorDimension": "ROWS",
"values": [["moreInfo"]]
}
]
}
Wenn Sie eine einzelne Zelle als Bereich angegeben haben, werden alle angegebenen Werte in das Tabellenblatt geschrieben, beginnend mit dieser Zelle als Koordinate links oben. Wenn Sie stattdessen einen Bereich mit mehreren Zellen angeben, müssen die angegebenen Werte genau in diesen Bereich passen. Andernfalls gibt die API einen Fehler zurück.