Google Sheets API 可讓您將值和公式寫入儲存格、範圍、範圍組合及整份工作表。本頁的範例說明如何利用 Sheets API 的 spreadsheets.values
資源實現某些常見的寫入作業。
請注意,您也可以使用 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 | 引擎 | NT$3,000 元 | 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
程式碼範例會從空白工作表開始,顯示如何將值寫入 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」是正確的合理值,而「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 | 引擎 | NT$3,000 元 | 1 | 2016 年 3 月 20 日 |
5 |