Grundlagen

Mit der Google Tabellen API können Sie Werte aus Zellen, Bereichen, Bereichsgruppen und ganzen Tabellen 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 auslesen. In der Regel ist dies jedoch einfacher spreadsheets.values.get oder spreadsheets.values.batchGet.

Diese Beispiele werden in Form von HTTP-Anfragen dargestellt, um sprachenunabhängig zu sein. Informationen zum Implementieren von Lesevorgängen in verschiedenen Sprachen mit den 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 würden. Sie finden sie in der Tabellen-URL. Die zu lesenden Bereiche werden in der Anfrage-URL in A1-Notation angegeben. Ein Beispiel für einen Bereich ist Tabelle1!A1:D5.

Quelldaten

Für diese Beispiele wird davon ausgegangen, dass die gelesene Tabelle die folgenden Quelldaten im ersten Tabellenblatt („Sheet1“) enthält. Die Strings in der ersten Zeile sind Labels für die einzelnen Spalten. Beispiele zum Lesen aus anderen Tabellen in Ihrer Tabelle finden Sie unter A1-Notation.

A B C D
1 Element Kosten Bestückt 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 Gesamt 135,5 $ 7 20.03.2016

Einzelnen Bereich lesen

Im folgenden spreadsheets.values.get-Codebeispiel wird gezeigt, wie die Werte aus dem Bereich „Tabelle1!A1:D5“ gelesen und in der Antwort zurückgegeben werden. Leere Zeilen und Spalten am Ende werden weggelassen.

Das Anfrageprotokoll wird hier angezeigt.

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

Die Antwort besteht aus einem ValueRange-Objekt, das die Werte des Bereichs beschreibt. Das Feld majorDimension gibt an, dass die Arrays Listen von Werten sind, die nach Zeilen organisiert 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 Bereich lesen, der nach Spalte gruppiert ist

Im folgenden spreadsheets.values.get-Codebeispiel wird gezeigt, wie die Werte aus dem Bereich „Tabelle1!A1:D3“ gelesen und in der Antwort zurückgegeben werden, aber nach Spalte gruppiert. 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 einem ValueRange-Objekt, das die Werte des Bereichs 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

Im folgenden Codebeispiel spreadsheets.values.get wird gezeigt, wie die Werte aus dem Bereich „Tabelle1!A1:D5“ gelesen und in der Antwort zurückgegeben werden. Dabei werden aber Rendering-Optionen verwendet, um festzulegen, wie diese Informationen zurückgegeben werden. Die Einstellung ValueRenderOption von FORMULA gibt an, dass anstelle des berechneten Werts Formeln zurückgegeben werden sollen. Die Einstellung DateTimeRenderOption von SERIAL_NUMBER gibt an, dass Datumsangaben als Zahlen zurückgegeben werden sollen. Andere Einstellungen sind ebenfalls möglich. Leere Zeilen und Spalten am Ende werden weggelassen.

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 einem ValueRange-Objekt, das die Werte des Bereichs beschreibt. Das Feld majorDimension gibt an, dass die Arrays Listen von Werten sind, die nach Zeilen organisiert 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 für 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 ValueRenderOption-Einstellung von UNFORMATTED_VALUE gibt an, dass Werte berechnet, aber nicht in der Antwort formatiert werden. Leere Zeilen und Spalten am Ende werden weggelassen.

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, die jedem angeforderten Bereich in der Reihenfolge entsprechen, in der sie angefordert wurden. Das Feld majorDimension gibt an, dass die Arrays Listen von Werten sind, die nach Spalten sortiert 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 spreadsheets.values.batchGet-Codebeispiel wird gezeigt, wie Werte aus den Bereichen in den Tabellen „Tabelle1!A1:D5“, „Produkte!D1:D100“ und „Umsätze!E4:F6“ gelesen und in der Antwort zurückgegeben werden. Die ValueRenderOption-Einstellung von UNFORMATTED_VALUE gibt an, dass Werte berechnet, aber nicht in der Antwort formatiert werden. Leere nachgestellte Zeilen und Spalten werden weggelassen.

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, die dem jeweiligen Bereich entsprechen. Die Objekte sind in der Reihenfolge aufgelistet, 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": [
        [...],
        [...]
      ]
    }
  ]
}