Google Sheets API 可讓您讀取儲存格、範圍、範圍組合及整份工作表中的值。本頁的範例說明使用 spreadsheets.values
資源的一些常見的讀取作業。您也可以使用 spreadsheets.get
方法讀取儲存格值,但通常 spreadsheets.values.get
或 spreadsheets.values.batchGet
較為簡單。
這些範例以 HTTP 要求的形式呈現,可達成語言中立的目標。如要瞭解如何使用 Google API 用戶端程式庫以不同語言實作讀取作業,請參閱「讀取及寫入儲存格值」。
在這些範例中,預留位置 SPREADSHEET_ID 代表您要提供試算表 ID 的位置,這項資訊可以在試算表網址中找到。要讀取的範圍是在要求網址中使用 A1 標記法來指定。範例範圍是 Sheet1!A1:D5。
來源資料
針對這些範例,假設正在讀取的試算表在其第一個工作表 (「Sheet1」) 中具有下列來源資料。第一列的字串是個別資料欄的標籤。如要查看如何讀取試算表中其他工作表的範例,請參閱 A1 標記法。
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 日 |
讀取單一範圍
下列 spreadsheets.values.get
程式碼範例說明如何讀取 Sheet1!A1:D5 範圍內的值,並在回應中傳回這些值。結尾會省略空白的結尾列和欄。
要求通訊協定會顯示在這裡。
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5
回應包含說明範圍值的 ValueRange
物件。majorDimension
欄位表示陣列是按資料列排列的值清單。
{ "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", "30/20/2016"], ["Totals", "$135.5", "7", "3/20/2016"] ], }
讀取依資料欄分組的單一範圍
下列 spreadsheets.values.get
程式碼範例說明如何讀取 Sheet1!A1:D3 範圍內的值,並在回應中傳回這些值,但這些值是以資料欄分組。結尾的資料列和資料欄不能為空白。
要求通訊協定會顯示在這裡。
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS
回應包含說明範圍值的 ValueRange
物件。majorDimension
欄位表示陣列是依資料欄整理的值清單。
{ "range": "Sheet1!A1:D3", "majorDimension": "COLUMNS", "values": [ ["Item", "Wheel", "Door"], ["Cost", "$20.50", "$15"], ["Stocked", "4", "2"], ["Ship Date", "3/1/2016", "3/15/2016"] ], }
讀取含有轉譯選項的單一範圍
下列 spreadsheets.values.get
程式碼範例說明如何讀取 Sheet1!A1:D5 範圍內的值,並在回應中傳回這些值,並使用轉譯選項來管理資訊的傳回方式。FORMULA
的 ValueRenderOption
設定代表傳回公式而非計算值,而 SERIAL_NUMBER
的 DateTimeRenderOption
設定表示日期將以數字形式傳回。你也可以使用其他設定。結尾的資料列和資料欄不能為空白。
要求通訊協定會顯示在這裡。
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5? valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER
回應包含說明範圍值的 ValueRange
物件。majorDimension
欄位表示陣列是按資料列排列的值清單。
{ "range": "Sheet1!A1:D5", "majorDimension": "ROWS", "values": [ ["Item", "Cost", "Stocked", "Ship Date"], ["Wheel", "$20.50", "4", "42430"], ["Door", "$15", "2", "42444"], ["Engine", "$100", "1", "42449"], ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"] ], }
讀取多個範圍
以下 spreadsheets.values.batchGet
程式碼範例說明如何讀取 Sheet1!B:B 和 Sheet1!D:D 中的值,並在回應中傳回這些值。UNFORMATTED_VALUE
的 ValueRenderOption
設定表示值已經過計算,但並未設定格式。結尾會省略空白的結尾列和欄。
要求通訊協定會顯示在這裡。
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet? ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS
這個方法呼叫的回應是由包含試算表 ID 的物件,以及對應每個要求範圍的 ValueRange
物件陣列所組成,並依照要求順序列出。majorDimension
欄位表示陣列是依資料欄整理的值清單。例如:
{ "spreadsheetId": SPREADSHEET_ID, "valueRanges": [ { "range": "Sheet1!B1:B1000", "majorDimension": "COLUMNS", "values": [ ["Cost",20.5,15,100,135.5] ] }, { "range": "Sheet1!D1:D1000", "majorDimension": "COLUMNS", "values": [ ["Ship Date",42430,42444,42449,42449] ]s } ] }
讀取多份工作表中的多個範圍
以下 spreadsheets.values.batchGet
程式碼範例說明如何讀取工作表 Sheet1!A1:D5、Products!D1:D100 和 Sales!E4:F6 中的值,並在回應中傳回。UNFORMATTED_VALUE
的 ValueRenderOption
設定表示值已經過計算,但並未設定格式。結尾會省略空白的結尾列和欄。
要求通訊協定會顯示在這裡。
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet? ranges=Sheet1!A1:D5&ranges=Products!D1:D100&ranges=Sales!E4:F6&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS
這個方法呼叫的回應是由包含試算表 ID 的物件,以及對應每個要求範圍的 ValueRange
物件陣列所組成,並依照要求順序列出。majorDimension
欄位表示陣列是依資料欄整理的值清單。例如:
{ "spreadsheetId": SPREADSHEET_ID, "valueRanges": [ { "range": "Sheet1!A1:D5", "majorDimension": "COLUMNS", "values": [ [...], [...] ] }, { "range": "Products!D1:D100", "majorDimension": "COLUMNS", "values": [ [...] ] }, { "range": "Sales!E4:F6", "majorDimension": "COLUMNS", "values": [ [...], [...] ] } ] }