基本書寫

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