Von Sheets API Version 3 migrieren

Wenn Sie bereits Apps haben, die auf der Google Sheets API Version 3 basieren, können Sie Google Sheets API Version 4. Version 4 ist JSON-basiert und bietet eine nutzerfreundlichere und bietet einen wesentlichen Funktionsumfang, der nicht möglich ist, in Version 3.

Diese Seite enthält eine Zuordnung zwischen den Befehlen der älteren Sheets API v3 und ihren Operationen in Sheets API v4. Die Zuordnung konzentriert sich hauptsächlich spreadsheets.values die Funktion zum direkten Lesen und Schreiben von Zellen bietet. Andere Aspekte, z. B. das Hinzufügen von Tabellenblättern oder das Aktualisieren von Tabellenblatteigenschaften, werden vom Tabellen. Beachten Sie, dass die JSON-Strukturen der v4 API nicht abwärtskompatibel mit dem XML-Strukturen, die in Version 3 verwendet werden.

Weitere Informationen zu den Ressourcen, die in der Google Sheets v4 API verfügbar sind, 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 „Tabellenblätter“. die von der API v4 verwendet wird.

Die APIs erfordern häufig die Angabe einer Tabellen-ID. Tabelle, mit der Sie arbeiten. Häufig wird auch die ID des das Tabellenblatt bearbeitet wird. Diese Werte werden entweder als Teil des API-Endpunkts URL, als Suchparameter oder als Teil des Anfragetexts. Auf dieser Seite sehen Sie, Platzhalter spreadsheetId und sheetId sich auf die Tabellen- bzw. Tabellenblatt-IDs beziehen. Wenn Sie die Methoden die auf dieser Seite beschrieben sind, ersetzen Sie sie durch die tatsächlichen IDs an diesen Speicherorten.

Version 3 des APIs weist außerdem Zeilen, die mithilfe der Funktion list feed (Listenfeed) Dies wird auf dieser Seite durch den Platzhalter rowId dargestellt.

Anfragen autorisieren

Wenn Ihre App ausgeführt wird, werden Nutzer aufgefordert, bestimmte Berechtigungen zu erteilen. die Bereiche enthalten, 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 der Tabellen- oder Tabellenblatteigenschaften eines Nutzers. Verwenden Sie Tabellenumfänge anstelle von Drive-Bereiche, wenn die Anwendung keinen allgemeinen Drive-Zugriff benötigt.

Sichtbarkeit

In älteren Versionen der API wird der Begriff Sichtbarkeit für das Objekt Verfügbarkeit einer bestimmten Tabelle.

Version 3 der API

Die Sheets API Version 3 ermöglicht Sichtbarkeit direkt an ihren Endpunkten. Ein public Tabellenkalkulation heißt „Im Web veröffentlicht“ und kann von den Nutzern API nicht autorisiert, während für private-Tabellen Authentifizierung. Die Sichtbarkeit wird im Endpunkt nach der Tabellen-ID:

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 erhalten, wird ein Fehler zurückgegeben. Andernfalls wird der Anruf 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 alles oder eine feste Teilmenge die in der API definiert sind. Die Sheets API Version 4 verwendet keine Projektion. sondern vielmehr können Sie besser steuern, welche Daten zurückgegeben werden.

Version 3 der API

In der Sheets API Version 3 gibt es nur zwei mögliche Projektionseinstellungen. full Projektion gibt alle verfügbaren Informationen zurück, während basic eine kleinere, feste Teilmenge von Daten (für die Arbeitsblätter, Listen und Zellenfeeds). Wie die Sichtbarkeit muss die Projektion im API-Endpunkt angegeben werden (nach der Sichtbarkeitseinstellung):

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic

Die kleinere Teilmenge der Daten, die von der basic-Prognose bereitgestellt wird, ist wertvoll um Code effizienter zu gestalten, lässt sich jedoch nicht individuell anpassen.

Version 4 API

Die Sheets API Version 4 kann zwar einen vollständigen Datensatz zurückgeben, definiert aber keine festen Teilmengen analog zur basic-Sichtbarkeitseinstellung der Sheets API Version 3. Methoden in der Tabelle schränken die Menge der Daten ein, die sie aufgrund der Nutzung von Einen fields-Abfrageparameter.

Die folgende Abfrage gibt beispielsweise nur die Titel aller in einer bestimmten Tabellenkalkulation:

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, neue Tabellen zu erstellen. die Datei Drive API Files.create zum Erstellen neuer Tabellenkalkulationsdateien verwendet werden. Dazu ist die Anwendung, um den Bereich https://www.googleapis.com/auth/drive zu deklarieren.

