利用 Google Sheets 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 | 引擎 | $100 | 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": [
[...],
[...]
]
}
]
}