电子表格可以拥有多个工作表,每个工作表都可以有任意数量的行或列。 单元格是插入特定行和列的位置,并且可能包含数据值。 Google Sheets API 提供的 spreadsheets.values 集合可以对值进行简单的读取和写入操作。本页面介绍了使用 spreadsheets.values 集合的基础知识。
如果您需要更新工作表中的格式设置或其他属性,则需要使用 spreadsheets 集合,该集合在更新电子表格中有所介绍。
方法
spreadsheets.values 集合提供了以下读取和写入值的方法,每种方法都可以执行特定的任务:
范围获取 | 读取 | 写入 |
---|---|---|
单个范围 | spreadsheets.values.get | spreadsheets.values.update |
多个范围 | spreadsheets.values.batchGet | spreadsheets.values.batchUpdate |
追加 | spreadsheets.values.append |
一般来说,将多个读取或更新(分别)与 batchGet 和 batchUpdate 方法结合是一种不错的做法,因为这样可以提高效率。
读取
要从工作表读取数据,您需要电子表格 ID 和采用 A1 表示法表示的范围。 如需了解有关电子表格 ID 和 A1 表示法的详细信息,请参阅 Google Sheets API 中的主要概念。
输出的格式由三个可选参数控制:
格式参数 | 默认值 |
---|---|
majorDimension | ROWS |
valueRenderOption | FORMATTED_VALUE |
dateTimeRenderOption | SERIAL_NUMBER |
请注意,dateTimeRenderOption
仅在 valueRenderOption
不为 FORMATTED_VALUE
时使用。
单个获取和批处理获取方法将在下文介绍。 有关基本读取操作的示例,请参阅基本读取诀窍页面。
读取单个范围
要从电子表格读取单个范围的数据,请使用 spreadsheets.values.get 请求:
PROTOCOL
PHP
PYTHON
result = service.spreadsheets().values().get( spreadsheetId=spreadsheet_id, range=range_name).execute()
此请求的响应为 ValueRange 对象。
读取多个范围
要读取多个不连续的范围,请使用 spreadsheets.values.batchGet,该请求让您可以指定要检索的任意数量的范围:
PROTOCOL
PHP
PYTHON
range_names = [ # Range names ...]result = service.spreadsheets().values().batchGet( spreadsheetId=spreadsheet_id, ranges=range_names).execute()
此请求的响应为 BatchGetValueResponse 对象,该对象包含电子表格 ID 和一个由多个 ValueRange 对象组成的列表。
写入
要向工作表写入数据,您需要在相应的请求正文对象中包含电子表格 ID、采用 A1 表示法表示的范围,以及您希望写入的数据。如需了解有关电子表格 ID 和 A1 表示法的详细信息,请参阅 Google Sheets API 中的主要概念。
更新需要一个有效的 ValueInputOption 参数(对于单个更新,此参数是一个必要的查询参数;对于批处理更新,此参数为请求正文中的必需参数)。
ValueInputOption 控制是否解析输入字符串,如下表中所述:
ValueInputOption | 描述 |
---|---|
RAW | 输入不解析,仅作为字符串插入,因此输入“=1+2”会将字符串“=1+2”插入单元格中,而不是插入公式。 (布尔值或数字之类的非字符串值始终作为 RAW 处理。) |
USER_ENTERED | 输入将完全按照在 Google Sheets UI 中输入的形式解析,因此“Mar 1 2016”将成为日期,“=1+2”成为公式。 格式也会推导出来,因此“$100.15”将变成一个采用货币格式设置的数字。 |
单个更新和批处理更新方法将在下文介绍。 有关基本写入操作的示例,请参阅基本写入诀窍页面。
向单个范围写入数据
要向单个范围写入数据,请使用 spreadsheets.values.update 请求:
PROTOCOL
PHP
PYTHON
values = [ [ # Cell values ... ], # Additional rows ...]body = { 'values': values}result = service.spreadsheets().values().update( spreadsheetId=spreadsheet_id, range=range_name, valueInputOption=value_input_option, body=body).execute()
更新请求的正文必须是一个 ValueRange 对象,尽管唯一必填字段是 values
。
如果指定 range
,它必须与网址中的范围匹配。 在 ValueRange 中,您可以根据需要指定其 majorDimension 默认情况下,将使用 ROWS。 如果指定 COLUMNS,每个内部数组都将写入列而不是行中。
更新时,将跳过没有数据的值。 要清除数据,请使用空字符串 (“”)。范围参数可以指定多个单元格(例如 A1:D5)或一个单元格(例如 A1)。 如果范围参数指定多个单元格,那么输入数据必须位于该范围中。 如果范围参数指定一个单元格,输入数据将从该坐标开始延伸任意数量的行或列。
写入多个范围
如果想要向多个不连续的范围写入数据,您可以使用 spreadsheets.values.batchUpdate 请求:
PROTOCOL
PHP
PYTHON
values = [ [ # Cell values ], # Additional rows]data = [ { 'range': range_name, 'values': values }, # Additional ranges to update ...]body = { 'valueInputOption': value_input_option, 'data': data}result = service.spreadsheets().values().batchUpdate( spreadsheetId=spreadsheet_id, body=body).execute()
batchUpdate 请求的正文必须是一个 BatchUpdateValuesRequest 对象,该对象包含一个 ValueInputOption 和一个由多个 ValueRange 对象组成的列表(每个写入范围一个对象)。每个 ValueRange 对象都指定其自己的 range
、majorDimension
和要输入的数据。
追加值
要在工作表中包含数据的表格后追加数据,请使用 spreadsheets.values.append 请求:
PROTOCOL
PHP
PYTHON
values = [ [ # Cell values ... ], # Additional rows ...]body = { 'values': values}result = service.spreadsheets().values().append( spreadsheetId=spreadsheet_id, range=range_name, valueInputOption=value_input_option, body=body).execute()
更新请求的正文必须是一个 ValueRange 对象,尽管唯一必填字段是 values
。如果指定 range
,它必须与网址中的范围匹配。 在 ValueRange 中,您可以根据需要指定其 majorDimension。 默认情况下,将使用 ROWS。 如果指定 COLUMNS,每个内部数组都将写入列而不是行中。majorDimension 参数不控制数据以行还是列形式添加到表格中。 数据将始终添加到随后的行中。 该参数仅控制输入数据的读取方式。
输入范围用于搜索现有数据和查找该范围内的“表格”。 值将追加到表格的下一行,从表格的第一列开始。 例如,假设存在一个如下所示的工作表 Sheet1
:
A | B | C | D | E |
1 | x | y | z | |
2 | x | y | z | |
3 | ||||
4 | x | y | ||
5 | y | z | ||
6 | x | y | z | |
7 |
工作表中存在两个表格:A1:C2
和 B4:D6
。 对于下面的所有 range
输入,追加的值将从 B7
开始:
Sheet1
,因为它将检查工作表中的所有数据,确定B4:D6
处的表格为最后一个表格。B4
或者C5:D5
,因为它们都位于B4:D6
表格中。B2:D4
,因为范围中的最后一个表格为B4:D6
表格(尽管范围也包含A1:C2
表格)。A3:G10
,因为范围中的最后一个表格为B4:D6
表格(尽管 A3:G10 在该表格之前开始并在该表格之后结束)。
下面的 range
输入不会从 B7
开始写入:
A1
将从A3
开始写入,因为 A1 处于A1:C2
表格中。E4
将从E4
开始写入,因为它不位于任何表格中。 (基于相同的原因,A4
也会从A4
开始写入。)
此外,您也可以选择是在表格后替换现有数据,还是为新数据插入新行。 默认情况下,输入将在表格后替换数据。 要将新数据写入新行,请指定 insertDataOption=INSERT_ROWS
。