Version 4 API

Die Methode Drive API Files.create kann folgende Aktionen ausführen: kann auch mit der Sheets API v4 verwendet werden, erfordert jedoch, dass die Anwendung den Bereich https://www.googleapis.com/auth/drive.

Als äquivalente Alternative bietet die Sheets API Version 4 eine spreadsheets.create mit der Sie optional Tabellenblätter hinzufügen, die Tabelle und das Tabellenblatt Eigenschaften und fügen benannte Bereiche hinzu. Mit dem folgenden Befehl wird z. B. ein neues und gibt ihr den Namen "NewTitle":

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, auf die der authentifizierte Nutzer zugreifen kann. Der Tabellen-Feed Endpunkt 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, Migrieren Sie Ihre Anwendung so, dass der Bereich „drive.file“ in Kombination mit dem Google-Auswahl für Tabellenauswahl.

In Fällen, in denen Tabellenkalkulationen benötigt werden, können diese reproduziert werden. Drive API-Methode „Files.list“ unter Verwendung von eine mimeType-Abfrage:

GET https://www.googleapis.com/drive/v3/files
             ?q=mimeType='application/vnd.google-apps.spreadsheet'

Mit der Drive API-Methode „files.list“ alle Tabellen eines Nutzers auflisten erfordert einen eingeschränkten Bereich.

Tabellenblatt-Metadaten abrufen

Die Sheets API Version 3 bietet einen Feed für den Zugriff auf die Tabellenblatt-Metadaten Tabellenkalkulationen enthalten (Zeilen- und Zellendaten werden über separaten Feed). Die Metadaten enthalten Informationen wie Blatttitel und Größeninformationen.

Sheets API v4 spreadsheets.get auf diese und weitere Informationen zugreifen.

Version 3 der API

Der Arbeitsblattfeed ist von diesem API-Endpunkt aus zugänglich (mithilfe eines entsprechenden Autorisierungsheader):

GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

Die Antwort auf diese Anfrage hat eine ähnliche Struktur wie diese, wobei die Daten jedes Tabellenblatts, die 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

Die Datei spreadsheets.get können Sie Tabellenblatteigenschaften und andere Metadaten abrufen, mehr als mit der Sheets API Version 3. Wenn Sie nur Tabellenblatteigenschaften lesen möchten, legen Sie die Abfrage includeGridData fest auf false setzen, damit die Zellendaten der Tabelle nicht eingeschlossen werden:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false

Die Spreadsheet Antwort enthält ein Array von Sheet Objekten; finden Sie die Tabellentitel und Größenangaben. unter SheetProperties -Elements 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 neue Arbeitsblätter zu einer Tabelle hinzugefügt werden, indem die nach (authentifizierter) POST-Anfrage. Sie können die Größe des Elements Neues Tabellenblatt:

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 AddSheet in spreadsheets.batchUpdate . Als Teil des Anfragetexts können Sie die Tabellenblatteigenschaften für auf das neue Tabellenblatt. Alle Eigenschaften sind optional. Die Angabe eines Titel, 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 Titel und Größe von Tabellenblättern aktualisieren. Sheets API v4 ermöglicht dies ebenfalls, kann aber auch zum Aktualisieren anderer Tabellenblatteigenschaften verwendet werden. Beachten Sie, dass das Verringern der Größe eines Tabellenblatts dazu führen kann, dass die Daten in den zugeschnittenen Zellen ohne Warnung gelöscht.

Version 3 der API

Um den Titel oder die Größe eines Arbeitsblatts zu ändern, rufen Sie als Erstes den Arbeitsblattfeed und Suchen des gewünschten Arbeitsblatteintrags, der eine edit-URL enthält. Die Metadaten des Arbeitsblatts aktualisieren und als Text einer PUT-Anfrage senden an die Bearbeitungs-URL an. 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

Um die Größe, den Titel und andere Tabellenblatteigenschaften zu aktualisieren, updateSheetProperties im Feld spreadsheets.batchUpdate . Der Text der POST-Anfrage sollte die Attribute enthalten, die geändert und der Parameter fields sollte diese Eigenschaften explizit auflisten. Wenn Sie alle Unterkünfte aktualisieren möchten, verwenden Sie fields:"*" als Abkürzung für alle aufführen). Für Beispiel: Titel und Größe des Tabellenblatts sollten für das Tabellenblatt mit der angegebenen ID aktualisiert werden:

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 in der Tabelle abrufen spreadsheets.get verwenden.

