Google Sheets API 可讓您視需要建立及更新試算表中的圖表。本頁的範例說明如何使用 Google Sheets API 執行一些常見的圖表作業。
這些範例會以 HTTP 要求的形式呈現，不限於特定語言。如要瞭解如何使用 Google API 用戶端程式庫，以不同語言實作批次更新，請參閱更新試算表。
在這些範例中，預留位置 SPREADSHEET_ID 和 SHEET_ID
表示您提供這些 ID 的位置。您可以在試算表網址中找到試算表 ID。您可以使用 spreadsheets.get 方法取得 工作表 ID。範圍是使用 A1 標記法指定。例如 Sheet1!A1:D5。
此外，預留位置 CHART_ID 表示指定圖表的 ID。您可以在使用 Google 試算表 API 建立圖表時設定這個 ID，也可以讓 Google 試算表 API 為您產生 ID。您可以使用 spreadsheets.get 方法取得現有圖表的 ID。
最後，預留位置 SOURCE_SHEET_ID 會指出含有來源資料的工作表。在這些範例中，這是「圖表來源資料」下方列出的表格。
圖表來源資料
在這些範例中，假設所用的試算表在第一個工作表 (「Sheet1」) 中有下列來源資料。第一列中的字串是個別資料欄的標籤。如要查看如何從試算表中的其他工作表讀取資料的範例，請參閱「A1 標記」。
| A | B | C | D | E | |
| 1 | 型號 | 銷售 - Jan | 銷售人員 - 2 月 | 銷售人員 - Mar | 總銷售額 |
| 2 | D-01X | 68 | 74 | 60 | 202 |
| 3 | FR-0B1 | 97 | 76 | 88 | 261 |
| 4 | P-034 | 27 | 49 | 32 | 108 |
| 5 | P-105 | 46 | 44 | 67 | 157 |
| 6 | W-11 | 75 | 68 | 87 | 230 |
| 7 | W-24 | 74 | 52 | 62 | 188 |
新增柱狀圖
下列
spreadsheets.batchUpdate
程式碼範例說明如何使用 AddChartRequest
從來源資料建立直條圖，並將其放在新工作表中。這項要求會執行下列動作來設定圖表：
- 將圖表類型設為柱狀圖。
- 在圖表底部新增圖例。
- 設定圖表和軸標題。
- 設定 3 個資料數列，代表 3 個不同月份的銷售額，同時使用預設格式和顏色。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{ "requests": [ { "addChart": { "chart": { "spec": { "title": "Model Q1 Sales", "basicChart": { "chartType": "COLUMN", "legendPosition": "BOTTOM_LEGEND", "axis": [ { "position": "BOTTOM_AXIS", "title": "Model Numbers" }, { "position": "LEFT_AXIS", "title": "Sales" } ], "domains": [ { "domain": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 7, "startColumnIndex": 0, "endColumnIndex": 1 } ] } } } ], "series": [ { "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 7, "startColumnIndex": 1, "endColumnIndex": 2 } ] } }, "targetAxis": "LEFT_AXIS" }, { "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 7, "startColumnIndex": 2, "endColumnIndex": 3 } ] } }, "targetAxis": "LEFT_AXIS" }, { "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 7, "startColumnIndex": 3, "endColumnIndex": 4 } ] } }, "targetAxis": "LEFT_AXIS" } ], "headerCount": 1 } }, "position": { "newSheet": true } } } } ] }
這項要求會在新的工作表中建立圖表，如下所示：
新增圓餅圖
下列 spreadsheets.batchUpdate 程式碼範例說明如何使用 AddChartRequest 從來源資料建立 3D 圓形圖。這項要求會執行下列動作來設定圖表：
- 設定圖表標題。
- 在圖表右側新增圖例。
- 將圖表設為 3D 圓餅圖。請注意，3D 圓餅圖無法像平面圓餅圖一樣，在中央顯示「圓環洞」。
- 將圖表資料序列設為各型號的總銷售量。
- 將圖表錨定在 SHEET_ID 指定工作表的 C3 儲存格，並在 X 和 Y 方向上偏移 50 像素。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{ "requests": [ { "addChart": { "chart": { "spec": { "title": "Model Q1 Total Sales", "pieChart": { "legendPosition": "RIGHT_LEGEND", "threeDimensional": true, "domain": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 7, "startColumnIndex": 0, "endColumnIndex": 1 } ] } }, "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 7, "startColumnIndex": 4, "endColumnIndex": 5 } ] } }, } }, "position": { "overlayPosition": { "anchorCell": { "sheetId": SHEET_ID, "rowIndex": 2, "columnIndex": 2 }, "offsetXPixels": 50, "offsetYPixels": 50 } } } } } ] }
這項要求會建立如下的圖表：
或者，您也可以在要求中將 RIGHT_LEGEND 的 legendPosition 值更新為 LABELED_LEGEND，讓圖例值與圓餅圖切片連結。
'legendPosition': 'LABELED_LEGEND',
更新後的要求會建立如下圖表：
使用多個不相鄰的範圍新增折線圖
下列
spreadsheets.batchUpdate
程式碼範例說明如何使用
AddChartRequest
從來源資料建立折線圖，並將其放在來源工作表中。
選取不連續的範圍，即可從 ChartSourceRange 中排除資料列。
這項要求會執行下列動作來設定圖表：
- 將圖表類型設為折線圖。
- 設定水平 x 軸標題。
- 設定代表銷售量的資料序列。系統會將 A1:A3 和 A6:A7 設為
domain，並將 B1:B3 和 B6:B7 設為series，同時使用預設格式和顏色。範圍是在要求網址中，使用 A1 標記指定。 - 將圖表錨定在 SHEET_ID 指定的試算表儲存格 H8。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"addChart": {
"chart": {
"spec": {
"basicChart": {
"chartType": "LINE",
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"startRowIndex": 0,
"endRowIndex": 3,
"startColumnIndex": 0,
"endColumnIndex": 1,
"sheetId": SOURCE_SHEET_ID
},
{
"startRowIndex": 5,
"endRowIndex": 7,
"startColumnIndex": 0,
"endColumnIndex": 1,
"sheetId": SOURCE_SHEET_ID
}
]
}
}
}
],
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"startRowIndex": 0,
"endRowIndex": 3,
"startColumnIndex": 1,
"endColumnIndex": 2,
"sheetId": SOURCE_SHEET_ID
},
{
"startRowIndex": 5,
"endRowIndex": 7,
"startColumnIndex": 1,
"endColumnIndex": 2,
"sheetId": SOURCE_SHEET_ID
}
]
}
}
}
]
}
},
"position": {
"overlayPosition": {
"anchorCell": {
"sheetId": SOURCE_SHEET_ID,
"rowIndex": 8,
"columnIndex": 8
}
}
}
}
}
}
]
}這項要求會在新的工作表中建立圖表，如下所示：
刪除圖表
下列spreadsheets.batchUpdate程式碼範例說明如何使用 DeleteEmbeddedObjectRequest 刪除 CHART_ID 指定的圖表。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"deleteEmbeddedObject": {
"objectId": CHART_ID
}
}
]
}編輯圖表的屬性
下列
spreadsheets.batchUpdate
程式碼範例說明如何使用 UpdateChartSpecRequest 編輯在「新增直條圖」食譜中建立的圖表，修改其資料、類型和外觀。無法個別變更圖表屬性的子集。如要編輯，您必須提供整個 spec 欄位，並附上 UpdateChartSpecRequest。基本上，如要編輯圖表規格，必須改用新規格。
下列要求會更新原始圖表 (由 CHART_ID 指定)：
- 將圖表類型設為
BAR。 - 將圖例移至圖表右側。
- 反轉座標軸，使「銷售量」位於底部座標軸，「型號」位於左側座標軸。
- 將軸標題格式設為 24 點字型、粗體和斜體。
- 從圖表 (圖表來源資料中的第 7 列) 移除「W-24」資料。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{ "requests": [ { "updateChartSpec": { "chartId": CHART_ID, "spec": { "title": "Model Q1 Sales", "basicChart": { "chartType": "BAR", "legendPosition": "RIGHT_LEGEND", "axis": [ { "format": { "bold": true, "italic": true, "fontSize": 24 }, "position": "BOTTOM_AXIS", "title": "Sales" }, { "format": { "bold": true, "italic": true, "fontSize": 24 }, "position": "LEFT_AXIS", "title": "Model Numbers" } ], "domains": [ { "domain": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 6, "startColumnIndex": 0, "endColumnIndex": 1 } ] } } } ], "series": [ { "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 6, "startColumnIndex": 1, "endColumnIndex": 2 } ] } }, "targetAxis": "BOTTOM_AXIS" }, { "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 6, "startColumnIndex": 2, "endColumnIndex": 3 } ] } }, "targetAxis": "BOTTOM_AXIS" }, { "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 6, "startColumnIndex": 3, "endColumnIndex": 4 } ] } }, "targetAxis": "BOTTOM_AXIS" } ], "headerCount": 1 } } } } ] }
要求後，圖表會顯示如下：
移動圖表或調整圖表大小
下列程式碼範例說明如何使用 spreadsheets.batchUpdate 移动及調整圖表大小。UpdateEmbeddedObjectPositionRequest要求後，CHART_ID
指定的圖表為：
- 錨定至原始工作表的 A5 儲存格。
- 在 X 方向偏移 100 像素。
- 調整為 1200 x 742 像素 (圖表的預設大小為 600 x 371 像素)。
要求只會變更以 fields 參數指定的屬性。其他屬性 (例如 offsetYPixels) 會保留原始值。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"updateEmbeddedObjectPosition": {
"objectId": CHART_ID,
"newPosition": {
"overlayPosition": {
"anchorCell": {
"rowIndex": 4,
"columnIndex": 0
},
"offsetXPixels": 100,
"widthPixels": 1200,
"heightPixels": 742
}
},
"fields": "anchorCell(rowIndex,columnIndex),offsetXPixels,widthPixels,heightPixels"
}
}
]
}讀取圖表資料
下列程式碼範例說明如何從試算表取得圖表資料。spreadsheets.getfields 查詢參數指定只應傳回圖表資料。
這個方法呼叫的回應是 spreadsheet 物件，其中包含 sheet 物件的陣列。工作表上的所有圖表都會以 sheet 物件表示。如果回應欄位設為預設值，系統會從回應中省略該欄位。
在本範例中，第一個工作表 (SOURCE_SHEET_ID) 沒有任何圖表，因此系統會傳回一對空白的大括號。第二個工作表包含「建立柱狀圖」建立的圖表，沒有其他內容。
要求通訊協定如下所示。
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets(charts)
{ "sheets": [ {}, { "charts": [ { "chartId": CHART_ID, "position": { "sheetId": SHEET_ID }, "spec": { "basicChart": { "axis": [ { "format": { "bold": false, "italic": false }, "position": "BOTTOM_AXIS", "title": "Model Numbers" }, { "format": { "bold": false, "italic": false }, "position": "LEFT_AXIS", "title": "Sales" } ], "chartType": "COLUMN", "domains": [ { "domain": { "sourceRange": { "sources": [ { "endColumnIndex": 1 "endRowIndex": 7, "sheetId": SOURCE_SHEET_ID, "startColumnIndex": 0, "startRowIndex": 0, } ] } } } ], "legendPosition": "BOTTOM_LEGEND", "series": [ { "series": { "sourceRange": { "sources": [ { "endColumnIndex": 2, "endRowIndex": 7, "sheetId": SOURCE_SHEET_ID, "startColumnIndex": 1, "startRowIndex": 0, } ] } }, "targetAxis": "LEFT_AXIS" }, { "series": { "sourceRange": { "sources": [ { "endColumnIndex": 3, "endRowIndex": 7, "sheetId": SOURCE_SHEET_ID, "startColumnIndex": 2, "startRowIndex": 0, } ] } }, "targetAxis": "LEFT_AXIS" }, { "series": { "sourceRange": { "sources": [ { "endColumnIndex": 4, "endRowIndex": 7, "sheetId": SOURCE_SHEET_ID, "startColumnIndex": 3, "startRowIndex": 0, } ] } }, "targetAxis": "LEFT_AXIS" } ] }, "hiddenDimensionStrategy": "SKIP_HIDDEN_ROWS_AND_COLUMNS", "title": "Model Q1 Sales", }, } ] } ] }