本頁面說明如何將 Google 圖表與 Google 試算表搭配使用。
簡介
Google 圖表與 Google 試算表緊密整合。您可以在 Google 試算表中放置 Google 圖表,而 Google 圖表也可以從 Google 試算表擷取資料。本說明文件將說明如何執行這兩種操作。
無論您選擇哪種方法,只要基礎試算表有所變更,您的圖表都會隨之變更。
將圖表嵌入試算表
在試算表中加入圖表非常簡單。在試算表工具列中,依序選取 [插入] 和 [圖表],您就能選擇圖表類型及各種選項:
以獨立試算表建立圖表
一般來說,使用者需填入資料表格,並使用這些資料繪製圖表。如果您想改為從 Google 試算表擷取資料,可以查詢試算表以擷取要建立圖表的資料:
function drawChart() { var query = new google.visualization.Query(URL); query.send(handleQueryResponse); } function handleQueryResponse(response) { var data = response.getDataTable(); var chart = new google.visualization.ColumnChart(document.getElementById('columnchart')); chart.draw(data, null); }
這之所以有效,是因為 Google 試算表支援使用 Google 圖表的查詢語言來排序及篩選資料;任何支援查詢語言的系統都可用來當做資料來源。
請注意,圖表「不得」在未經明確授權的情況下,使用檢視者的權限。這份試算表必須讓所有使用者都能看見,或者網頁必須明確取得使用者憑證,如本頁的授權一節所述。
如要使用「Google 試算表」做為資料來源,您需要其網址:
- 開啟現有的試算表。這份試算表應具有視覺呈現的格式,且應具備適當的檢視權限。(最簡單的權限是「公開在網路上」或「擁有連結的使用者」檢視權限),且本節的操作說明均假設您以這種方式設定一份試算表。如要限制存取該試算表,請將試算表設為 [私人] 並授權個別 Google 帳戶存取,但請務必按照下方的授權操作說明進行。
- 從瀏覽器中複製網址。 如要進一步瞭解如何選取特定範圍,請參閱查詢來源範圍。
- 將網址提供給
google.visualization.Query()
。 這項查詢支援下列選用參數:headers=N
:指定有多少列是標題列,其中 N 是一個整數零或更大。系統會從資料中排除這些資料,並以資料表內的資料欄標籤的形式指派。如果未指定這個參數,試算表會猜測有多少資料列是標題列。 請注意,如果所有資料欄都是字串資料,試算表可能會難以判斷哪些資料列是不含這個參數的標題列。gid=N
:指定未連結至第一個工作表時,要設為連結多個工作表中的工作表。 「N」是工作表的 ID 號碼。如要瞭解 ID 編號,請前往該工作表的已發布版本,並在網址中尋找gid=N
參數。您也可以使用sheet
參數取代此參數。Gotcha:Google 試算表可能會在瀏覽器中檢視網址中的 gid 參數;如果從瀏覽器複製資料,請確定所有參數都「位於」網址的#
標記之前。範例:gid=1545912003
。sheet=sheet_name
:如果您要連結的是第一個工作表,則請指定您要連結的多工作表文件中的哪個工作表。sheet_name 是工作表的顯示名稱。範例:sheet=Sheet5
。
相關完整範例如下:
以下是繪製這張圖表的兩種方法:一種是使用 gid
參數,另一種則是使用 sheet
參數。在瀏覽器中輸入任一網址後,圖表會產生相同的結果/資料,
function drawGID() { var queryString = encodeURIComponent('SELECT A, H, O, Q, R, U LIMIT 5 OFFSET 8'); var query = new google.visualization.Query( 'https://docs.google.com/spreadsheets/d/1XWJLkAwch5GXAt_7zOFDcg8Wm8Xv29_8PWuuW15qmAE/gviz/tq?gid=0&headers=1&tq=' + queryString); query.send(handleQueryResponse); } function handleQueryResponse(response) { if (response.isError()) { alert('Error in query: ' + response.getMessage() + ' ' + response.getDetailedMessage()); return; } var data = response.getDataTable(); var chart = new google.visualization.ColumnChart(document.getElementById('chart_div')); chart.draw(data, { height: 400 }); }
function drawSheetName() { var queryString = encodeURIComponent('SELECT A, H, O, Q, R, U LIMIT 5 OFFSET 8'); var query = new google.visualization.Query( 'https://docs.google.com/spreadsheets/d/1XWJLkAwch5GXAt_7zOFDcg8Wm8Xv29_8PWuuW15qmAE/gviz/tq?sheet=Sheet1&headers=1&tq=' + queryString); query.send(handleSampleDataQueryResponse); } function handleSampleDataQueryResponse(response) { if (response.isError()) { alert('Error in query: ' + response.getMessage() + ' ' + response.getDetailedMessage()); return; } var data = response.getDataTable(); var chart = new google.visualization.ColumnChart(document.getElementById('chart_div')); chart.draw(data, { height: 400 }); }
查詢來源範圍
查詢來源網址會指定查詢中試算表的哪個部分:特定儲存格、儲存格範圍、資料列或資料欄,或是整個試算表。使用「range=<range_expr>」語法指定範圍,例如:
https://docs.google.com/spreadsheets/d/1XWJLkAwch5GXAt_7zOFDcg8Wm8Xv29_8PWuuW15qmAE/gviz/tq?range=A1:C4
以下列舉幾個語法說明的語法:
A1:B10
- 儲存格 A1 到 B10 的範圍5:7
- 第 5-7 列D:F
- D-F 欄A:A70
- A 欄中的前 70 個儲存格-
A70:A
- 第 70 列到 A 欄的 A 欄 B5:5
- B5 至第 5 列結尾D3:D
- D3 至 D 欄的結尾C:C10
- 從 C 欄的開頭到 C10
授權
Google 試算表需要使用者憑證,才能透過 Google Visualization API 存取私人試算表 (「/tq 要求」)。注意:與「知道連結的人皆可檢視」的試算表不需憑證。變更試算表共用設定比導入授權來得容易。
如果連結共用設定不是可行的解決方案,開發人員必須變更程式碼,以傳遞已獲 Google 試算表 API 範圍 (https://www.googleapis.com/auth/spreadsheet) 授權的 OAuth 2.0 憑證。
如要進一步瞭解 OAuth 2.0,請參閱使用 OAuth 2.0 存取 Google API 一文
範例:使用 OAuth 存取 /gviz/tq
前置作業:從 Google Developers Console 取得用戶端 ID
如需整合 Google 身分識別平台的詳細操作說明,請造訪 Google 登入 和建立 Google API 控制台專案和用戶端 ID。
如要取得使用者的 OAuth 憑證,您必須先透過 Google Developer Console 註冊專案,並取得用戶端 ID。
- 在開發人員控制台中建立新的 OAuth 用戶端 ID。
- 選擇「Web application」做為您的應用程式類型。
- 請挑選任何名稱;這個名稱僅供參考。
- 將網域名稱 (以及任何測試網域) 新增為「授權 JavaScript 來源」。
- 將 [Authorized redirect URIs] (已授權的重新導向 URI) 留空。
按一下 [建立] 後,複製用戶端 ID 以供日後參考。這項練習不需要用戶端密鑰。
更新您的網站以取得 OAuth 憑證。
Google 提供的 gapi.auth
程式庫可大幅簡化取得 OAuth 憑證的程序。下方的程式碼範例會使用這個程式庫取得憑證 (如有需要可要求授權),並將產生的憑證傳送至 /gviz/tq 端點。
<html> <body> <button id="authorize-button" style="visibility: hidden">Authorize</button> <script src="./demo.js" type="text/javascript"></script> <script src="https://apis.google.com/js/auth.js?onload=init"></script> </body> </html>demo.js
// NOTE: You must replace the client id on the following line. var clientId = '549821307845-9ef2xotqflhcqbv10.apps.googleusercontent.com'; var scopes = 'https://www.googleapis.com/auth/spreadsheets'; function init() { gapi.auth.authorize( {client_id: clientId, scope: scopes, immediate: true}, handleAuthResult); } function handleAuthResult(authResult) { var authorizeButton = document.getElementById('authorize-button'); if (authResult && !authResult.error) { authorizeButton.style.visibility = 'hidden'; makeApiCall(); } else { authorizeButton.style.visibility = ''; authorizeButton.onclick = handleAuthClick; } } function handleAuthClick(event) { gapi.auth.authorize( {client_id: clientId, scope: scopes, immediate: false}, handleAuthResult); return false; } function makeApiCall() { // Note: The below spreadsheet is "Public on the web" and will work // with or without an OAuth token. For a better test, replace this // URL with a private spreadsheet. var tqUrl = 'https://docs.google.com/spreadsheets' + '/d/1XWJLkAwch5GXAt_7zOFDcg8Wm8Xv29_8PWuuW15qmAE/gviz/tq' + '?tqx=responseHandler:handleTqResponse' + '&access_token=' + encodeURIComponent(gapi.auth.getToken().access_token); document.write('<script src="' + tqUrl +'" type="text/javascript"></script>'); } function handleTqResponse(resp) { document.write(JSON.stringify(resp)); }
授權成功後,gapi.auth.getToken()
會傳回所有憑證詳細資料,包括可附加到 /gviz/tq 要求的 access_token
。
如要進一步瞭解如何使用 gapi 程式庫進行驗證,請參閱:
使用 drive.file 範圍
上述範例使用 Google Sheets API 範圍,這個範圍會授予使用者試算表內容的完整讀取和寫入權限。視應用程式而定,這可能比必要更寬鬆。如果是唯讀存取權,請使用 sheets.readonly 範圍,授予使用者工作表及其屬性的唯讀存取權。
drive.file 範圍 (https://www.googleapis.com/auth/drive.file) 只會授予使用者「明確」透過 Google 檔案選擇器開啟的檔案 (檔案來源為 Picker API)。
使用挑選器會變更應用程式的流程。使用者必須使用挑選器工具,選擇您希望網頁存取的試算表,而不是貼上網址,或採用硬式編碼的試算表。請按照挑選器「Hello World」範例並使用 google.picker.ViewId.SPREADSHEETS
取代 google.picker.ViewId.PHOTOS
。