Tabellenblätter löschen

Beide APIs können Tabellenblätter aus einer bestimmten Tabelle entfernen.

Version 3 der API

Um ein Arbeitsblatt zu löschen, rufen Sie zunächst den Arbeitsblattfeed, dann Senden Sie 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, erstellen Sie DeleteSheet im Feld spreadsheets.batchUpdate . Der Text der POST-Anfrage sollte nur sheetId für den zu löschen. Beispiel:

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": sheetId
      }
    }
  ],
}

Um die sheetId eines einzelnen Tabellenblatts abzurufen, verwenden Sie die Tabelle spreadsheets.get .

Zeilendaten abrufen

Der Listenzeilenfeed ist eine der beiden Methoden, die die Sheets API Version 3 zur Verfügung stellt, um auf Daten in den Zellen einer Tabelle zugreifen (die andere ist der Zellenfeed). Die Zeilenfeed unterstützt gängige Tabellenkalkulationsvorgänge (Zeilen für Zeilen, das Anfügen von Zeilen oder das Sortieren von Daten), aber es geht von bestimmten Annahmen aus, die sie ungeeignet machen. für bestimmte Aufgaben. Insbesondere wird beim Listenfeed davon ausgegangen, dass leere Zeilen Feedelemente enthalten und dass obligatorische Überschriften in der ersten Zeile eines Tabellenblatt.

Im Gegensatz dazu verwendet die Sheets API v4 keine Zugriffsmethoden, die zeilenspezifisch. Stattdessen wird der Zugriff auf die Daten in den Blattzellen über den spezifischen die in der A1-Notation erforderlich sind. 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 Arbeitsblattfeed und finden Sie die Listen-Feed-URL im entsprechenden Arbeitsblatteintrag.

Zum Abrufen eines listenbasierten Feeds senden Sie eine GET-Anfrage an die Listenfeed-URL. mit einem 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. Einzelne Zellen werden durch die in der Kopfzeile des Tabellenblatts angegebenen Namen. Hier ein Beispiel ist ein einzeiliger Eintrag:

<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

Die Sheets API Version 3 ermöglicht auch das Filtern bestimmter Zeilen über eine strukturierte Abfrage (durch Spaltenüberschriften referenziert):

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?sq=age>25%20and%20height<175

Version 4 API

Mit der Sheets API v4 können Zeilen mithilfe der Funktion spreadsheets.values.get oder spreadsheets.values.batchGet . 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"]]
}

Nachgestellte leere Zellen sind beim Abrufen ganzer Zellen nicht in der Antwort enthalten. Zeilen, Spalten oder Tabellenblättern.

Die Sheets API Version 4 hat keine Entsprechungen für die Abfrage der Zeilenreihenfolge -Parameter, die von der Sheets API Version 3 bereitgestellt werden. Die umgekehrte Reihenfolge ist einfach. einfach Das zurückgegebene values-Array wird in umgekehrter Reihenfolge verarbeitet. „Sortieren nach Spalte“ ist nicht wird für Lesevorgänge unterstützt, aber es ist möglich, die Daten auf dem Blatt SortRange) 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 in Ihrer Anwendung nach Bedarf 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 Arbeitsblattfeed und finden Sie die Post-URL im entsprechenden Arbeitsblatteintrag.

Um eine Datenzeile hinzuzufügen, senden Sie eine POST-Anfrage an die Beitrags-URL, mit einem 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 Zeilendaten enthalten, um addieren, 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 API

Mit der Sheets API Version 4 können Sie Zeilen mithilfe der spreadsheets.values.append . Im folgenden Beispiel wird eine neue Datenzeile unterhalb der letzten Tabelle in „Sheet1“ einer Tabellenkalkulation. 

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1

