Wenn Sie bereits Apps auf Grundlage der Google Sheets API v3 haben, können Sie zur Google Sheets API v4 migrieren. Die Version 4 basiert auf JSON, hat eine benutzerfreundlichere Oberfläche und bietet eine Vielzahl von Funktionen, die in Version 3 nicht möglich sind.
Auf dieser Seite finden Sie eine Zuordnung zwischen den älteren Sheets API v3-Befehlen und den entsprechenden Vorgängen in der Sheets API v4. Die Zuordnung konzentriert sich hauptsächlich auf die Sammlung spreadsheets.values, die direkte Funktionen zum Lesen und Schreiben von Zellen bietet. Andere Aspekte, z. B. das Hinzufügen von Tabellenblättern oder das Aktualisieren von Tabellenblatteigenschaften, werden von der Sammlung spreadsheets verarbeitet. Die JSON-Strukturen der v4 API sind nicht abwärtskompatibel mit den XML-Strukturen, die in v3 verwendet werden.
Weitere Informationen zu den in der Sheets API v4 verfügbaren Ressourcen finden Sie in der API-Referenz.
Notation und Begriffe
In der v3 API werden Tabellenblätter in einer bestimmten Tabelle als „Arbeitsblätter“ bezeichnet. Dies ist synonym mit dem Begriff „Tabellen“, der in der v4-API verwendet wird.
Für die APIs müssen Sie häufig eine Tabellen-ID der Tabelle angeben, mit der Sie arbeiten. Häufig ist auch die ID des zu bearbeitenden Tabellenblatts erforderlich. Diese Werte werden entweder als Teil der API-Endpunkt-URL, als Abfrageparameter oder als Teil eines Anfragetextes angezeigt. Auf dieser Seite beziehen sich die Platzhalter spreadsheetId und sheetId auf die Tabellen- bzw. Tabellenblatt-IDs. Wenn Sie die auf dieser Seite beschriebenen Methoden verwenden, müssen Sie die tatsächlichen IDs an diesen Stellen einsetzen.
Mit der v3 API wird auch Zeilen, die mit dem List-Feed abgerufen werden, eine ID zugewiesen. Auf dieser Seite wird dies durch den Platzhalter rowId dargestellt.
Anfragen autorisieren
Wenn Ihre App ausgeführt wird, werden Nutzer aufgefordert, bestimmte Berechtigungen zu erteilen. Die Berechtigungen, die angefordert werden, hängen von den Bereichen ab, die Sie in Ihrer Anwendung angeben.
v3 API
Für die Sheets API v3 ist nur ein Autorisierungsbereich erforderlich:
https://spreadsheets.google.com/feeds
ein Alias für
https://www.googleapis.com/auth/spreadsheets
Beide Bereichsformate können verwendet werden.
v4 API
Für die Sheets API v4 werden einer oder mehrere 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 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 wird der Begriff visibility verwendet, um auf die Verfügbarkeit einer bestimmten Tabelle zu verweisen.
v3 API
In der Sheets API v3 wird die Sichtbarkeit direkt in den Endpunkten angegeben. Eine public-Tabelle wurde „Im Web veröffentlicht“ und kann daher ohne Autorisierung über die API aufgerufen werden. Für eine private-Tabelle ist hingegen 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 Sheets API v4 gibt es keine explizite Deklaration der Sichtbarkeit. API-Aufrufe erfolgen über Tabellen-IDs. Wenn die Anwendung keine Berechtigung für den Zugriff auf die angegebene Tabelle hat, wird ein Fehler zurückgegeben. Andernfalls wird der Anruf fortgesetzt.
Projektion
Der Begriff Projektion wird in der Sheets API v3 verwendet, um sich auf die Menge der Daten zu beziehen, die von einem bestimmten API-Aufruf zurückgegeben werden – entweder alle oder eine feste Teilmenge, die in der API definiert ist. Bei der Sheets API v4 wird keine Projektion verwendet. Stattdessen haben Sie mehr Kontrolle darüber, welche Daten zurückgegeben werden.
v3 API
In der Sheets 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 von Daten zurückgegeben wird (für die Arbeitsblatt-, Listen- und Zell-Feeds).
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 basic-Projektion bereitgestellt wird, ist nützlich, um Code effizienter zu gestalten, kann aber nicht angepasst werden.
v4 API
Mit der Sheets API v4 kann zwar ein vollständiger Datensatz zurückgegeben werden, es werden jedoch keine festen Teilmengen definiert, die der Sichtbarkeitseinstellung basic in der Sheets API v3 entsprechen.
Methoden in der spreadsheet-Sammlung beschränken die Menge der zurückgegebenen Daten durch die Verwendung eines fields-Abfrageparameters.
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
v3 API
Die Sheets API v3 bietet keine Möglichkeit, neue Tabellen zu erstellen. Stattdessen kann die Drive API-Methode „Files.create“ verwendet werden, um neue Tabellendateien zu erstellen. Dazu muss die Anwendung den Bereich https://www.googleapis.com/auth/drive deklarieren.
v4 API
Die Methode Drive API Files.create kann auch mit der Sheets API v4 verwendet werden. Dazu muss die Anwendung jedoch den Bereich https://www.googleapis.com/auth/drive angeben.
Als gleichwertige Alternative bietet die Sheets API v4 die Methode spreadsheets.create, mit der optional auch Tabellenblätter hinzugefügt, die Tabellen- und Tabellenblatteigenschaften festgelegt und benannte Bereiche hinzugefügt werden 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
Mit dem Sheets API v3-Feed kann eine Anwendung eine Liste aller Tabellen abrufen, auf die der authentifizierte Nutzer zugreifen kann. Der Endpunkt für den Tabellenfeed lautet:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
v4 API
Die Sheets API v4 bietet diesen speziellen Vorgang nicht. Wir empfehlen, Ihre App so zu migrieren, dass der Bereich „drive.file“ in Kombination mit der Google-Auswahl für die Tabellenauswahl verwendet wird.
Wenn Tabellen aufgelistet werden müssen, kann dies mit der Drive API-Methode „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 Bereich erforderlich.
Tabellenblatt-Metadaten abrufen
Die Sheets API v3 bietet einen Feed für den Zugriff auf die Tabellenmetadaten in einer bestimmten Tabelle. Auf Zeilen- und Zellendaten wird über einen separaten Feed zugegriffen. Die Metadaten enthalten Informationen wie Blattüberschriften und Größenangaben.
Die Methode spreadsheets.get der Sheets API v4 bietet Zugriff auf diese und viele weitere Informationen.
v3 API
Der Arbeitsblattfeed ist über diesen API-Endpunkt zugänglich (mit einem entsprechenden Autorisierungsheader):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
Die Antwort auf diese Anfrage hat eine ähnliche Struktur. Die Daten für jedes Tabellenblatt sind in einem separaten <entry> enthalten:
<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 Sie Tabelleneigenschaften und andere Metadaten abrufen, die weit über die Möglichkeiten der Sheets API v3 hinausgehen. Wenn Sie nur die Tabelleneigenschaften lesen möchten, setzen Sie den Abfrageparameter includeGridData auf false, um die Einbeziehung der Tabellenzellendaten zu verhindern:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
Die Spreadsheet-Antwort enthält ein Array von Sheet-Objekten. Die Blattüberschriften und Größeninformationen finden Sie im SheetProperties-Element 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 Blätter hinzufügen.
v3 API
Mit der Sheets API v3 können Sie einer Tabelle neue Arbeitsblätter hinzufügen, indem Sie die folgende (authentifizierte) POST-Anfrage senden. Sie können die Größe des neuen Tabellenblatts angeben:
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 Tabellenblätter hinzufügen, indem Sie in der 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 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 eines Tabellenblatts ändern
Mit der Sheets API v3 können Sie Tabellentitel und -größe aktualisieren. Die Sheets API v4 bietet diese Möglichkeit ebenfalls, kann aber auch zum Aktualisieren anderer Tabelleneigenschaften verwendet werden. Wenn Sie die Größe eines Tabellenblatts verringern, können Daten in den abgeschnittenen Zellen ohne Vorwarnung gelöscht werden.
v3 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>
v4 API
Wenn Sie die Größe, den Titel und andere Blatteigenschaften aktualisieren möchten, 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 Kurzform für die Auflistung aller Attribute. Im folgenden Beispiel wird angegeben, dass die Eigenschaften für den Blattnamen und die Blattgröße für das Blatt 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 eines Tabellenblatts abrufen möchten, verwenden Sie die Methode spreadsheets.get.
Tabellenblatt löschen
Mit beiden APIs können Tabellenblätter aus einer bestimmten Tabelle entfernt werden.
v3 API
Wenn Sie ein Arbeitsblatt löschen möchten, rufen Sie zuerst den Arbeitsblattfeed ab und senden Sie dann eine DELETE-Anfrage an die edit-URL des Zielarbeitsblatteintrags.
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 POST-Anfragetext 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.
Zeilendaten abrufen
Der Feed zum Auflisten von Zeilen ist eine der beiden Methoden, die die Sheets API v3 zum Zugriff auf Daten in den Zellen einer Tabelle bietet. Die andere Methode ist der Zellenfeed. Der Zeilenfeed soll gängige Tabellenkalkulationsvorgänge unterstützen (Zeile für Zeile lesen, Zeilen anhängen, sortieren), geht aber von bestimmten Annahmen aus, die ihn für einige Aufgaben ungeeignet machen. Im Listenfeed wird davon ausgegangen, dass leere Zeilen das Ende des Feeds darstellen und dass in der ersten Zeile eines Tabellenblatts obligatorische Überschriften vorhanden sind.
Im Gegensatz dazu werden in der Sheets API v4 keine zeilenspezifischen Zugriffsmethoden verwendet. Stattdessen wird auf Tabellenzellendaten zugegriffen, indem mit der A1-Notation auf die erforderlichen Bereiche verwiesen wird. Die Bereiche können Zellblöcke, ganze Zeilen, ganze Spalten oder ganze Tabellenblätter sein. Die API kann auch auf disjunkte Zellbereiche zugreifen.
v3 API
Wenn Sie die URL eines listenbasierten Feeds für ein bestimmtes Arbeitsblatt ermitteln möchten, rufen Sie den Arbeitsblattfeed ab und suchen Sie im gewünschten Arbeitsblatteintrag 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 entsprechenden 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 mit den Namen verwiesen, die in der (obligatorischen) Kopfzeile des Tabellenblatts 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 der Reihenfolge der Zeilen zurückgegeben. Die Sheets API v3 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:lastnameMit der Sheets API v3 können auch bestimmte Zeilen über eine strukturierte Abfrage (mit Spaltenüberschriften) gefiltert werden:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175v4 API
Mit der Sheets API v4 können Zeilen mithilfe der Methoden spreadsheets.values.get oder spreadsheets.values.batchGet nach Bereich abgerufen werden. Mit dem folgenden Befehl werden beispielsweise 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:
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}Nachfolgende leere Zellen sind nicht in der Antwort enthalten, wenn ganze Zeilen, Spalten oder Tabellen abgerufen werden.
Für die Abfrageparameter für die Zeilenreihenfolge, die von der Sheets API v3 bereitgestellt werden, gibt es in der Sheets API v4 keine Entsprechungen. Die umgekehrte Reihenfolge ist trivial. Verarbeiten Sie einfach das zurückgegebene values-Array in umgekehrter Reihenfolge. Die Sortierung nach Spalte wird für Lesevorgänge nicht unterstützt. Sie können die Daten jedoch im Tabellenblatt sortieren (mit einer SortRange-Anfrage) und sie dann lesen.
Für strukturierte Abfragen in der Sheets API v3 gibt es derzeit kein direktes Äquivalent in der Sheets API v4. Sie können die relevanten Daten jedoch abrufen und in Ihrer Anwendung nach Bedarf 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 Arbeitsblatt ermitteln möchten, rufen Sie den Arbeitsblattfeed ab und suchen Sie im gewünschten Arbeitsblattfeed nach der Post-URL.
Wenn Sie eine Datenzeile hinzufügen möchten, senden Sie eine POST-Anfrage an die Post-URL und verwenden Sie einen entsprechenden Autorisierungsheader. 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 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 Sheets API v4 können Sie Zeilen mit der Methode spreadsheets.values.append anhängen. Im folgenden Beispiel wird eine neue Datenzeile unter die letzte Tabelle in „Sheet1“ einer Tabelle geschrieben.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Mit der Sheets API v4 können Sie außerdem Zellen mit bestimmten Eigenschaften und Formatierungen anhängen. Verwenden Sie dazu die AppendCells-Anfragen in einem spreadsheets.batchUpdate-Vorgang.
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.
Sobald der Eintrag aktualisiert wurde, senden Sie eine PUT-Anfrage mit dem Eintrag als Anfragebody an die edit-URL, die in diesem Zeileneintrag angegeben ist. Verwenden Sie dazu einen entsprechenden 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 Sheets API v4 können Sie eine Zeile bearbeiten, indem Sie die A1-Notation der zu bearbeitenden Zeile verwenden und eine spreadsheets.values.update-Anfrage zum Überschreiben dieser Zeile senden. Der angegebene Bereich muss sich nur auf die erste Zelle in der Zeile beziehen. Die API leitet die zu aktualisierenden Zellen aus den mit der Anfrage bereitgestellten Werten ab. Wenn Sie stattdessen einen Bereich mit mehreren Zellen angeben, müssen die von Ihnen angegebenen Werte in diesen Bereich passen. Andernfalls gibt die API einen Fehler zurück.
Im folgenden Beispiel werden mit der Anfrage und dem Anfragetext Daten in die vierte Zeile von „Sheet1“ eingefü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 Zellen aktualisieren.
Mit der Sheets API v4 können Sie außerdem die Zelleigenschaften und die Formatierung von Zellen mit den Anfragen UpdateCells oder RepeatCell in einem 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 Zeile 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 wird.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Wenn Sie sichergehen möchten, dass Sie keine Zeile löschen, die seit dem Abrufen von einem anderen Client geändert wurde, fügen Sie einen HTTP-Header „If-Match“ mit dem ETag-Wert der ursprünglichen Zeile ein. Sie können den ETag-Wert der ursprünglichen Zeile ermitteln, indem Sie das Attribut „gd:etag“ des Eintrags untersuchen.
Wenn Sie die Zeile löschen möchten, unabhängig davon, ob sie seit dem Abrufen von jemand anderem aktualisiert wurde, verwenden Sie „If-Match: *“ und lassen Sie das ETag weg. In diesem Fall müssen Sie die Zeile nicht abrufen, bevor Sie sie löschen.
v4 API
Das Löschen von Zeilen mit der Sheets API v4 erfolgt durch einen spreadsheet.batchUpdate-Methodenaufruf mit einer DeleteDimension-Anfrage. Mit dieser Anfrage können auch Spalten entfernt werden. Entwickler können auch nur einen Teil einer Zeile oder Spalte entfernen. Im folgenden Beispiel wird die sechste Zeile eines Tabellenblatts mit der angegebenen ID entfernt. Die Zeilenindizes sind nullbasiert, wobei „startIndex“ eingeschlossen und „endIndex“ ausgeschlossen wird:
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. Für den Lesezugriff kann der Zellenfeed den gesamten Tabellenblattinhalt oder einen Bereich der Tabellenblattzellen liefern, der durch eine Reihe von Abfrageparametern definiert wird. Dies ist jedoch nur als einzelner Block möglich. Nicht zusammenhängende Bereiche müssen separat mit zusätzlichen GET-Anfragen abgerufen werden.
Mit der Sheets API v4 können beliebige Zellendaten aus einem Tabellenblatt abgerufen werden, auch aus mehreren disjunkten Bereichen. Die Sheets API v3 kann nur Zellinhalte als Eingabewerte (wie von einem Nutzer über die Tastatur eingegeben) und/oder die Ausgaben von Formeln (falls numerisch) zurückgeben. Die Sheets API v4 bietet vollständigen Zugriff auf Werte, Formeln, Formatierung, Hyperlinks, Datenvalidierung und andere Eigenschaften.
v3 API
Wenn Sie die URL eines zellenbasierten Feeds für ein bestimmtes Arbeitsblatt ermitteln möchten, sehen Sie sich den Arbeitsblattfeed an und suchen Sie im gewünschten Arbeitsblatt-Eintrag 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 entsprechenden Autorisierungsheader. Beispiel:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Auf Zellen wird über die Zeilen- und Spaltennummer verwiesen. Sie können einen einzelnen bestimmten Bereich abrufen, indem Sie die Abfrageparameter max-row, min-row, max-col und min-col verwenden. 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=4Die Sheets API v3 gibt den inputValue der abgerufenen Zellen zurück, also den Wert, den ein Nutzer 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 eine numericValue zurück, z. B. wenn eine Formel eine Zahl ergibt. Eine Antwort kann beispielsweise Zellen enthalten, die in ihrer Struktur den folgenden ähneln:
<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 Zellendaten ab, indem Sie die Methode spreadsheets.values.get oder spreadsheets.values.batchGet für den bzw. die gewünschten Bereiche aufrufen. Mit dem folgenden Beispiel werden die Zellen in Spalte D von „Sheet2“ ab Zeile 2 in spaltenweiser Reihenfolge zurückgegeben. Formeln werden so zurückgegeben, wie sie eingegeben wurden. Leere Zellen am Ende werden ausgelassen:
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:
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}Wenn Sie mehrere Bereiche mit Zellendaten abrufen möchten, ist es effizienter, spreadsheet.values.batchGet zu verwenden. Wenn Sie auf Zelleigenschaften wie die Formatierung zugreifen möchten, ist die Methode spreadsheet.get erforderlich.
Zelle bearbeiten
Mit der Sheets API v3 können Sie Zellinhalte bearbeiten, indem Sie einen PUT-Befehl an den Zellenfeed senden und den geänderten Zelleintrag als Anfragetext verwenden.
Die Sheets API v4 bietet dagegen die Methoden spreadsheets.values.update und spreadsheets.values.batchUpdate zum Ändern von Zellinhalten.
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 so, dass er den gewünschten Inhalt der Zelle widerspiegelt, und senden Sie dann eine PUT-Anfrage an die Bearbeitungs-URL mit dem aktualisierten Zelleneintrag als Text der Anfrage. Im folgenden Beispiel wird die Zelle D2 (R2C4) aktualisiert, sodass sie eine SUM-Formel 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>
v4 API
Einzelne Zellen können in der Sheets API v4 mit der Methode spreadsheets.values.update bearbeitet werden. Für diese Methode ist der Abfrageparameter ValueInputOption erforderlich, mit dem angegeben wird, ob die Eingabedaten so behandelt werden, als ob sie in die Benutzeroberfläche von Google Tabellen eingegeben wurden (USER_ENTERED), oder ob sie nicht geparst und unverändert übernommen werden (RAW). Im folgenden Beispiel wird die 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, verwenden Sie die Methode spreadsheets.values.batchUpdate, um die Änderungen in einer Anfrage zu senden.
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 sich eine Batchanfrage bezieht, müssen nicht in einem zusammenhängenden Bereich liegen.
Wenn einer oder mehrere der Zellbearbeitungen im Batch fehlschlagen, können andere mit der Sheets API v3 erfolgreich sein. Die Sheets API v4 gibt jedoch einen Fehler zurück, wenn einer der Batch-Updates fehlschlägt, und wendet in diesem Fall keinen der Updates an.
v3 API
Wenn Sie mehrere Zellen bearbeiten möchten, rufen Sie zuerst einen Zellenfeed für das Arbeitsblatt 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 dem neuen Zellinhalt. Die POST-Anfrage und der Anfragetext haben eine ähnliche Struktur wie die folgenden:
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 sein. gs:cell identifiziert die Zelle anhand der Zeilen- und Spaltennummer und enthält die neuen Daten, die dort eingefügt werden sollen. id enthält die vollständige URL der Zelle, die aktualisiert werden soll.
link muss ein href-Attribut mit dem vollständigen Pfad zur ID der Zelle haben. Alle diese Felder sind für jeden Eintrag erforderlich.
v4 API
Die Sheets API v4 bietet die Möglichkeit, Zellwerte mithilfe der Methode spreadsheets.values.batchUpdate im Batch zu bearbeiten.
Wenn Sie mehrere Zellen bearbeiten möchten, senden Sie eine POST-Anfrage mit den Datenänderungen im Anfragetext. 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, wobei diese Zelle als obere linke Koordinate dient. Wenn Sie stattdessen einen Bereich mit mehreren Zellen angeben, müssen die von Ihnen angegebenen Werte genau in diesen Bereich passen. Andernfalls gibt die API einen Fehler zurück.