Google API 读取和写入单元格值

电子表格可以拥有多个工作表，每个工作表都可以有任意数量的行或列。 单元格是插入特定行和列的位置，并且可能包含数据值。 Google Sheets API 提供的 spreadsheets.values 集合可以对值进行简单的读取和写入操作。本页面介绍了使用 spreadsheets.values 集合的基础知识。

如果您需要更新工作表中的格式设置或其他属性，则需要使用 spreadsheets 集合，该集合在更新电子表格中有所介绍。

方法

spreadsheets.values 集合提供了以下读取和写入值的方法，每种方法都可以执行特定的任务：

一般来说，将多个读取或更新（分别）与 batchGet 和 batchUpdate 方法结合是一种不错的做法，因为这样可以提高效率。

您可以在基本读取和基本写入示例页面中找到这些方法的示例。

读取

要从工作表读取数据，您需要电子表格 ID 和采用 A1 表示法表示的范围。 如需了解有关电子表格 ID 和 A1 表示法的详细信息，请参阅 Google Sheets API 中的主要概念。

输出的格式由三个可选参数控制：

请注意，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 控制是否解析输入字符串，如下表中所述：

单个更新和批处理更新方法将在下文介绍。 有关基本写入操作的示例，请参阅基本写入诀窍页面。

向单个范围写入数据

要向单个范围写入数据，请使用 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：

工作表中存在两个表格：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。