Grundlagen

Mit der Google Sheets API können Sie Werte aus Zellen, Bereichen, Gruppen von Bereichen und ganzen Tabellenblättern lesen. Die Beispiele auf dieser Seite veranschaulichen einige gängige Lesevorgänge mit der Ressource spreadsheets.values. Sie können Zellenwerte auch mit der Methode spreadsheets.get lesen. Normalerweise ist dies jedoch mit spreadsheets.values.get oder spreadsheets.values.batchGet einfacher.

Diese Beispiele werden in Form von HTTP-Anfragen präsentiert, um sprachneutral zu sein. Informationen zum Implementieren von Lesevorgängen in verschiedenen Sprachen mithilfe der Google API-Clientbibliotheken finden Sie unter Zellenwerte lesen und schreiben.

In diesen Beispielen gibt der Platzhalter SPREADSHEET_ID an, wo Sie die Tabellen-ID angeben müssen, die Sie der Tabellen-URL entnehmen können. Die auszulesenden Bereiche werden in der A1-Notation in der Anfrage-URL angegeben. Ein Beispielbereich ist Sheet1!A1:D5.

Quelldaten

Nehmen wir für diese Beispiele an, dass die gelesene Tabelle im ersten Tabellenblatt („Sheet1“) die folgenden Quelldaten enthält. Die Strings in der ersten Zeile sind Beschriftungen für die einzelnen Spalten. Beispiele für das Lesen aus anderen Tabellenblättern in Ihrer Tabelle finden Sie unter A1-Notation.

A B C D
1 Artikel Kosten Auf Lager Versanddatum
2 Wheel Riesenrad 20,50 $ 4 01.03.2016
3 Tür $15 2 15.03.2016
4 Engine 100 $ 1 20.03.2016
5 Summen 135,50 $ 7 20.03.2016

Einzelnen Bereich lesen

Im folgenden Codebeispiel spreadsheets.values.get wird gezeigt, wie die Werte aus dem Bereich Sheet1!A1:D5 gelesen werden und in der Antwort zurückgegeben werden. Leere nachgestellte Zeilen und Spalten werden ausgelassen.

Das Anfrageprotokoll wird hier angezeigt.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5

Die Antwort besteht aus dem Objekt ValueRange, das die Bereichswerte beschreibt. Das Feld majorDimension gibt an, dass die Arrays Listen von Werten sind, die nach Zeilen angeordnet sind.

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "3/1/2016"],
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "30/20/2016"],
    ["Totals", "$135.5", "7", "3/20/2016"]
  ],
}

Einzelnen nach Spalte gruppierten Bereich lesen

Das folgende Codebeispiel spreadsheets.values.get zeigt, wie die Werte aus dem Bereich Sheet1!A1:D3 gelesen werden und in der Antwort zurückgegeben, aber nach Spalte gruppiert werden. Leere nachgestellte Zeilen und Spalten werden ausgelassen.

Das Anfrageprotokoll wird hier angezeigt.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS

Die Antwort besteht aus dem Objekt ValueRange, das die Bereichswerte beschreibt. Das Feld majorDimension gibt an, dass die Arrays Listen von Werten sind, die nach Spalten organisiert sind.

{
  "range": "Sheet1!A1:D3",
  "majorDimension": "COLUMNS",
  "values": [
    ["Item", "Wheel", "Door"],
    ["Cost", "$20.50", "$15"],
    ["Stocked", "4", "2"],
    ["Ship Date", "3/1/2016", "3/15/2016"]
  ],
}

Einzelnen Bereich mit Renderingoptionen lesen

Das folgende Codebeispiel spreadsheets.values.get zeigt, wie die Werte aus dem Bereich „Sheet1!A1:D5“ gelesen werden und in der Antwort zurückgegeben werden. Es werden aber Renderingoptionen verwendet, um zu verwalten, wie diese Informationen zurückgegeben werden. Die Einstellung ValueRenderOption von FORMULA gibt an, dass Formeln anstelle des berechneten Werts zurückgegeben werden. Mit der Einstellung DateTimeRenderOption von SERIAL_NUMBER wird angegeben, dass Datumsangaben als Zahlen zurückgegeben werden sollen. Weitere Einstellungen sind ebenfalls möglich. Leere nachgestellte Zeilen und Spalten werden ausgelassen.

Das Anfrageprotokoll wird hier angezeigt.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?
            valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER

Die Antwort besteht aus dem Objekt ValueRange, das die Bereichswerte beschreibt. Das Feld majorDimension gibt an, dass die Arrays Listen von Werten sind, die nach Zeilen angeordnet sind.

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "42430"],
    ["Door", "$15", "2", "42444"],
    ["Engine", "$100", "1", "42449"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

Mehrere Bereiche lesen

Das folgende Codebeispiel spreadsheets.values.batchGet zeigt, wie Werte aus den Bereichen Sheet1!B:B und Sheet1!D:D gelesen und in der Antwort zurückgegeben werden. Die Einstellung UNFORMATTED_VALUE für ValueRenderOption gibt an, dass Werte berechnet, aber in der Antwort nicht formatiert werden. Leere nachgestellte Zeilen und Spalten werden ausgelassen.

Das Anfrageprotokoll wird hier angezeigt.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

Die Antwort auf diesen Methodenaufruf besteht aus einem Objekt mit der Tabellen-ID und einem Array von ValueRange-Objekten für jeden angeforderten Bereich, die in der Reihenfolge aufgelistet sind, in der sie angefordert wurden. Das Feld majorDimension gibt an, dass die Arrays Listen von Werten sind, die nach Spalten organisiert sind. Beispiel:

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "range": "Sheet1!B1:B1000",
      "majorDimension": "COLUMNS",
      "values": [
        ["Cost",20.5,15,100,135.5]
      ]
    },
    {
      "range": "Sheet1!D1:D1000",
      "majorDimension": "COLUMNS",
      "values": [
        ["Ship Date",42430,42444,42449,42449]
      ]s
    }
  ]
}

Mehrere Bereiche in mehreren Tabellenblättern lesen

Im folgenden Codebeispiel spreadsheets.values.batchGet wird gezeigt, wie Werte aus Bereichen in einem Tabellenblatt „Sheet1!A1:D5“, „Products!D1:D100“ und „Sales!E4:F6“ gelesen und in der Antwort zurückgegeben werden. Die Einstellung UNFORMATTED_VALUE für ValueRenderOption gibt an, dass Werte berechnet, aber in der Antwort nicht formatiert werden. Leere nachgestellte Zeilen und Spalten werden ausgelassen.

Das Anfrageprotokoll wird hier angezeigt.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!A1:D5&ranges=Products!D1:D100&ranges=Sales!E4:F6&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

Die Antwort auf diesen Methodenaufruf besteht aus einem Objekt mit der Tabellen-ID und einem Array von ValueRange-Objekten für jeden angeforderten Bereich, die in der Reihenfolge aufgelistet sind, in der sie angefordert wurden. Das Feld majorDimension gibt an, dass die Arrays Listen von Werten sind, die nach Spalten organisiert sind. Beispiel:

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "range": "Sheet1!A1:D5",
      "majorDimension": "COLUMNS",
      "values": [
        [...],
        [...]
      ]
    },
    {
      "range": "Products!D1:D100",
      "majorDimension": "COLUMNS",
      "values": [
        [...]
      ]
    },
    {
      "range": "Sales!E4:F6",
      "majorDimension": "COLUMNS",
      "values": [
        [...],
        [...]
      ]
    }
  ]
}