{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

Außerdem können Sie mit der Sheets API Version 4 auch Zellen anhängen, Eigenschaften und Formatierungen mithilfe der AppendCells in einer spreadsheets.batchUpdate.

Zeile mit neuen Daten bearbeiten

Beide APIs ermöglichen das Aktualisieren von Zeilendaten mit neuen Werten.

Version 3 der API

Wenn Sie eine Datenzeile bearbeiten möchten, prüfen Sie den Listenfeed. um den Eintrag für die Zeile zu finden, die Sie aktualisieren möchten. Aktualisieren Sie den Inhalt von diesen Eintrag nach Bedarf hinzufügen. Achten Sie darauf, dass der ID-Wert in dem Eintrag, den Sie verwenden, 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 an, die in diesem Zeileneintrag angegeben ist, mit einem 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>

Version 4 API

Mit der Sheets API Version 4 können Sie eine Zeile mithilfe der Funktion A1-Notation der Zeile, die Sie hinzufügen möchten. bearbeiten und eine spreadsheets.values.update -Anforderung zum Überschreiben dieser Zeile. Der angegebene Bereich muss sich nur auf die in der Zeile beginnen. leitet die API die zu aktualisierenden Zellen anhand des -Werte enthalten. Wenn Sie stattdessen einen mehrzelligen Bereich angeben, die von Ihnen angegebenen Werte müssen in diesen Bereich fallen. gibt die API eine Fehlermeldung aus, Fehler.

Mit der folgenden Beispielanfrage und dem folgenden Anfragetext werden Daten zum vierte Zeile von „Sheet1“:

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

Sie können Zeilendaten auch über die spreadsheet.values.batchUpdate . ist es effizienter, diese Methode zu verwenden, wenn Sie mehrere oder Zellen aktualisieren.

Darüber hinaus können Sie mit der Sheets API Version 4 auch die Zelleneigenschaften und Formatierung von Zellen mithilfe der UpdateCells oder RepeatCell in einer spreadsheets.batchUpdate.

Zeile löschen

Beide APIs unterstützen das Löschen von Zeilen. Eine gelöschte Zeile wird aus dem Zeilen darunter werden um eins nach oben verschoben.

Version 3 der API

Um eine Zeile zu löschen, rufen Sie zunächst die zu löschende Zeile aus dem Listenfeed, 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 sicherstellen möchten, dass Sie keine geänderte Zeile löschen von einem anderen Client gesendet haben, da Sie sie abgerufen haben, fügen Sie einen HTTP-If-Match-Header ein. die den ETag-Wert der ursprünglichen Zeile enthält. Sie können die ursprüngliche den ETag-Wert der Zeile durch Überprüfen des gd:etag-Attributs des Eintragselements.

Wenn Sie die Zeile unabhängig davon löschen möchten, ob eine andere Person sie aktualisiert hat da Sie sie abgerufen haben, 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 eine Tabelle mit der Bezeichnung spreadsheet.batchUpdate Methodenaufruf mit einer DeleteDimension-Methode Diese Anfrage kann auch zum Entfernen von Spalten verwendet werden. und wählen Sie aus, dass nur ein Teil einer Zeile oder Spalte entfernt werden soll. Beispiel: Der Parameter entfernt die sechste Zeile eines Tabellenblatts mit der angegebenen ID (die Zeilenindizes sind nullbasiert, wobei startIndex einschließlich und endIndex ausgeschlossen ist):

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
  "requests": [
    {
      "deleteDimension": {
        "range": {
          "sheetId": sheetId,
          "dimension": "ROWS",
          "startIndex": 5,
          "endIndex": 6
        }
      }
    }
  ],
}

Die sheetId eines Tabellenblatts können mithilfe der spreadsheet.get-Methode.

Zellendaten abrufen

Die Sheets API v3 bietet einen Zell-Feed für den Basiszugriff auf alle Daten, die in einem Tabelle. Für den Lesezugriff kann der Zellen-Feed das gesamte Tabellenblatt bereitstellen oder einem Zellenbereich der Tabelle, der durch eine Reihe von Suchparametern definiert ist, aber nur als einzelnen Block – disjunkte Bereiche müssen abgerufen werden separat durch zusätzliche GET-Anfragen.

Mit der Sheets API v4 können beliebige Gruppen von Zellendaten aus einem Tabellenblatt abgerufen werden, einschließlich mehrere disjunkte Bereiche). Die Sheets API v3 kann nur Zelleninhalte in folgender Form zurückgeben: Eingabewerte (wie sie von einem Nutzer über eine Tastatur eingegeben werden) und/oder Formel (falls numerisch); Die Sheets API v4 ermöglicht 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, Arbeitsblattfeed und suchen Sie die Zell-Feed-URL im entsprechenden Arbeitsblatteintrag.

Um einen zellbasierten Feed abzurufen, senden Sie eine GET-Anfrage an die Zellenfeed-URL. mit einem entsprechenden Autorisierungsheader. Beispiel:

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full

Auf die Zellen wird mithilfe der Zeilen- und Spaltennummer verwiesen. Das Abrufen einer einzelnen spezifischen Bereich kann mit max-row, min-row, max-col und min-col erstellt werden Suchparametern. Mit dem folgenden Befehl werden beispielsweise alle Zellen in der Spalte 4 (D), 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 die inputValue der abgerufenen Zellen zurück, also den Wert, den ein Nutzer andernfalls in den Google Tabellen-Nutzer eingeben würde zur Bearbeitung der Zelle. inputValue kann ein Literalwert sein oder eine Formel. Die API gibt manchmal auch numericValue zurück. zum Beispiel wenn eine Formel zu einer Zahl führt. Eine Antwort kann beispielsweise folgende Zellen enthalten: Einträge, deren Struktur in etwa so aussieht:

<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 eine spreadsheets.values.get oder spreadsheets.values.batchGet für den jeweiligen Bereich bzw. die Bereiche von Interesse. Beispiel: Der Parameter werden die Zellen in Spalte D von Sheet2 zurückgegeben, beginnend mit Zeile 2, in Spalten-Hauptreihenfolge und Rückgabe von Formeln wie eingegeben (nachgestelltes leeres Zellen ausgelassen werden):

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"]]
      }]
}

Es ist effizienter, spreadsheet.values.batchGet wenn Sie mehrere Zelldatenbereiche abrufen möchten. Wenn Sie auf Zelleneigenschaften wie die Formatierung, die spreadsheet.get ist erforderlich.

Zelle bearbeiten

Mit der Sheets API Version 3 können Sie Zelleninhalte bearbeiten, indem Sie einen PUT-Befehl für den Zellen-Feed mit dem geänderten Zelleneintrag als Anfragetext.

Die Sheets API Version 4 bietet dagegen 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 zunächst den entsprechenden Eintrag in der Zellfeed. Der Eintrag enthält eine Bearbeitungs-URL. Aktualisieren Sie den Eintrag entsprechend. die die Zelle haben soll, und senden Sie dann eine PUT-Anfrage an die Bearbeitungs-URL. mit dem aktualisierten Zelleneintrag als Textkörper der Anfrage. Beispiel: Der Parameter Mit dem folgenden Code 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>

Version 4 API

Das Bearbeiten einzelner Zellen in der Sheets API v4 kann mit der spreadsheets.values.update . Diese Methode erfordert einen ValueInputOption-Abfrageparameter, der gibt an, ob die Eingabedaten so behandelt werden, als wären sie in das Benutzeroberfläche von Google Tabellen (USER_ENTERED) oder nicht geparst und so übernommen (RAW). Für Im folgenden 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 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 Änderungen am Inhalt mehrerer Zellen vorgenommen werden mit einer einzelnen (Batch-)Anfrage. Die Zellen, auf die in einer Batchanfrage Bezug genommen wird, sind darf nicht in einem bestimmten Bereich liegen.

Wenn eine oder mehrere Zellenbearbeitungen im Batch fehlschlagen, können andere mit der Sheets API Version 3 erfolgreich ausgeführt werden. Die Sheets API v4 gibt jedoch einen Fehler zurück. wenn eine der Batch-Updates fehlschlägt und in diesem Fall keine davon angewendet wird.

Version 3 der API

Wenn Sie mehrere Zellen bearbeiten möchten, rufen Sie zuerst einen Zellenfeed auf. für das Arbeitsblatt. Der Eintrag enthält eine Batch-URL. POST senden an diese URL gesendet werden, zusammen mit einem Anfragetext, der die Zellen beschreibt, die Sie aktualisieren möchten, und den neuen Zelleninhalt. 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 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 um sie dort einzufügen. id enthält die vollständige URL der Zelle, die aktualisiert werden soll. link muss ein href-Attribut haben, das den vollständigen Pfad zum Zellen-ID ein. Alle diese Felder sind für jeden Eintrag erforderlich.

Version 4 API

Die Sheets API Version 4 ermöglicht die Batch-Bearbeitung von Zellenwerten über die spreadsheets.values.batchUpdate .

Wenn Sie mehrere Zellen bearbeiten möchten, senden Sie eine POST-Anfrage mit dem Parameter Datenänderungen, die im Anfragetext angegeben sind. Beispiel:

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{
  "valueInputOption": "USER_ENTERED"
  "data": [
       {"range": "D4",
        "majorDimension": "ROWS",
        "values": [["newData"]]
       },
       {"range": "B5",
        "majorDimension": "ROWS",
        "values": [["moreInfo"]]
       }
  ]
}

Wenn Sie eine einzelne Zelle als Bereich angegeben haben, sind alle angegebenen Werte beginnend mit dieser Zelle als Koordinate oben links in das Blatt geschrieben. Wenn Sie stattdessen einen mehrzelligen Bereich angeben, müssen die angegebenen Werte der Bereich genau entspricht. Andernfalls gibt die API einen Fehler zurück.