Google Sheets API 可讓您建立、清除、複製和刪除工作表,也可控制工作表的屬性。本頁面的範例說明如何透過 Sheets API 完成一些常見的試算表作業。
這些範例以 HTTP 要求的形式呈現,可達成語言中立的目標。如要瞭解如何使用 Google API 用戶端程式庫,以不同語言實作批次更新,請參閱「更新試算表」。
在這些範例中,預留位置 SPREADSHEET_ID
和 SHEET_ID
會指出您會在哪些位置提供這些 ID。你可以在試算表網址中找到試算表 ID。您可以使用 spreadsheets.get
方法取得工作表 ID。範圍是使用 A1 標記法來指定。範例範圍是 Sheet1!A1:D5。
新增工作表
下列 spreadsheets.batchUpdate
程式碼範例說明如何使用 AddSheetRequest
在試算表中新增工作表,同時設定標題、格線大小和分頁顏色。
回應由 AddSheetResponse
組成,其中包含的物件含有所建立工作表的屬性 (例如其 SHEET_ID
)。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
:batchUpdate
{ "requests": [ { "addSheet": { "properties": { "title": "Deposits", "gridProperties": { "rowCount": 20, "columnCount": 12 }, "tabColor": { "red": 1.0, "green": 0.3, "blue": 0.4 } } } } ] }
清除所有值的工作表,同時保留格式
以下 spreadsheets.batchUpdate
程式碼範例說明如何使用 UpdateCellsRequest
移除工作表中的所有值,同時保留格式不變。
如果指定沒有對應值的 userEnteredValue
欄位,系統會將其解讀為清除範圍內值的指示。這項設定也可搭配其他欄位使用。舉例來說,將 fields
值變更為 userEnteredFormat
會從工作表中移除 Sheets API 支援的所有格式,但不變更儲存格值。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
:batchUpdate
{
"requests": [
{
"updateCells": {
"range": {
"sheetId": SHEET_ID
},
"fields": "userEnteredValue"
}
}
]
}
將工作表中的工作表複製到其他試算表
以下 spreadsheet.sheets.copyTo
程式碼範例說明如何將 SHEET_ID
指定的單張工作表從一份試算表複製到另一份試算表。
要求主體中的 TARGET_SPREADSHEET_ID
變數會指定目的地試算表。副本會保留原始項目的所有值、格式、公式及其他屬性。複製工作表的標題會設為「Copy of [originalsheet title]」。
回應包含 SheetProperties
物件,說明所建立工作表的屬性。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/sheets/SHEET_ID
:copyTo
{
"destinationSpreadsheetId": "TARGET_SPREADSHEET_ID
"
}
刪除工作表
下列 spreadsheets.batchUpdate
程式碼範例說明如何使用 DeleteSheetRequest
刪除 SHEET_ID
指定的工作表。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": SHEET_ID
}
}
]
}
讀取工作表資料
以下 spreadsheets.get
程式碼範例說明如何從 SHEET_ID
和 SPREADSHEET_ID
指定的試算表取得工作表屬性資訊。此方法通常用於確定特定試算表中的工作表中繼資料,以便執行其他作業以指定這些工作表。fields
查詢參數會指定只傳回工作表屬性資料 (而非儲存格值資料或整份試算表的相關資料)。
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
?&fields=sheets.properties
回應包含 Spreadsheet
資源,其中包含具有 SheetProperties
元素的 Sheet
物件。如果將特定回應欄位設為預設值,回應中會省略該欄位。
{
"sheets": [
{
"properties": {
"sheetId": SHEET_ID
,
"title": "Sheet1",
"index": 0,
"sheetType": "GRID",
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1
}
"tabColor": {
"blue": 1.0
}
},
...
],
}