Grundkenntnisse

Mit der Google Tabellen API können Sie Werte und Formeln in Zellen, Bereiche, Bereichsgruppen und ganze Tabellen schreiben. Die Beispiele auf dieser Seite veranschaulichen, wie einige gängige Schreibvorgänge mit der spreadsheets.values-Ressource der Google Tabellen API ausgeführt werden können.

Zellenwerte können auch mit der Methode spreadsheet.batchUpdate geschrieben werden. Das kann nützlich sein, wenn Sie gleichzeitig die Zellenformatierung oder andere Eigenschaften aktualisieren möchten, auf die sich die spreadsheets.values-Ressource nicht auswirkt. Wenn Sie beispielsweise einen Zellenbereich von einem Tabellenblatt in ein anderes kopieren und dabei sowohl die Zellformel als auch die Zellformatierung überschreiben möchten, können Sie die Methode UpdateCellsRequest mit einer spreadsheet.batchUpdate verwenden.

Für einfache Wertzugriffe ist es jedoch einfacher, die Methode spreadsheets.values.update oder spreadsheets.values.batchUpdate zu verwenden.

Diese Beispiele werden in Form von sprachneutralen HTTP-Anfragen präsentiert. Informationen zum Implementieren von Schreibvorgä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. Diese finden Sie in der Tabellen-URL. Die Bereiche, in die geschrieben werden soll, werden in A1-Notation angegeben. Ein Beispielbereich ist Sheet1!A1:D5.

Einzelnen Bereich schreiben

Im folgenden spreadsheets.values.update-Codebeispiel wird veranschaulicht, wie Sie die Werte in einen Bereich schreiben, wenn Sie mit einer neuen, leeren Tabelle beginnen. Der Abfrageparameter ValueInputOption ist erforderlich und bestimmt, ob die geschriebenen Werte geparst werden (z. B. ob ein String in ein Datum umgewandelt wird).

Der Anfragetext ist ein ValueRange-Objekt, das zu schreibende Bereichswerte beschreibt. Das Feld majorDimension gibt an, dass die Arrays Listen von Werten sind, die nach Zeilen organisiert sind. Vorhandene Werte im Zielbereich werden überschrieben.

Das Anfrageprotokoll ist unten dargestellt.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION

{
  "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", "3/20/2016"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

Die Antwort besteht aus einem UpdateValuesResponse-Objekt, z. B. diesem:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

Das Ergebnis sieht so aus:

Selektiv in einen Bereich schreiben

Wenn Sie Werte in einen Bereich schreiben, können Sie verhindern, dass einige vorhandene Zellen geändert werden, indem Sie die entsprechenden Arrayelemente auf null festlegen. Sie können eine Zelle auch löschen, indem Sie einen leeren String ("") in sie schreiben.

In diesem Beispiel wird ein Tabellenblatt mit denselben Daten verwendet, die im obigen Beispiel erstellt wurden. Im folgenden spreadsheets.values.update-Codebeispiel wird gezeigt, wie die Werte in den Bereich B1:D4 geschrieben werden, wobei einige Zellen beibehalten und andere gelöscht werden. Der Abfrageparameter ValueInputOption ist erforderlich und bestimmt, ob die geschriebenen Werte geparst werden (z. B. ob ein String in ein Datum umgewandelt wird).

Der Anfragetext ist ein ValueRange-Objekt, das die zu schreibenden Bereichswerte beschreibt. Das Feld majorDimension gibt an, dass die Arrays Listen von Werten sind, die nach Spalten sortiert sind.

Das Anfrageprotokoll ist unten zu sehen.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!B1",
  "majorDimension": "COLUMNS",
  "values": [
    [null,"$1","$2", ""],
    [],
    [null,"4/1/2016", "4/15/2016", ""]
  ]
}

Im Feld values werden die Änderungen aufgelistet, die an den einzelnen Spalten des Bereichs vorgenommen wurden. Das erste Array gibt an, dass B1 unverändert bleiben soll (aufgrund des Arrayelements null), während B4 gelöscht werden soll (leerer String). Die Werte in B2 und B3 wurden aktualisiert. Das dritte Array führt die gleichen Operationen für Spalte D durch, während das zweite leere Array anzeigt, dass Spalte C unverändert bleiben soll.

Die Antwort besteht aus einem UpdateValuesResponse-Objekt, z. B. diesem:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

Das Ergebnis sieht so aus:

Beachten Sie, dass sich die Zeile "Gesamt" zwar nicht direkt durch diese Anfrage geändert hat, sich aber ändert, da ihre Zellen Formeln enthalten, die von den geänderten Zellen abhängen.

In mehrere Bereiche schreiben

Im folgenden Codebeispiel für spreadsheets.values.batchUpdate sehen Sie, wie die Werte in die Bereiche Sheet1!A1:A4 und Sheet1!B1:D2 geschrieben werden. Dabei wird ein leeres Tabellenblatt verwendet. Vorhandene Werte im Zielbereich werden überschrieben. Der Anfragetext besteht aus einem ValueInputOption-Objekt, das zeigt, wie die Eingabedaten zu interpretieren sind, und einem Array von ValueRange-Objekten, die den einzelnen geschriebenen Bereichen entsprechen. Das Feld majorDimension bestimmt, ob die enthaltenen Arrays als Arrays von Spalten oder Zeilen interpretiert werden.

Das Anfrageprotokoll ist unten dargestellt.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchUpdate

{
  "valueInputOption": "VALUE_INPUT_OPTION",
  "data": [
    {
      "range": "Sheet1!A1:A4",
      "majorDimension": "COLUMNS",
      "values": [
        ["Item", "Wheel", "Door", "Engine"]
      ]
    },
    {
      "range": "Sheet1!B1:D2",
      "majorDimension": "ROWS",
      "values": [
        ["Cost", "Stocked", "Ship Date"],
        ["$20.50", "4", "3/1/2016"]
      ]
    }
  ]
}

Die Antwort besteht aus einem Objekt mit den aktualisierten Zellenstatistiken und einem Array von UpdateValuesResponse-Objekten, jeweils eines für jeden aktualisierten Bereich. Beispiel:

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 4,
  "totalUpdatedColumns": 4,
  "totalUpdatedCells": 10,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!A1:A4",
      "updatedRows": 4,
      "updatedColumns": 1,
      "updatedCells": 4,
    },
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!B1:D2",
      "updatedRows": 2,
      "updatedColumns": 3,
      "updatedCells": 6,
    }
  ],
}

Das Ergebnis sieht so aus:

Werte ohne Parsen schreiben

Im folgenden spreadsheets.values.update-Codebeispiel wird gezeigt, wie Werte in ein leeres Tabellenblatt geschrieben werden. Dabei wird der Abfrageparameter RAW ValueInputOption verwendet, um zu verhindern, dass die geschriebenen Strings als Formeln, Boolesche Werte oder Zahlen geparst werden. Sie werden als Strings angezeigt und der Text ist im Tabellenblatt linksbündig ausgerichtet.

Der Anfragetext ist ein ValueRange-Objekt, das die zu schreibenden Bereichswerte beschreibt. Das Feld majorDimension gibt an, dass die Arrays Listen von Werten sind, die nach Zeilen organisiert sind. Vorhandene Werte im Zielbereich werden überschrieben.

Das Anfrageprotokoll ist unten dargestellt.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Data", 123.45, true, "=MAX(D2:D4)", "10"]
  ],
}

Die Antwort besteht aus einem UpdateValuesResponse-Objekt wie diesem:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

Das resultierende Tabellenblatt sieht so aus:

Beachten Sie, dass „TRUE“ (WAHR) zentriert ist und ein boolescher Wert ist, während „123.45“ rechtsbündig ausgerichtet ist, da es sich um eine Zahl handelt, und „10“ linksbündig, da es sich um einen String handelt. Die Formel wird nicht geparst und wird ebenfalls als String angezeigt.

Werte anhängen

Beginnen Sie mit einem Tabellenblatt wie der folgenden Tabelle:

Im folgenden Codebeispiel mit spreadsheets.values.append wird gezeigt, wie Sie zwei neue Zeilen mit Werten hinzufügen, beginnend mit Zeile 3. Der Abfrageparameter ValueInputOption ist erforderlich und bestimmt, ob die geschriebenen Werte geparst werden (z. B. ob ein String in ein Datum umgewandelt wird).

Der Anfragetext ist ein ValueRange-Objekt, das die zu schreibenden Bereichswerte beschreibt. Das Feld majorDimension gibt an, dass die Arrays Listen von Werten sind, die nach Zeilen organisiert sind.

Das Anfrageprotokoll ist unten dargestellt.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
  ],
}

Die Antwort besteht aus einem AppendValuesResponse-Objekt, z. B. diesem:

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

Das resultierende Tabellenblatt sieht so aus: