Google Sheets 文档内工作表操作#

使用此操作可以在 Google 表格中创建、更新、清空或删除工作表。有关 Google Sheets 节点本身的更多信息，请参阅 Google Sheets 文档。

/// 注意 | 此节点可用作 AI 工具该节点可用于增强 AI 代理的能力。当以这种方式使用时，许多参数可以自动设置，或由 AI 提供信息进行配置 - 更多详情请参阅 AI 工具参数文档。 ///

追加或更新行#

使用此操作可以更新现有行，或者在数据表中找不到匹配项时在数据末尾添加新行。

输入以下参数：

连接凭证：创建或选择现有的 Google Sheets 凭证。
资源：选择 文档中的工作表。
操作：选择 追加或更新行。
文档：选择包含要追加或更新行的工作表的电子表格。
- 选择 从列表 从下拉列表中选择电子表格标题，通过 URL 输入电子表格的 URL，或 通过 ID 输入 spreadsheetId。
- 您可以在 Google Sheets 的 URL 中找到 spreadsheetId：https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0。
工作表：选择要追加或更新行的工作表。
- 选择 从列表 从下拉列表中选择工作表标题，通过 URL 输入工作表的 URL，通过 ID 输入 sheetId，或 通过名称 输入工作表标题。
- 您可以在 Google Sheets 的 URL 中找到 sheetId：https://docs.google.com/spreadsheets/d/aBC-123_xYz/edit#gid=sheetId。
映射列模式：
- 手动映射每列：为每列输入 要发送的值。
- 自动映射：n8n 会自动查找与 Google Sheets 中列匹配的传入数据。在此模式下，请确保传入数据字段与 Google Sheets 中的列相同。（如果需要，可以在此节点之前使用编辑字段节点进行更改。）
- 不映射：不映射任何数据。

选项#

单元格格式：使用此选项选择如何格式化单元格中的数据。更多信息请参考 Google Sheets API | CellFormat。
- 由 Google Sheets 格式化（默认）：n8n 根据 Google Sheets 的默认设置格式化单元格中的文本和数字。
- 由 n8n 格式化：工作表中的新单元格将保持与 n8n 提供的输入数据相同的数据类型。
数据在表格中的位置：当需要指定数据在工作表中的范围时使用此选项。
- 标题行：指定包含列标题的行索引。
- 首行数据：指定实际数据开始的行索引。
处理输入中的额外字段：当使用映射列模式 > 自动映射时，使用此选项决定如何处理输入数据中与工作表现有列不匹配的字段。
- 插入到新列（默认）：为任何额外数据添加新列。
- 忽略它们：忽略与现有列不匹配的额外数据。
- 报错：抛出错误并停止执行。
使用追加模式：启用此选项以使用 Google API 追加端点来添加新数据行。
- 默认情况下，n8n 会先追加空行或空列再添加新数据。这种方式可以确保数据对齐但效率较低。使用追加端点可以通过减少 API 调用次数和简化流程来提高性能。但如果现有工作表数据存在不一致（如行或列之间存在间隙或中断），n8n 可能会将新数据添加到错误位置，导致对齐问题。
- 当性能是优先考虑因素且工作表数据结构一致无间隙时使用此选项。

更多信息请参考 Method: spreadsheets.values.update | Google Sheets API 文档。

追加行#

使用此操作在表格数据末尾追加新行。

输入以下参数：

连接凭证：创建或选择现有的 Google Sheets 凭证。
资源：选择 文档中的工作表。
操作：选择 追加行。
文档：选择要追加行的电子表格。
- 选择 从列表 从下拉列表中选择电子表格标题，通过 URL 输入电子表格的 URL，或 通过 ID 输入 spreadsheetId。
- 您可以在 Google Sheets URL 中找到 spreadsheetId：https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0。
工作表：选择要追加行的工作表。
- 选择 从列表 从下拉列表中选择工作表标题，通过 URL 输入工作表的 URL，通过 ID 输入 sheetId，或 通过名称 输入工作表标题。
- 您可以在 Google Sheets URL 中找到 sheetId：https://docs.google.com/spreadsheets/d/aBC-123_xYz/edit#gid=sheetId。
列映射模式：
- 手动映射每列：查找要更新的行时选择 匹配列。为每列输入 要发送的值。
- 自动映射：n8n 会自动查找与 Google Sheets 中列匹配的传入数据。在此模式下，请确保传入数据字段与 Google Sheets 中的列相同。（如果需要，可以在此节点前使用编辑字段节点进行更改。）
- 不映射：不映射任何数据。

选项#

单元格格式：使用此选项选择如何格式化单元格中的数据。更多信息请参考 Google Sheets API | CellFormat。
- 由 Google Sheets 格式化（默认）：n8n 根据 Google Sheets 的默认设置格式化单元格中的文本和数字。
- 由 n8n 格式化：工作表中的新单元格将保持与 n8n 提供的输入数据相同的数据类型。
数据在表格中的位置：当需要指定数据在工作表中的范围时使用此选项。
- 标题行：指定包含列标题的行索引。
- 首行数据：指定实际数据开始的行索引。
处理输入中的额外字段：当使用映射列模式 > 自动映射时，使用此选项决定如何处理输入数据中与工作表现有列不匹配的字段。
- 插入到新列（默认）：为任何额外数据添加新列。
- 忽略它们：忽略与现有列不匹配的额外数据。
- 报错：抛出错误并停止执行。
使用追加模式：启用此选项以使用 Google API 追加端点来添加新数据行。
- 默认情况下，n8n 会先追加空行或空列再添加新数据。这种方式可以确保数据对齐但效率较低。使用追加端点可以通过减少 API 调用次数和简化流程来提高性能。但如果现有工作表数据存在不一致（如行或列之间存在间隙或中断），n8n 可能会将新数据添加到错误位置，导致对齐问题。
- 当性能是优先考虑因素且工作表数据结构一致无间隙时使用此选项。

更多信息请参考 Method: spreadsheets.values.append | Google Sheets API 文档。

清空工作表#

使用此操作可清空工作表中的所有数据。

输入以下参数：

连接凭证：创建或选择现有的 Google Sheets 凭证。
资源：选择 文档中的工作表。
操作：选择清空。
文档：选择包含要清空数据的工作表的电子表格。
- 选择 从列表 从下拉列表中选择电子表格标题，通过 URL 输入电子表格的 URL，或 通过 ID 输入 spreadsheetId。
- 您可以在 Google Sheets 的 URL 中找到 spreadsheetId：https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0。
工作表：选择要清空数据的工作表。
- 选择 从列表 从下拉列表中选择工作表标题，通过 URL 输入工作表的 URL，通过 ID 输入 sheetId，或 通过名称 输入工作表标题。
- 您可以在 Google Sheets 的 URL 中找到 sheetId：https://docs.google.com/spreadsheets/d/aBC-123_xYz/edit#gid=sheetId。
清空范围：选择要从工作表中清空的数据范围。
- 整个工作表：清空整个工作表的数据。开启 保留首行 可保留工作表的第一行。
- 特定行：清空特定行的数据。还需输入：
  - 起始行号：输入要清空的第一行行号。
  - 要删除的行数：输入要清空的行数。1 表示仅清空 起始行号 指定的行。
- 特定列：清空特定列的数据。还需输入：
  - 起始列：使用字母表示法输入要清空的第一列。
  - 要删除的列数：输入要清空的列数。1 表示仅清空 起始列 指定的列。
- 特定范围：以 A1 表示法输入要清空数据的表格范围。

更多信息请参考 Method: spreadsheets.values.clear | Google Sheets API 文档。

创建新工作表#

使用此操作可以创建一个新的工作表。

输入以下参数：

连接凭证：创建或选择现有的 Google Sheets 凭证。
资源：选择 文档内的工作表。
操作：选择创建。
文档：选择要在其中创建新工作表的电子表格。
- 选择 从列表 从下拉列表中选择电子表格标题，通过 URL 输入电子表格的 URL，或 通过 ID 输入 spreadsheetId。
- 您可以在 Google Sheets 的 URL 中找到 spreadsheetId：https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0。
标题：输入新工作表的标题。

选项#

隐藏：启用此选项可在界面中隐藏工作表。
从右到左：启用此选项使用 RTL（从右到左）工作表而非 LTR（从左到右）工作表。
工作表 ID：输入工作表的 ID。
- 您可以在 Google Sheets 的 URL 中找到 sheetId：https://docs.google.com/spreadsheets/d/aBC-123_xYz/edit#gid=sheetId
工作表索引：默认情况下，新工作表会作为电子表格中的最后一个工作表。要覆盖此行为，请输入您希望新工作表使用的索引。当您在指定索引处添加工作表时，Google 会递增所有后续工作表的索引。更多信息请参考 Sheets | SheetProperties 文档。
标签颜色：输入十六进制颜色代码或使用颜色选择器设置界面中标签的颜色。

更多信息请参考 Method: spreadsheets.batchUpdate | Google Sheets API 文档。

删除工作表#

使用此操作可永久删除工作表。

输入以下参数：

连接凭证：创建或选择现有的 Google Sheets 凭证。
资源：选择 文档中的工作表。
操作：选择删除。
文档：选择包含要删除工作表的电子表格。
- 选择 从列表 从下拉列表中选择电子表格标题，通过URL 输入电子表格的URL，或 通过ID 输入 spreadsheetId。
- 您可以在Google Sheets URL中找到 spreadsheetId：https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0。
工作表：选择要删除的工作表。
- 选择 从列表 从下拉列表中选择工作表标题，通过URL 输入工作表的URL，通过ID 输入 sheetId，或 通过名称 输入工作表的名称。
- 您可以在Google Sheets URL中找到 sheetId：https://docs.google.com/spreadsheets/d/aBC-123_xYz/edit#gid=sheetId。

更多信息请参考 Method: spreadsheets.batchUpdate | Google Sheets API文档。

删除行或列#

使用此操作可以删除工作表中的行或列。

输入以下参数：

连接凭证：创建或选择现有的 Google Sheets 凭证。
资源：选择 文档中的工作表。
操作：选择 删除行或列。
文档：选择包含要删除行或列的工作表的电子表格。
- 选择 从列表 从下拉列表中选择电子表格标题，通过 URL 输入电子表格的 URL，或 通过 ID 输入 spreadsheetId。
- 您可以在 Google Sheets 的 URL 中找到 spreadsheetId：https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0。
工作表：选择要删除行或列的工作表。
- 选择 从列表 从下拉列表中选择工作表标题，通过 URL 输入工作表的 URL，通过 ID 输入 sheetId，或 通过名称 输入工作表的名称。
- 您可以在 Google Sheets 的 URL 中找到 sheetId：https://docs.google.com/spreadsheets/d/aBC-123_xYz/edit#gid=sheetId。
起始行号 或 起始列：输入要开始删除的行号或列字母。
要删除的行数 或 要删除的列数：输入要删除的行数或列数。

更多信息请参考 Method: spreadsheets.batchUpdate | Google Sheets API 文档。

获取行数据#

使用此操作从工作表中读取一行或多行数据。

输入以下参数：

连接凭证：创建或选择现有的 Google Sheets 凭证。
资源类型：选择 文档中的工作表。
操作类型：选择 获取行数据。
文档：选择包含目标工作表的数据表。
- 选择 从列表 从下拉菜单中选择数据表标题，通过URL 输入数据表链接，或 通过ID 输入 spreadsheetId。
- 您可以在 Google Sheets 链接中找到 spreadsheetId：https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0。
工作表：选择要读取数据的工作表。
- 选择 从列表 从下拉菜单中选择工作表标题，通过URL 输入工作表链接，通过ID 输入 sheetId，或 通过名称 输入工作表名称。
- 您可以在 Google Sheets 链接中找到 sheetId：https://docs.google.com/spreadsheets/d/aBC-123_xYz/edit#gid=sheetId。
筛选条件：默认情况下，节点会返回工作表中的所有行。设置筛选条件可返回限定结果集：
- 列：选择要搜索的工作表列。
- 值：输入要搜索的单元格值。您可以在此处拖入输入数据参数。如果筛选条件匹配多行数据，n8n 将返回第一个结果。如需获取所有匹配行：
  1. 在选项下，选择 添加选项 > 当筛选条件有多项匹配时。
  2. 将 当筛选条件有多项匹配时 改为 返回所有匹配项。

选项#

数据在表格中的位置：使用此选项指定数据范围。默认情况下，n8n 会自动检测范围直到表格的最后一行。
输出格式：使用此选项选择 n8n 如何格式化 Google Sheets 返回的数据。
通用格式：
- 值（未格式化）（默认）：n8n 会移除货币符号和其他特殊格式。数据类型保持为数字。
- 值（格式化）：n8n 会按照 Google Sheets 中显示的方式展示值（例如保留逗号或货币符号），将数据类型从数字转换为字符串。
- 公式：n8n 返回公式本身，不计算公式输出。例如，如果单元格 B2 包含公式 =A2，n8n 会将 B2 的值返回为 =A2（文本形式）。更多信息请参考关于日期和时间值 | Google Sheets。
日期格式：更多信息请参考 DateTimeRenderOption | Google Sheets。
- 格式化文本（默认）：按照 Google Sheets 中显示的格式，取决于电子表格的区域设置。例如 01/01/2024。
- 序列号：自 1899 年 12 月 30 日以来的天数。
当筛选器有多个匹配项时：设置为返回所有匹配项以获取多个匹配结果。默认情况下只返回第一个结果。

首行

n8n 将 Google Sheet 中的第一行视为标题行，在读取所有行时不会返回该行。如需读取第一行，请使用选项设置数据在表格中的位置。

更多信息请参考方法：spreadsheets.batchUpdate | Google Sheets API 文档。

更新行#

使用此操作可以更新表格中现有的行。此操作仅更新已存在的行。若要在表格中找不到匹配项时追加行，请改用追加或更新行操作。

输入以下参数：

连接凭证：创建或选择现有的 Google Sheets 凭证。
资源：选择文档中的工作表。
操作：选择更新行。
文档：选择包含要更新工作表的电子表格。
- 选择从列表从下拉菜单中选择电子表格标题，通过URL输入电子表格的URL，或通过ID输入spreadsheetId。
- 您可以在Google Sheets的URL中找到spreadsheetId：https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0。
工作表：选择要更新的工作表。
- 选择从列表从下拉菜单中选择工作表标题，通过URL输入工作表的URL，通过ID输入sheetId，或通过名称输入工作表标题。
- 您可以在Google Sheets的URL中找到sheetId：https://docs.google.com/spreadsheets/d/aBC-123_xYz/edit#gid=sheetId。
列映射模式：
- 手动映射每列：为每列输入要发送的值。
- 自动映射：n8n会自动查找与Google Sheets中列匹配的传入数据。在此模式下，请确保传入数据字段与Google Sheets中的列相同。（如有需要，可在此节点前使用编辑字段节点进行修改。）
- 不映射：不映射任何数据。

选项#

单元格格式：使用此选项选择如何格式化单元格中的数据。更多信息请参考 Google Sheets API | CellFormat。
- 由 Google Sheets 格式化（默认）：n8n 会根据 Google Sheets 的默认设置格式化单元格中的文本和数字。
- 由 n8n 格式化：新单元格的数据类型将与 n8n 提供的输入数据类型保持一致。
数据在表格中的位置：当需要指定数据范围在表格中的位置时使用此选项。
- 标题行：指定包含列标题的行索引。
- 首行数据：指定实际数据开始的行索引。

更多信息请参阅 Method: spreadsheets.batchUpdate | Google Sheets API 文档。