借助 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 | Engine | $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": [ [...], [...] ] } ] }