本頁面由 Cloud Translation API 翻譯而成。

基本書寫

Google Sheets API 可讓你將值和公式寫入儲存格、範圍、組合範圍和整份工作表本頁的例子說明瞭常見的寫入作業可以使用 spreadsheets.values敬上 Sheets API 資源

請注意，您也可使用 spreadsheet.batchUpdate敬上方法，當您想同時更新儲存格格式設定時，這項功能就能派上用場或其他屬性 spreadsheets.values 但這不影響舉例來說，如果要複製某個範圍的儲存格同時覆寫儲存格公式和儲存格這時您可以使用 UpdateCellsRequest敬上方法， spreadsheet.batchUpdate。

不過，對於簡單的值寫入，較適合使用 spreadsheets.values.update敬上方法，或 spreadsheets.values.batchUpdate 方法。

這些範例是以 HTTP 要求的形式呈現中立。如要瞭解如何使用 Google API 用戶端程式庫，請參閱讀取及寫入儲存格值。

在這些範例中，預留位置 SPREADSHEET_ID 代表以便提供試算表 ID，可從試算表網址。要寫入的範圍是使用 A1 指定標記法。範例範圍是 Sheet1!A1:D5。

寫入單一範圍

以下我們將從新的空白試算表開始著手 spreadsheets.values.update敬上程式碼範例顯示如何將值寫入特定範圍。 ValueInputOption 查詢參數，用來判定寫入的值是否經過剖析 (適用於例如字串是否已轉換為日期)。

要求主體是 ValueRange敬上物件，說明要寫入的範圍值。 majorDimension 欄位表示陣列是按資料列排列的值清單。現有值就會被覆寫。

要求通訊協定如下所示。

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

回應由 UpdateValuesResponse敬上物件，例如以下：

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

產生的工作表如下所示：

	A	B	C	D
1	項目	費用	存貨	出貨日期
2	車輪	$20.50 美元	4	2016 年 3 月 1 日
3	門	$15	2	2016 年 3 月 15 日
4	引擎	$100	1	2016 年 3 月 20 日
5	總計	$135.5 美元	7	2016 年 3 月 20 日

選擇性寫入特定範圍

您可以將值寫入範圍，以避免變更將對應的陣列元素設為 null，即可修正儲存格的值。也有可能是要清除儲存格內容，請在儲存格中輸入空字串 ("")。

從包含與上述範例，詳情請參閱 spreadsheets.values.update敬上程式碼範例顯示如何將值寫入範圍 (選擇性) 保留部分儲存格並清除其他儲存格。 ValueInputOption 查詢參數，用來判定寫入的值是否經過剖析 (適用於例如字串是否已轉換為日期)。

要求主體是 ValueRange敬上物件，說明要寫入的範圍值。 majorDimension 欄位代表陣列是依資料欄整理的值清單。

要求通訊協定如下所示。

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

這裡的 values 欄位會列出範圍內每個資料欄的變更。第一個陣列表示 B1 會因為 null 陣列而維持不變元素)，而 B4 要清除 (空白字串)。B2 和 B3 也反映相同的價值已更新。第三個陣列會對 D 欄執行相同的作業，而第二個空白陣列表示 C 欄必須維持不變。

回應由 UpdateValuesResponse敬上物件，例如以下：

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

產生的工作表如下所示：

	A	B	C	D
1	項目	費用	存貨	出貨日期
2	車輪	$1.00 美元	4	2016 年 4 月 1 日
3	門	$2 美元	2	2016 年 4 月 15 日
4	引擎		1
5	總計	$3.00 美元	7	2016 年 4 月 15 日

請注意，「總計」資料列，雖然不是由此要求直接變更，但卻不會，變更，因為儲存格內的公式參照了經修改的儲存格。

寫入多個範圍

以下是從空白工作表開始著手 spreadsheets.values.batchUpdate敬上程式碼範例顯示如何將值寫入範圍 Sheet1!A1:A4 Sheet1!B1:D2。並覆寫目標範圍內的現有值。要求「主體」 ValueInputOption 物件，該物件會顯示如何解讀輸入資料和 ValueRange 對應至各個寫入範圍的物件 majorDimension 欄位會決定納入的陣列是否會解譯為資料欄或資料列陣列。

要求通訊協定如下所示。

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

回應包含物件，且該物件會列出更新後的儲存格統計資料和 UpdateValuesResponse敬上分別用於每個更新後的範圍例如：

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

產生的工作表如下所示：

	A	B	C	D
1	項目	費用	存貨	出貨日期
2	車輪	$20.50 美元	4	2016 年 3 月 1 日
3	門
4	引擎
5

在不剖析的情況下寫入值

以下是從空白工作表開始著手 spreadsheets.values.update敬上程式碼範例顯示如何將值寫入範圍 Sheet1!A1:E1，但卻使用 RAW ValueInputOption 查詢參數，避免系統將輸入的字串剖析為公式布林值或數字，以字串的形式顯示，且文字對齊的左右對齊工作表。

要求主體是 ValueRange敬上物件，說明要寫入的範圍值。 majorDimension 欄位表示陣列是按資料列排列的值清單。現有值就會被覆寫。

要求通訊協定如下所示。

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

回應由 UpdateValuesResponse敬上物件，例如以下：

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

產生的工作表如下所示：

	A	B	C	D	E
1	資料	123.45	TRUE	=MAX(D2:D4)	10
2

請注意，「TRUE」置中且為布林值，「123.45」是對的因為是數字、「10」才有意義所以左右對齊字串。系統不會剖析該公式，且會以字串形式顯示。

附加值

從下表開始：

	A	B	C	D
1	項目	費用	存貨	出貨日期
2	車輪	$20.50 美元	4	2016 年 3 月 1 日
3

下列 spreadsheets.values.append敬上程式碼範例顯示如何從第 3 列開始新增兩個值。 ValueInputOption 查詢參數，用來判定寫入的值是否經過剖析 (適用於例如字串是否已轉換為日期)。

要求主體是 ValueRange敬上物件，說明要寫入的範圍值。 majorDimension 欄位表示陣列是按資料列排列的值清單。

要求通訊協定如下所示。

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

回應由 AppendValuesResponse敬上物件，例如以下：

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

產生的工作表如下所示：

	A	B	C	D
1	項目	費用	存貨	出貨日期
2	車輪	$20.50 美元	4	2016 年 3 月 1 日
3	門	$15	2	2016 年 3 月 15 日
4	引擎	$100	1	2016 年 3 月 20 日
5