Wenn Sie vorhandene Anwendungen haben, die auf der Google Sheets API Version 3 basieren, können Sie zu Google Sheets API Version 4 migrieren. Version 4 ist JSON-basiert, hat eine nutzerfreundlichere Oberfläche und bietet im Wesentlichen Funktionen, die in Version 3 nicht möglich sind.
Diese Seite enthält eine Zuordnung zwischen den älteren Befehlen der Sheets API v3 und den entsprechenden Vorgängen in der Sheets API v4. Der Schwerpunkt der Zuordnung liegt hauptsächlich 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 Tabellenblatteigenschaften werden von der Sammlung Tabellen verwaltet. Beachten Sie, dass die JSON-Strukturen der API V4 mit den in Version 3 verwendeten XML-Strukturen nicht abwärtskompatibel sind.
Weitere Informationen zu den in der Sheets v4 API verfügbaren Ressourcen finden Sie in der API-Referenz.
Notation und Begriffe
In Version 3 des APIs werden Blätter in einer bestimmten Tabelle als "Arbeitsblätter" bezeichnet. Dies ist ein Synonym für den Begriff "Tabellen", der im API v4 verwendet wird.
Die APIs erfordern häufig die Angabe einer Tabellen-ID der Tabelle, mit der Sie arbeiten. Häufig ist auch die ID des zu manipulierenden Tabellenblatts erforderlich. 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 jeweils auf die Tabellen- bzw. Tabellenblatt-IDs. Wenn Sie die auf dieser Seite beschriebenen Methoden verwenden, ersetzen Sie sie durch die tatsächlichen IDs an diesen Stellen.
Die API V3 weist Zeilen, die mithilfe ihres Listenfeeds abgerufen wurden, auch eine ID zu. Dies wird auf dieser Seite durch den Platzhalter rowId dargestellt.
Anfragen autorisieren
Wenn Ihre Anwendung ausgeführt wird, werden Nutzer aufgefordert, bestimmte Berechtigungen zu erteilen. Die Bereiche, die Sie in Ihrer Anwendung angeben, bestimmen, welche Berechtigungen angefordert werden.
Version 3 der API
Die Sheets API Version 3 nutzt einen einzelnen Autorisierungsbereich:
https://spreadsheets.google.com/feeds
ein Alias für
https://www.googleapis.com/auth/spreadsheets
Beide Bereichsformate können verwendet werden.
Version 4 API
Die Sheets API Version 4 verwendet mindestens einen der folgenden Bereiche:
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 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.
Version 3 der API
Die Sheets API Version 3 ermöglicht Sichtbarkeit direkt an ihren Endpunkten. Eine public-Tabelle wurde „im Web veröffentlicht“ und kann daher von der API ohne Autorisierung aufgerufen werden. Eine private-Tabelle erfordert hingegen eine Authentifizierung. Die Sichtbarkeit wird im Endpunkt nach der Tabellen-ID angegeben:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
Version 4 API
In der neuen Sheets API Version 4 gibt es keine explizite Erklärung zur Sichtbarkeit. API-Aufrufe erfolgen mithilfe von Tabellen-IDs. Wenn die Anwendung keine Berechtigung zum Zugriff auf die angegebene Tabelle hat, wird ein Fehler zurückgegeben. Andernfalls wird der Aufruf fortgesetzt.
Projektion
Der Begriff Projektion wird in der Sheets API Version 3 für den Datensatz verwendet, der von einem bestimmten API-Aufruf zurückgegeben wird – entweder alle oder eine feste Teilmenge, die in der API definiert ist. Bei der Sheets API Version 4 wird keine Projektion verwendet. Stattdessen können Sie damit besser steuern, welche Daten zurückgegeben werden.
Version 3 der API
In der Sheets API Version 3 gibt es nur zwei mögliche Projektionseinstellungen. Die Projektion full gibt alle verfügbaren Informationen zurück, während basic eine kleinere, feste Teilmenge von Daten (für die Arbeitsblätter, Listen und Zellenfeeds) zurückgibt.
Wie die Sichtbarkeit muss die Projektion im API-Endpunkt (nach der Sichtbarkeitseinstellung) angegeben werden:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
Die kleinere Teilmenge der Daten, die von der basic-Projektion bereitgestellt wird, ist nützlich, um den Code effizienter zu gestalten, kann jedoch nicht angepasst werden.
Version 4 API
Obwohl die Sheets API Version 4 einen vollständigen Datensatz zurückgeben kann, definiert sie keine festen Teilmengen analog zur Sichtbarkeitseinstellung basic in der Sheets API Version 3.
Methoden in der Tabellensammlung schränken die Datenmenge ein, die sie mithilfe des Abfrageparameters fields zurückgeben.
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
Die Sheets API Version 3 bietet keine Möglichkeit zum Erstellen neuer Tabellen. Stattdessen können Sie die Methode Drive API Files.create verwenden, um neue Tabellendateien zu erstellen. Dazu muss die Anwendung den Bereich https://www.googleapis.com/auth/drive deklarieren.
Version 4 API
Die Methode Drive API Files.create kann auch mit der Sheets API Version 4 verwendet werden, erfordert aber, dass die Anwendung den Bereich https://www.googleapis.com/auth/drive bereitstellt.
Als äquivalente Alternative bietet die Sheets API Version 4 die Methode spreadsheets.create, mit der optional auch Tabellenblätter hinzugefügt, die Eigenschaften der Tabelle und Tabelle festgelegt und benannte Bereiche hinzugefügt werden können. Im folgenden Beispiel wird 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
Version 3 der API
Mit dem Sheets API v3-Feed 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 API
Die Sheets API Version 4 bietet diesen speziellen Vorgang nicht. Wir empfehlen Ihnen, Ihre Anwendung so zu migrieren, dass der Bereich „drive.file“ in Kombination mit der Google-Auswahl für die Tabellenauswahl verwendet wird.
Wenn das Auflisten von Tabellen erforderlich ist, kann 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 die „files.list“-Methode der Drive API verwenden, um alle Tabellen eines Nutzers aufzulisten, benötigen Sie einen eingeschränkten Bereich.
Tabellenblatt-Metadaten abrufen
Die Sheets API Version 3 stellt einen Feed bereit, um auf die in einer bestimmten Tabelle enthaltenen Tabellenblattmetadaten zuzugreifen. Zeilen- und Zellendaten werden dabei über einen separaten Feed abgerufen. Die Metadaten enthalten Informationen wie Tabellenblatttitel und Größeninformationen.
Mit der Methode spreadsheets.get der Sheets API Version 4 erhalten 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 API
Mit der Methode spreadsheets.get können Sie Tabellenblatteigenschaften und andere Metadaten abrufen – weit mehr als mit der Sheets API Version 3. Wenn Sie nur die Tabellenblatteigenschaften lesen möchten, legen Sie den Abfrageparameter includeGridData auf false fest, um zu verhindern, dass die Zellendaten der Tabelle eingeschlossen werden:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
Die Spreadsheet-Antwort enthält ein Array mit Sheet-Objekten. Die Tabellenblatttitel und die Größenangaben 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
},
...
},
...
},
...
],
...
}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 Version 3 können Sie einer Tabelle neue Arbeitsblätter hinzufügen, indem Sie die folgende (authentifizierte) POST-Anfrage stellen. 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 API
Sie können neue Tabellenblätter hinzufügen, indem Sie mit 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 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 kann aber auch zum Aktualisieren anderer Tabellenblatteigenschaften verwendet werden. Das Reduzieren der Größe eines Tabellenblatts kann dazu führen, dass 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 den 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 API
Wenn Sie die Größe, den Titel und andere Tabellenblatteigenschaften aktualisieren möchten, stellen Sie in der Methode spreadsheets.batchUpdate eine updateSheetProperties-Anfrage. Der Text der POST-Anfrage 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 Kurzschreibweise für alle. Die folgende Eingabe gibt beispielsweise an, dass der Titel und die Größe 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)"
}
}
],
}
Die sheetId eines Tabellenblatts können Sie mit der Tabellenmethode spreadsheets.get abrufen.
Tabellenblätter 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 edit-URL des Zielarbeitsblatteintrags.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
Version 4 API
Um ein Tabellenblatt zu löschen, stellen Sie eine Anfrage DeleteSheet 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
}
}
],
}
Mit der Tabellenmethode spreadsheets.get können Sie die sheetId eines einzelnen Tabellenblatts abrufen.
Zeilendaten abrufen
Der Listenzeilenfeed ist eine der beiden Methoden, die von der Sheets API Version 3 bereitgestellt werden, um auf Daten in den Zellen einer Tabelle zuzugreifen. Die andere ist der Zellenfeed. Der Zeilenfeed soll gängige Tabellenkalkulationsvorgänge (Zeilen für Zeile lesen, Zeilen anfügen, Sortieren) unterstützen, setzt jedoch bestimmte Annahmen voraus, die ihn für einige Aufgaben ungeeignet machen. Insbesondere wird beim Listenfeed davon ausgegangen, dass leere Zeilen Feedtermine darstellen und dass in der ersten Zeile eines Tabellenblatts obligatorische Überschriften vorhanden sind.
Im Gegensatz dazu verwendet die Sheets API Version 4 keine zeilenspezifischen Zugriffsmethoden. Stattdessen erfolgt der Zugriff auf Tabellenblattdaten, indem auf die jeweiligen Bereiche verwiesen wird, die mithilfe der A1-Notation generiert werden müssen. Die Bereiche können Blöcke von Zellen, ganze Zeilen, ganze Spalten oder ganze Tabellenblätter sein. Die API kann auch auf disjunkte Gruppen von Zellen zugreifen.
Version 3 der API
Um die URL eines listenbasierten Feeds für ein bestimmtes Arbeitsblatt zu ermitteln, rufen Sie den Arbeitsblattfeed ab und suchen Sie die Listenfeed-URL im entsprechenden Arbeitsblatteintrag.
Senden Sie zum Abrufen eines listenbasierten Feeds eine GET-Anfrage mit einem entsprechenden Autorisierungsheader 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 die einzelnen Zellen wird durch die Namen in der (obligatorischen) Tabellenblatt-Kopfzeile verwiesen. Hier ist ein Beispiel für einen 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 Zeilenreihenfolge zurückgegeben. Die Sheets API Version 3 bietet Abfrageparameter, mit denen Sie diese Reihenfolge ändern können.
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 Sheets API Version 3 können Sie auch bestimmte Zeilen über eine strukturierte Abfrage filtern, 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 API
Mit der 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 sieht in etwa so aus:
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}
Leere nachgestellte Zellen sind beim Abrufen ganzer Zeilen, Spalten oder Tabellenblätter nicht in der Antwort enthalten.
Für die Sheets API Version 4 gibt es keine Entsprechungen für die Abfrageparameter der Sheets API Version 3, die Suchparameter für die Zeilenreihenfolge enthalten. Die umgekehrte Reihenfolge ist einfach. 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 im Tabellenblatt jedoch mit einer SortRange-Anfrage sortieren und dann lesen.
Für die Sheets API v4 gibt es derzeit keine direkte Entsprechung für strukturierte 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.
Version 3 der API
Um die URL eines listenbasierten Feeds für ein bestimmtes Arbeitsblatt zu ermitteln, rufen Sie den Arbeitsblattfeed ab und suchen Sie die Beitrags-URL im entsprechenden Arbeitsblatteintrag.
Wenn Sie eine Datenzeile hinzufügen möchten, senden Sie eine POST-Anfrage mit einem entsprechenden Autorisierungsheader an die Beitrags-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 mit einzelnen Zellen enthalten, auf die durch 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 an das Ende des angegebenen Tabellenblatts angehängt.
Version 4 API
Mit der Sheets API Version 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 „Sheet1“ einer Tabelle geschrieben.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
Außerdem haben Sie mit der Sheets API Version 4 auch die Möglichkeit, Zellen mit bestimmten Eigenschaften und Formatierungen mithilfe von AppendCells-Anfragen in spreadsheets.batchUpdate anzuhängen.
Zeile mit neuen Daten bearbeiten
Beide APIs ermöglichen das Aktualisieren von Zeilendaten mit neuen Werten.
Version 3 der API
Um eine Datenzeile zu bearbeiten, 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 in dem von Ihnen 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 in diesem 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 API
Mit der Sheets API Version 4 können Sie eine Zeile mit 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 in der Anfrage bereitgestellten Werte 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.
Mit der folgenden Beispielanfrage und dem folgenden 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. Diese Methode ist effizienter, wenn Sie mehrere Zeilen- oder Zellenaktualisierungen vornehmen.
Darüber hinaus können Sie mit der Sheets API Version 4 auch die Zelleneigenschaften und die Formatierung von Zellen bearbeiten. Verwenden Sie dazu die Anfragen UpdateCells oder RepeatCell in spreadsheets.batchUpdate.
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.
Version 3 der API
Wenn Sie eine Zeile löschen möchten, rufen Sie zuerst die zu löschende Zeile aus dem Listenfeed ab. Senden Sie dann eine DELETE-Anfrage an die URL edit, 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 verhindern möchten, dass eine Zeile gelöscht wird, die seit dem Abruf von einem anderen Client geändert wurde, fügen Sie einen HTTP-If-Match-Header ein, der den ETag-Wert der ursprünglichen Zeile enthält. Sie können den ETag-Wert der ursprünglichen Zeile mithilfe des Attributs gd:etag des Eintragselements ermitteln.
Wenn Sie die Zeile unabhängig davon löschen möchten, ob eine andere Person sie seit dem Abruf aktualisiert hat, verwenden Sie „If-Match: *“ und lassen Sie das ETag weg. In diesem Fall müssen Sie die Zeile vor dem Löschen nicht abrufen.
Version 4 API
Das Löschen von Zeilen mit der Sheets API Version 4 erfolgt über einen Methodenaufruf spreadsheet.batchUpdate mit der Anfrage DeleteDimension. Diese Anfrage kann auch zum Entfernen von Spalten verwendet werden und Entwickler können sich dafür entscheiden, 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 der startIndex inklusive und der endIndex ausgeschlossen sind):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}
Die sheetId eines Tabellenblatts können mit der Methode spreadsheet.get abgerufen werden.
Zellendaten abrufen
Die Sheets API Version 3 bietet einen Zellen-Feed für den Basiszugriff auf alle in einer Tabelle gespeicherten Daten. Für den Lesezugriff kann der Zellen-Feed den gesamten Tabellenblattinhalt oder einen Bereich der Zellen des Tabellenblatts bereitstellen, der durch einen Satz von Abfrageparametern definiert wird. Dies gilt jedoch nur als einzelner Block. Disjunkte Bereiche müssen separat mit zusätzlichen GET-Anfragen abgerufen werden.
Mit der Sheets API Version 4 können Sie einen beliebigen Satz von Zellendaten aus einem Tabellenblatt abrufen (einschließlich mehrerer disjunkter Bereiche). Die Sheets API v3 kann nur Zelleninhalte als Eingabewerte (wie bei der Eingabe durch einen Nutzer über eine Tastatur) und/oder die Ausgaben einer Formel (falls numerisch) zurückgeben. Die Sheets API v4 bietet vollständigen Zugriff auf Werte, Formeln, Formatierungen, Hyperlinks, Datenvalidierung und andere Eigenschaften.
Version 3 der API
Um die URL eines zellenbasierten Feeds für ein bestimmtes Arbeitsblatt zu ermitteln, sehen Sie sich den Arbeitsblattfeed an und suchen Sie die Zellenfeed-URL im entsprechenden Arbeitsblatteintrag.
Senden Sie zum Abrufen eines zellbasierten Feeds eine GET-Anfrage mit einem entsprechenden Autorisierungsheader an die Zellenfeed-URL. Beispiel:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Auf die Zellen wird mithilfe der Zeilen- und Spaltennummer verwiesen. Ein bestimmter Bereich kann mit den Abfrageparametern max-row, min-row, max-col und min-col abgerufen werden. Mit dem folgenden Befehl werden beispielsweise alle Zellen in Spalte 4 (D) abgerufen, beginnend mit Zeile 2:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4
Die Sheets API v3 gibt den inputValue der abgerufenen Zellen zurück. Das 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 einen numericValue zurück, z. B. wenn eine Formel zu einer Zahl führt. Eine Antwort kann beispielsweise Zelleneinträ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 API
Rufen Sie Zellendaten ab, indem Sie die Methode spreadsheets.values.get oder spreadsheets.values.batchGet für den oder die gewünschten Bereiche aufrufen. Das folgende Beispiel gibt die Zellen in Spalte D von „Sheet2“, beginnend mit Zeile 2, in Spaltenhauptreihenfolge zurück und gibt Formeln wie eingegeben zurück (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 die Verwendung von spreadsheet.values.batchGet effizienter. Wenn Sie auf Zelleneigenschaften wie die Formatierung zugreifen möchten, ist die Methode spreadsheet.get erforderlich.
Zelle bearbeiten
Mit der Sheets API Version 3 können Sie Zelleninhalte bearbeiten, indem Sie einen PUT-Befehl an den Zellenfeed senden, der den geänderten Zelleneintrag als Anfragetext enthält.
Die Sheets API Version 4 bietet hingegen die Methoden spreadsheets.values.update und spreadsheets.values.batchUpdate, um Zelleninhalte zu ändern.
Version 3 der API
Um den Inhalt einer einzelnen Zelle zu bearbeiten, suchen Sie zuerst im Zellfeed nach dem entsprechenden Eintrag der Zelle.
Der Eintrag enthält eine Bearbeitungs-URL. Aktualisieren Sie den Eintrag so, dass er den Inhalt der Zelle enthält, und senden Sie dann eine PUT-Anfrage an die Bearbeitungs-URL, wobei der aktualisierte Zelleneintrag als Text der Anfrage dient. Im folgenden Beispiel wird die Zelle D2 (R2C4) so aktualisiert, dass 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>
Version 4 API
In der Sheets API Version 4 können einzelne Zellen mit der Methode spreadsheets.values.update bearbeitet werden. Diese Methode erfordert einen ValueInputOption-Abfrageparameter, der angibt, ob die Eingabedaten so behandelt werden, als wären sie in die Google Tabellen-Benutzeroberfläche eingegeben (USER_ENTERED) oder nicht geparst und unverändert übernommen (RAW). Die folgende Zelle aktualisiert beispielsweise die Zelle D2 mit einer Formel:
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 Anfrage auszugeben.
Mehrere Zellen über die 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 bedingten Bereich befinden.
Wenn eine oder mehrere Zellenbearbeitungen im Batch fehlschlagen, können andere mit der Sheets API Version 3 erfolgreich ausgeführt werden. Die Sheets API Version 4 gibt jedoch einen Fehler zurück, wenn eine der Aktualisierungen im Batch fehlschlägt, und wendet in diesem Fall keinen Fehler an.
Version 3 der API
Um mehrere Zellen zu bearbeiten, 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, die in etwa so aussieht:
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 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 Zellen-ID enthält. Alle diese Felder sind für jeden Eintrag erforderlich.
Version 4 API
Die Sheets API Version 4 ermöglicht die Batch-Bearbeitung von Zellenwerten mit der Methode spreadsheets.values.batchUpdate.
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 eine einzelne Zelle als Bereich 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.