Grundkenntnisse

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

Sie können Zellwerte auch mit der spreadsheet.batchUpdate Methode schreiben. Das ist nützlich, wenn Sie gleichzeitig die Zellformatierung oder andere Eigenschaften aktualisieren möchten, die von der spreadsheets.values Ressource nicht betroffen sind. Wenn Sie beispielsweise einen Zellbereich aus einer Tabelle in eine andere kopieren und dabei sowohl die Zellformel als auch die Zell formatierung überschreiben möchten, können Sie die UpdateCellsRequest Methode mit spreadsheet.batchUpdate verwenden.

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

Diese Beispiele werden in Form von HTTP-Anfragen dargestellt, um sprachneutral zu sein. Informationen zum Implementieren von Schreibvorgängen in verschiedenen Sprachen mit den Google API-Clientbibliotheken finden Sie unter Zellwerte lesen und schreiben.

In diesen Beispielen gibt der Platzhalter SPREADSHEET_ID an , wo Sie die Tabellen -ID angeben müssen. Sie finden sie in der Tabellen-URL. Die Bereiche, in die geschrieben werden soll, werden mit der A1 Notation angegeben. Ein Beispielbereich ist Tabelle1!A1:D5.

In einen einzelnen Bereich schreiben

Das folgende spreadsheets.values.update Codebeispiel zeigt, wie Sie in eine neue, leere Tabelle Werte in einen Bereich schreiben. Der ValueInputOption Abfrage parameter 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 majorDimension Feld 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.:

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

Die resultierende Tabelle 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 Array-Elemente auf null setzen. Sie können eine Zelle auch leeren, indem Sie einen leeren String ("") hineinschreiben.

Ausgehend von einer Tabelle mit denselben Daten wie im oben genannten Beispiel zeigt das folgende spreadsheets.values.update Codebeispiel, wie Sie die Werte in den Bereich B1:D4 schreiben und dabei einige Zellen unverändert lassen und andere leeren. Der ValueInputOption Abfrage parameter 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 majorDimension Feld gibt an, dass die Arrays Listen von Werten sind, die nach Spalten organisiert sind.

Das Anfrageprotokoll ist unten dargestellt.

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

Das Feld values listet hier die Änderungen auf, die an den einzelnen Spalten im Bereich vorgenommen wurden. Das erste Array gibt an, dass B1 unverändert bleiben soll (aufgrund des null-Array-Elements), während B4 geleert werden soll (leerer String). Die Werte von B2 und B3 werden aktualisiert. Das dritte Array führt dieselben Vorgänge für Spalte D aus, während das zweite leere Array angibt, dass Spalte C unverändert bleiben soll.

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

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

Die resultierende Tabelle sieht so aus:

Die Zeile „Gesamt“ wird zwar nicht direkt durch diese Anfrage geändert, aber ihre Zellen enthalten Formeln, die von den geänderten Zellen abhängen.

In mehrere Bereiche schreiben

Das folgende spreadsheets.values.batchUpdate Codebeispiel zeigt, wie Sie in eine leere Tabelle Werte in die Bereiche Tabelle1!A1:A4 und Tabelle1!B1:D2 schreiben. Vorhandene Werte im Zielbereich werden überschrieben. Der Anfragetext besteht aus einem ValueInputOption-Objekt, das angibt, wie die Eingabedaten interpretiert werden sollen, und einem Array von ValueRange -Objekten, die den einzelnen Bereichen entsprechen, in die geschrieben wird. Das majorDimension Feld 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, das die Statistiken der aktualisierten Zellen auflistet und einem Array von UpdateValuesResponse Objekten, 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,
    }
  ],
}

Die resultierende Tabelle sieht so aus:

Werte ohne Parsing schreiben

Das folgende spreadsheets.values.update Codebeispiel zeigt, wie Sie in eine leere Tabelle Werte in den Bereich Tabelle1!A1:E1 schreiben. Dabei wird der RAW ValueInputOption Abfrageparameter verwendet, um zu verhindern, dass die geschriebenen Strings als Formeln, boolesche Werte oder Zahlen geparst werden. Sie werden als Strings angezeigt und die Textausrichtung wird in der Tabelle gerechtfertigt.

Der Anfragetext ist ein ValueRange Objekt, das die zu schreibenden Bereichswerte beschreibt. Das majorDimension Feld 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, z. B.:

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

Die resultierende Tabelle sieht so aus:

„TRUE“ ist zentriert und ein boolescher Wert, während „123,45“ rechtsbündig ist, weil es eine Zahl ist, und „10“ linksbündig ist, weil es ein String ist. Die Formel wird nicht geparst und wird auch als String angezeigt.

Werte anhängen

Beginnen Sie mit einer Tabelle wie der folgenden:

Das folgende spreadsheets.values.append Codebeispiel zeigt, wie Sie ab Zeile 3 zwei neue Zeilen mit Werten hinzufügen. Der ValueInputOption Abfrage parameter 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 majorDimension Feld 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.:

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

Die resultierende Tabelle sieht so aus: