Wenn Sie bereits Anwendungen haben, die auf der Google Sheets API Version 3 basieren, können Sie zu Version 4 der Google Sheets API migrieren. Version 4 ist JSON-basiert, bietet eine nutzerfreundliche Oberfläche und bietet viele Funktionen, die in Version 3 nicht möglich sind.
Auf dieser Seite finden Sie eine Zuordnung zwischen den älteren Befehlen der Sheets API Version 3 und den entsprechenden Vorgängen in der Sheets API Version 4. Der Schwerpunkt liegt auf der Sammlung spreadsheets.values, die direkte Lese- und Schreibfunktionen für Zellen bietet. Andere Aspekte wie das Hinzufügen von Tabellenblättern oder das Aktualisieren von Tabelleneigenschaften werden über die Sammlung Tabellen verwaltet. Die JSON-Strukturen der API V4 sind mit den in Version 3 verwendeten XML-Strukturen nicht abwärtskompatibel.
Weitere Informationen zu den in der Sheets v4 API verfügbaren Ressourcen finden Sie in der API-Referenz.
Schreibweise und Begriffe
In Version 3 des APIs werden Tabellenblätter in einer bestimmten Tabelle als „Arbeitsblätter“ bezeichnet. Dies ist ein Synonym für den Begriff "Tabellen", den die API v4 verwendet.
Für die APIs müssen Sie häufig die Tabellen-ID der Tabelle angeben, mit der Sie arbeiten. Häufig wird auch die ID des zu ändernden Tabellenblatts benötigt. Diese Werte werden entweder als Teil der API-Endpunkt-URL, als Abfrageparameter oder als Teil eines Anfragetexts angezeigt. Auf dieser Seite beziehen sich die Platzhalter spreadsheetId und sheetId auf die Tabellen- bzw. Tabellen-IDs. Wenn Sie die auf dieser Seite beschriebenen Methoden verwenden, ersetzen Sie die tatsächlichen IDs an diesen Orten.
Version 3 der API weist auch Zeilen, die mit ihrem Listenfeed abgerufen wurden, eine ID zu. Auf dieser Seite wird dies durch den Platzhalter rowId dargestellt.
Anfragen autorisieren
Wenn Ihre App ausgeführt wird, werden Nutzer aufgefordert, bestimmte Berechtigungen zu gewähren. Die von Ihnen in der Anwendung angegebenen Bereiche bestimmen, welche Berechtigungen angefordert werden.
Version 3 der API
Die Sheets API Version 3 arbeitet mit einem einzigen Autorisierungsbereich:
https://spreadsheets.google.com/feeds
Dies ist ein Alias für
https://www.googleapis.com/auth/spreadsheets
Beide Bereichsformate können verwendet werden.
Version 4 der API
In Version 4 der Sheets API wird 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 schreibgeschützte Bereiche, wenn Ihre Anwendung keine Änderungen an den Tabellenblättern oder Tabellenblatteigenschaften eines Nutzers vornehmen muss. Verwenden Sie Tabellenkalkulationen 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.
Version 3 der API
In Version 3 der Sheets API wird Sichtbarkeit direkt in den Endpunkten festgelegt. Eine public-Tabelle wurde „im Web veröffentlicht“ und kann daher ohne Autorisierung von der API aufgerufen werden. Eine private-Tabelle erfordert dagegen eine Authentifizierung. Die Sichtbarkeit wird im Endpunkt nach der Tabellen-ID angegeben:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
Version 4 der API
In der neuen Sheets API Version 4 gibt es keine explizite Erklärung der Sichtbarkeit. API-Aufrufe erfolgen mithilfe von Tabellen-IDs. Wenn die Anwendung keine Berechtigung für den Zugriff auf die angegebene Tabelle hat, wird ein Fehler zurückgegeben. Andernfalls wird der Aufruf fortgesetzt.
Projektion
Der Begriff Projektion wird von der Sheets API Version 3 verwendet, um auf den Datensatz zu verweisen, der von einem bestimmten API-Aufruf zurückgegeben wird – entweder alle oder eine feste, in der API definierte Teilmenge. In Version 4 der Sheets API wird keine Projektion verwendet. Sie haben damit mehr Kontrolle darüber, welche Daten zurückgegeben werden.
Version 3 der API
In der Sheets API Version 3 sind nur zwei Projektionseinstellungen möglich. Die full-Projektion gibt alle verfügbaren Informationen zurück, während basic eine kleinere, feste Teilmenge von Daten zurückgibt (für die Arbeitsblätter, Listen und Zellenfeeds).
Wie die Sichtbarkeit muss auch die Projektion im API-Endpunkt angegeben werden (nach der Sichtbarkeitseinstellung):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
Die kleinere Teilmenge von Daten, die von der Projektion basic bereitgestellt wird, ist nützlich, um Code effizienter zu gestalten, kann aber nicht angepasst werden.
Version 4 der API
Die Sheets API (Version 4) kann zwar einen vollständigen Datensatz zurückgeben, definiert aber keine festen Teilmengen wie mit der Sichtbarkeitseinstellung basic in Version 3 der Sheets API.
Die Methoden in der Tabellensammlung beschränken die zurückgegebene Datenmenge mithilfe des Abfrageparameters fields.
Die folgende Abfrage gibt beispielsweise nur die Titel aller Tabellenblätter in einer bestimmten Tabelle zurück:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Tabelle erstellen
Version 3 der API
Version 3 der Sheets API bietet keine Möglichkeit, neue Tabellen zu erstellen. Stattdessen können Sie mit der Methode Drive API Files.create neue Tabellendateien erstellen. Dazu muss die Anwendung den Bereich https://www.googleapis.com/auth/drive deklarieren.
Version 4 der API
Die Methode Drive API Files.create kann auch mit der Sheets API Version 4 verwendet werden. Dafür muss die Anwendung den Bereich https://www.googleapis.com/auth/drive bereitstellen.
Als äquivalente Alternative bietet Version 4 der Sheets API die Methode spreadsheets.create, mit der Sie optional Tabellenblätter hinzufügen, die Tabellen- und Tabellenblatteigenschaften festlegen und benannte Bereiche hinzufügen können. Im folgenden Beispiel wird eine neue Tabelle erstellt und ihr den Namen "NewTitle" geben:
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Tabellen für den authentifizierten Nutzer auflisten
Version 3 der API
Mit dem Feed der Sheets API Version 3 kann eine Anwendung eine Liste aller Tabellen abrufen, auf die der authentifizierte Nutzer zugreifen kann. Der Endpunkt des Tabellenfeeds ist:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
Version 4 der API
In der Sheets API Version 4 ist dieser Vorgang nicht möglich. Wir empfehlen, Ihre Anwendung zu migrieren, um den Bereich „drive.file“ in Kombination mit der Google-Auswahl für die Tabellenauswahl zu verwenden.
Wenn Tabellen aufgelistet werden müssen, können diese über die Methode Drive API Files.list mithilfe 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 Bereich erforderlich.
Tabellenmetadaten abrufen
Die Sheets API Version 3 bietet einen Feed für den Zugriff auf die Tabellenmetadaten in einer bestimmten Tabelle. Der Zugriff auf Zeilen- und Zellendaten erfolgt über einen separaten Feed. Die Metadaten enthalten Informationen wie Tabellenblatttitel und Größeninformationen.
Mit der Methode spreadsheets.get der Sheets API Version 4 haben Sie Zugriff auf diese und weitere Informationen.
Version 3 der API
Der Arbeitsblattfeed kann über diesen API-Endpunkt über einen entsprechenden Autorisierungsheader aufgerufen werden:
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
Die Antwort auf diese Anfrage hat eine ähnliche Struktur, wobei die Daten jedes Tabellenblatts in einem separaten <entry> enthalten sind:
<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>
Version 4 der API
Mit der Methode spreadsheets.get können Sie Tabelleneigenschaften und andere Metadaten abrufen – wesentlich mehr als in der Sheets API Version 3 verfügbar. Wenn Sie nur die Eigenschaften des Tabellenblatts lesen möchten, legen Sie den includeGridData-Abfrageparameter auf false fest, um zu verhindern, dass die Zellendaten der Tabelle eingeschlossen werden:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
Die Antwort Spreadsheet enthält ein Array mit Sheet-Objekten. Die Tabellenblatttitel und Informationen zur Größe findest du unter dem 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
},
...
},
...
},
...
],
...
}Einer Tabelle ein Tabellenblatt hinzufügen
Mit beiden APIs können Sie einer vorhandenen Tabelle neue Tabellenblätter hinzufügen.
Version 3 der API
Mit der Sheets API v3 können einer Tabelle neue Arbeitsblätter hinzugefügt werden, indem die folgende (authentifizierte) POST-Anfrage gestellt wird. Sie können die Größe des
neuen Tabellenblatts 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>
Version 4 der API
Sie können neue Tabellenblätter hinzufügen, indem Sie eine AddSheet-Anfrage in der Methode spreadsheets.batchUpdate stellen. Im Text der Anfrage können Sie die Eigenschaften des neuen Tabellenblatts angeben. Alle Eigenschaften sind optional. Es ist ein Fehler, einen Titel anzugeben, der für ein vorhandenes Tabellenblatt 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 von Tabellenblättern ändern
Mit der Sheets API Version 3 können Sie die Titel und die Größe von Tabellenblättern aktualisieren. Mit der Sheets API Version 4 ist dies ebenfalls möglich. Sie können damit aber auch andere Eigenschaften von Tabellenblättern aktualisieren. Wenn Sie die Größe eines Tabellenblatts verringern, können Daten in den zugeschnittenen Zellen ohne Warnung gelöscht werden.
Version 3 der API
Wenn Sie den Titel oder die Größe eines Arbeitsblatts ändern möchten, rufen Sie zuerst den Arbeitsblattfeed ab und suchen Sie nach dem gewünschten Arbeitsblatteintrag, der eine edit-URL enthält.
Aktualisieren Sie die Metadaten des Arbeitsblatts und senden Sie sie als Text 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>
Version 4 der API
Um Größe, Titel und andere Eigenschaften von Tabellenblättern zu aktualisieren, stellen Sie eine updateSheetProperties-Anfrage in der Methode spreadsheets.batchUpdate. Der POST-Anfragetext sollte die zu ändernden Attribute enthalten und der Parameter fields sollte diese Attribute explizit auflisten. Wenn Sie alle Attribute aktualisieren möchten, verwenden Sie fields:"*" als Abkürzung für die Auflistung aller Attribute. Mit der folgenden Eingabe können Sie beispielsweise festlegen, dass der Titel und die Größeneigenschaften des Tabellenblatts 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)"
}
}
],
}
Der sheetId eines Tabellenblatts wird mit der Tabellenmethode spreadsheets.get abgerufen.
Tabellenblatt löschen
Beide APIs können Tabellenblätter aus einer bestimmten Tabelle entfernen.
Version 3 der API
Wenn Sie ein Arbeitsblatt löschen möchten, rufen Sie zuerst den Arbeitsblattfeed ab und senden Sie dann eine DELETE-Anfrage an die URL edit des Zielarbeitsblatteintrags.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
Version 4 der API
Wenn Sie ein Tabellenblatt löschen möchten, stellen Sie eine DeleteSheet-Anfrage in der Methode spreadsheets.batchUpdate. Der Text der POST-Anfrage sollte nur das sheetId-Element für das zu löschende Tabellenblatt enthalten. Beispiel:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}
Um den sheetId eines einzelnen Tabellenblatts abzurufen, verwenden Sie die Tabelle spreadsheets.get.
Zeilendaten abrufen
Der Feed mit Listenzeilen ist eine der beiden Methoden der Sheets API Version 3, um auf Daten in Zellen einer Tabelle zuzugreifen (die andere ist der Zellenfeed). Der Zeilenfeed soll gängige Tabellenvorgänge unterstützen (Zeilen für Zeile lesen, Zeilen anhängen, Sortieren). Es werden jedoch bestimmte Annahmen getroffen, die ihn für einige Aufgaben ungeeignet machen. Insbesondere geht es beim Listenfeed davon aus, dass leere Zeilen Feedbeendigungen sind und obligatorische Kopfzeilen in der ersten Zeile eines Tabellenblatts vorhanden sind.
Im Gegensatz dazu werden in Version 4 der Sheets API keine zeilenspezifischen Zugriffsmethoden verwendet. Der Zugriff auf die Daten von Tabellenblattzellen erfolgt stattdessen über die spezifischen Bereiche, die in der A1-Notation erforderlich sind. Bereiche können Zellenblöcke, ganze Zeilen, ganze Spalten oder ganze Blätter sein. Die API kann auch auf getrennte Gruppen von Zellen zugreifen.
Version 3 der API
Wenn Sie die URL eines listenbasierten Feeds für ein bestimmtes Arbeitsblatt ermitteln möchten, rufen Sie den Arbeitsblattfeed ab und suchen Sie die Listenfeed-URL im entsprechenden Arbeitsblatteintrag.
Wenn Sie einen listenbasierten Feed abrufen möchten, senden Sie eine GET-Anfrage unter Verwendung eines entsprechenden Autorisierungsheaders an die Listenfeed-URL. 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 durch die Namen verwiesen, die in der (erforderlichen) Kopfzeile des Tabellenblatts angegeben sind. Hier ist beispielsweise ein Eintrag in 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 der Zeilenreihenfolge zurückgegeben. Die Sheets API Version 3 bietet Abfrageparameter, mit denen diese Reihenfolge geändert werden kann.
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
Version 3 der Sheets API ermöglicht auch das Filtern bestimmter Zeilen mithilfe einer strukturierten Abfrage (auf die durch Spaltenüberschriften verwiesen wird):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175Version 4 der API
In der Google Sheets API Version 4 können Zeilen mit den Methoden spreadsheets.values.get oder spreadsheets.values.batchGet nach Bereich abgerufen werden. Im folgenden Beispiel werden alle Zeilen in „Sheet1“ zurückgegeben:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
Die Antwort auf diese Anfrage hat eine ähnliche Struktur wie diese:
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}
Wenn ganze Zeilen, Spalten oder Tabellenblätter abgerufen werden, werden am Ende leere Zellen nicht in die Antwort einbezogen.
In Version 4 der Sheets API gibt es keine Äquivalente für die Abfrageparameter für die Zeilenreihenfolge, die von der Sheets API Version 3 bereitgestellt werden. Die umgekehrte Reihenfolge ist einfach. Verarbeiten Sie das zurückgegebene values-Array einfach in umgekehrter Reihenfolge. Das Sortieren nach Spalten wird für Lesevorgänge nicht unterstützt, aber es ist möglich, die Daten im Tabellenblatt (mithilfe einer SortRange-Anfrage) zu sortieren und dann zu lesen.
Für die strukturierten Abfragen der Sheets API Version 3 gibt es derzeit keine direkte Entsprechung für die Sheets API Version 3. Sie können die relevanten Daten jedoch abrufen und nach Bedarf in Ihrer Anwendung sortieren.
Neue Datenzeile hinzufügen
Sie können einem Tabellenblatt mit einer der beiden APIs eine neue Datenzeile hinzufügen.
Version 3 der API
Um die URL eines listenbasierten Feeds für ein bestimmtes Arbeitsblatt zu ermitteln, rufen Sie den Arbeitsblatt-Feed ab und suchen die Post-URL im entsprechenden Arbeitsblatteintrag.
Wenn Sie eine Datenzeile hinzufügen möchten, senden Sie eine POST-Anfrage unter Verwendung eines geeigneten Autorisierungsheaders an die Post-URL. Beispiel:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Der Text der POST-Anfrage sollte einen Eintrag für die hinzuzufügenden Zeilendaten enthalten, wobei einzelne Zellen durch Spaltenüberschriften referenziert werden:
<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 an das Ende des angegebenen Tabellenblatts angehängt.
Version 4 der API
In Version 4 der Sheets API können Sie Zeilen mit der Methode spreadsheets.values.append anhängen. Im folgenden Beispiel wird unter der letzten Tabelle in „Sheet1“ eine neue Datenzeile geschrieben.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
Außerdem können Sie in Version 4 der Sheets API Zellen mit bestimmten Eigenschaften und Formatierungen mithilfe von AppendCells-Anfragen in einer spreadsheets.batchUpdate anhängen.
Zeile mit neuen Daten bearbeiten
Beide APIs ermöglichen die Aktualisierung von Zeilendaten mit neuen Werten.
Version 3 der 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. Achten Sie darauf, dass der ID-Wert im verwendeten Eintrag genau mit der ID des vorhandenen Eintrags übereinstimmt.
Nachdem der Eintrag aktualisiert wurde, senden Sie eine PUT-Anfrage mit dem Eintrag als Anfragetext an die edit-URL im Zeileneintrag. Verwenden Sie dazu 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>
Version 4 der API
Mit der Sheets API Version 4 können Sie eine Zeile mit der A1-Notation der entsprechenden Zeile bearbeiten 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 Werte in der Anfrage ab. Wenn Sie stattdessen einen mehrzelligen Bereich angeben, müssen die angegebenen Werte in diesen Bereich passen. Andernfalls gibt die API einen Fehler zurück.
Im folgenden Beispiel für den Anfrage- und Anfragetext werden der vierten Zeile von „Sheet1“ 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 über die Methode spreadsheet.values.batchUpdate aktualisieren. Sie ist effizienter, wenn Sie mehrere Zeilen oder Zellen aktualisieren.
Darüber hinaus können Sie mit der Sheets API Version 4 auch die Zelleneigenschaften und die Formatierung von Zellen mit den Anfragen UpdateCells oder RepeatCell in 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 darunter liegenden Zeilen werden um eine nach oben verschoben.
Version 3 der API
Wenn Sie eine Zeile löschen möchten, rufen Sie zuerst die zu löschende Zeile aus dem Listenfeed ab und senden Sie dann eine DELETE-Anfrage an die URL edit, die im Zeileneintrag angegeben ist.
Dies ist dieselbe URL, die zum Aktualisieren der Zeile verwendet wird.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Wenn Sie eine Zeile nicht löschen möchten, die seit dem Abruf von einem anderen Client geändert wurde, fügen Sie einen HTTP-If-Match-Header hinzu, der den ETag-Wert der ursprünglichen Zeile enthält. Sie können den ETag-Wert der ursprünglichen Zeile ermitteln, indem Sie das Attribut gd:etag des Eintragselements untersuchen.
Wenn Sie die Zeile löschen möchten, unabhängig davon, ob sie von einer anderen Person aktualisiert wurde, seit Sie sie abgerufen haben, verwenden Sie If-Match: * und fügen Sie das ETag nicht ein. In diesem Fall müssen Sie die Zeile nicht abrufen, bevor Sie sie löschen.
Version 4 der API
Das Löschen von Zeilen in der Sheets API Version 4 erfolgt über die Methode spreadsheet.batchUpdate über die Anfrage DeleteDimension. Diese Anfrage kann auch verwendet werden, um Spalten und Entwickler zu entfernen und nur einen Teil einer Zeile oder Spalte zu entfernen. Im folgenden Beispiel wird die sechste Zeile eines Tabellenblatts mit der angegebenen ID entfernt (die Zeilenindexe sind nullbasiert, wobei startIndex eingeschlossen und endIndex exklusiv 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 Version 3 bietet einen Zellenfeed für den grundlegenden Zugriff auf alle in einer Tabelle gespeicherten Daten. Für den Lesezugriff kann der Zellenfeed den gesamten Inhalt des Tabellenblatts oder einen Bereich der Zellen des Tabellenblatts angeben, der durch eine Reihe von Abfrageparametern definiert wird, jedoch nur als einzelnen Block. Disjunkte Bereiche müssen separat mit zusätzlichen GET-Anfragen abgerufen werden.
Mit der Sheets API v4 können Sie beliebige Zellendaten aus einem Tabellenblatt abrufen (einschließlich mehrerer disjunkter Bereiche). Die Sheets API Version 3 kann nur Zelleninhalte als Eingabewerte (wie sie von einem Nutzer über eine Tastatur eingegeben werden) und/oder als Ausgaben einer Formel (falls numerisch) zurückgegeben werden. Die Sheets API Version 4 gewährt vollständigen Zugriff auf Werte, Formeln, Formatierungen, Hyperlinks, Datenvalidierung und andere Eigenschaften.
Version 3 der API
Um die URL eines zellbasierten Feeds für ein bestimmtes Arbeitsblatt zu ermitteln, prüfen Sie den Arbeitsblatt-Feed und suchen Sie die Zellen-Feed-URL im entsprechenden Arbeitsblatteintrag.
Um einen zellbasierten Feed abzurufen, senden Sie eine GET-Anfrage unter Verwendung eines entsprechenden Autorisierungsheaders an die Zellenfeed-URL. Beispiel:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Auf Zellen wird anhand der Zeilen- und Spaltennummer verwiesen. Mit den Abfrageparametern max-row, min-row, max-col und min-col kann ein einzelner Bereich abgerufen werden. Die folgende Abfrage ruft beispielsweise alle Zellen in Spalte 4 (D) ab, beginnend mit Zeile 2:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4
Version 3 der Sheets API gibt den inputValue der abgerufenen Zellen zurück. Dies ist der Wert, den ein Nutzer andernfalls in die Google Tabellen-Benutzeroberfläche eingeben würde, um die Zelle zu bearbeiten. inputValue kann ein Literalwert oder eine Formel sein. Die API gibt manchmal auch ein numericValue zurück, beispielsweise wenn eine Formel zu einer Zahl führt. Eine Antwort kann beispielsweise Zelleinträge enthalten, die in etwa so aufgebaut sind:
<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>
Version 4 der API
Sie können Zellendaten abrufen, indem Sie die Methode spreadsheets.values.get oder spreadsheets.values.batchGet für den bzw. die gewünschten Bereiche aufrufen. Im folgenden Beispiel werden die Zellen in Spalte D von „Sheet2“, beginnend mit Zeile 2, in Spalten-Hauptreihenfolge und die eingegebenen Formeln zurückgegeben (nachgestellte leere Zellen werden ausgelassen):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
Die Antwort auf diese Anfrage sieht in etwa so aus:
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}
Wenn Sie mehrere Bereiche von Zellendaten 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.
Zellen bearbeiten
Mit der Sheets API Version 3 können Sie Zelleninhalte bearbeiten. Dazu führen Sie den Befehl PUT an den Zellenfeed mit dem geänderten Zelleneintrag als Anfragetext aus.
Version 4 der Sheets API bietet dagegen die Methoden spreadsheets.values.update und spreadsheets.values.batchUpdate zum Ändern von Zelleninhalten.
Version 3 der API
Um den Inhalt einer einzelnen Zelle zu bearbeiten, suchen Sie zuerst den Eintrag der Zelle im Zellenfeed.
Der Eintrag enthält eine Bearbeitungs-URL. Aktualisieren Sie den Eintrag mit dem Inhalt, den die Zelle haben soll. Senden Sie dann eine PUT-Anfrage an die Bearbeitungs-URL mit dem aktualisierten Zelleneintrag als Text der Anfrage. So wird beispielsweise die Zelle D2 (R2C4) so aktualisiert, dass sie die Formel SUM enthält:
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>
Version 4 der API
In Version 4 der Sheets API können einzelne Zellen mit der Methode spreadsheets.values.update bearbeitet werden. Für diese Methode ist ein ValueInputOption-Abfrageparameter erforderlich. Dieser gibt an, ob die Eingabedaten so behandelt werden, als wären sie in die Benutzeroberfläche von Google Tabellen eingegeben (USER_ENTERED) oder ob sie nicht geparst und unverändert übernommen werden (RAW). In folgendem Beispiel wird 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 Änderungen an mehreren Zellen vornehmen, verwenden Sie die Methode spreadsheets.values.batchUpdate, um die Zellen in einer Anfrage zu senden.
Mehrere Zellen per Batchanfrage bearbeiten
Beide APIs bieten die Möglichkeit, mit einer einzigen (Batch-)Anfrage Änderungen am Inhalt mehrerer Zellen vorzunehmen. Die Zellen, auf die in einer Batchanfrage verwiesen wird, müssen sich nicht in einem begrenzten Bereich befinden.
Falls eine oder mehrere Zellenbearbeitungen im Batch fehlschlagen, ermöglicht die Sheets API Version 3 andere Zellen. Die Sheets API Version 4 gibt jedoch einen Fehler zurück, wenn eine der Batch-Updates fehlschlägt, und wendet in diesem Fall keine an.
Version 3 der API
Wenn Sie mehrere Zellen bearbeiten möchten, rufen Sie zuerst einen Zellfeed für das Arbeitsblatt ab. Der Eintrag enthält eine Batch-URL. Senden Sie eine POST-Anfrage zusammen mit einem Anfragetext, der die zu aktualisierenden Zellen und den neuen Zelleninhalt beschreibt, an diese URL. Die POST-Anfrage und der Anfragetext haben eine Struktur wie diese:
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 im Batch eindeutig identifizieren.
Das Feld batch:operation muss zum Bearbeiten von Zellen update lauten. gs:cell identifiziert die Zelle anhand der Zeilen- und Spaltennummer und stellt die neuen Daten bereit, 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 Pflichtfelder.
Version 4 der API
In Version 4 der Sheets API kann Zellenwerte mit der Methode spreadsheets.values.batchUpdate im Batch bearbeitet werden.
Sie können mehrere Zellen bearbeiten, indem Sie eine POST-Anfrage mit den im Anfragetext angegebenen Datenänderungen senden. 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 als Bereich eine einzelne Zelle angegeben haben, werden alle angegebenen Werte in das Tabellenblatt geschrieben, beginnend mit dieser Zelle als Koordinate oben links. Wenn Sie stattdessen einen mehrzelligen Bereich angeben, müssen die angegebenen Werte genau in diesen Bereich passen. Andernfalls gibt die API einen Fehler zurück.