您可以運用 GoogleSheet API 讀取儲存格、範圍、範圍組合和整份工作表中的值。本頁的範例說明如何使用 spreadsheets.values 資源進行一些常見的讀取作業。您也可以使用 spreadsheets.get 方法讀取儲存格值，但通常 spreadsheets.values.get 或 spreadsheets.values.batchGet 會比較簡單。
這些範例是以 HTTP 要求形式呈現，採用不受語言限制。如要瞭解如何使用 Google API 用戶端程式庫以不同語言實作讀取作業，請參閱讀取及寫入儲存格值。
在這些範例中，預留位置 SPREADSHEET_ID 會指出您要提供試算表 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": [
[...],
[...]
]
}
]
}