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

基本書寫

Google 試算表 API 可讓您將值和公式寫入儲存格、儲存格範圍、範圍組合和整個試算表。本頁面的範例說明如何透過 Sheets API 的 spreadsheets.values 資源執行一些常見的寫入作業。

請注意，您也可以使用 spreadsheet.batchUpdate 方法寫入儲存格值，這在您想同時更新儲存格格式或 spreadsheets.values 資源不會影響的其他屬性時，可能會很實用。舉例來說，如果您想從一個工作表複製儲存格範圍，並覆寫儲存格公式和儲存格格式，可以使用 UpdateCellsRequest 方法搭配 spreadsheet.batchUpdate。

不過，如果要寫入簡單的值，建議使用 spreadsheets.values.update 方法或 spreadsheets.values.batchUpdate 方法。

這些範例以 HTTP 要求的形式呈現，以便不受語言限制。如要瞭解如何使用 Google API 用戶端程式庫，以不同語言實作寫入作業，請參閱「讀取及寫入儲存格值」。

在這些範例中，預留位置 SPREADSHEET_ID 會指出您要提供的試算表 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 程式碼範例說明如何將值寫入範圍 B1:D4，並有選擇地保留部分儲存格，清除其他儲存格。必須使用 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 程式碼範例說明如何將值寫入試算表 1!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