googlesheets-automation

通过 Rube MCP 实现 Google Sheets 自动化

借助 Composio 的 Google Sheets 工具包，自动化 Google Sheets 工作流，包括读取/写入数据、管理电子表格与标签页、设置单元格格式、筛选行以及 upsert 记录。

前提条件

• Rube MCP 必须已连接（RUBE_SEARCH_TOOLS 可用）
• 通过 RUBE_MANAGE_CONNECTIONS 使用工具包 googlesheets 建立有效的 Google Sheets 连接
• 始终先调用 RUBE_SEARCH_TOOLS 以获取最新的工具 schema

设置

获取 Rube MCP：在你的客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥——只需添加该端点即可使用。

1. 通过确认 RUBE_SEARCH_TOOLS 有响应，验证 Rube MCP 可用
2. 使用工具包 googlesheets 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接不是 ACTIVE，请按照返回的授权链接完成 Google OAuth
4. 在运行任何工作流之前，确认连接状态显示为 ACTIVE

核心工作流

1. 读取和写入数据

使用场景：用户想要从 Google Sheet 读取数据或向其写入数据

工具顺序：

1. GOOGLESHEETS_SEARCH_SPREADSHEETS - 如果 ID 未知，按名称查找电子表格 [前提条件]
2. GOOGLESHEETS_GET_SHEET_NAMES - 枚举标签页名称以定位正确的 sheet [前提条件]
3. GOOGLESHEETS_BATCH_GET - 从一个或多个范围读取数据 [必需]
4. GOOGLESHEETS_BATCH_UPDATE - 将数据写入某个范围或追加行 [必需]
5. GOOGLESHEETS_VALUES_UPDATE - 更新单个特定范围 [替代方案]
6. GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND - 在表格末尾追加行 [替代方案]

关键参数：

• spreadsheet_id：来自电子表格 URL 的字母数字 ID（位于 '/d/' 和 '/edit' 之间）
• ranges：A1 表示法数组（例如 'Sheet1!A1:Z1000'）；始终使用有界范围
• sheet_name：标签页名称（支持不区分大小写匹配）
• values：二维数组，其中每个内部数组为一行
• first_cell_location：A1 表示法中的起始单元格（省略则追加）
• valueInputOption：'USER_ENTERED'（解析后）或 'RAW'（字面值）

易错点：

• 大小写错误或不存在的标签页名称会报错 "Sheet 'X' not found"
• 空范围可能会省略 valueRanges[i].values；将缺失视为空数组
• GOOGLESHEETS_BATCH_UPDATE 的 values 必须是二维数组（列表的列表），即使是单行也是如此
• 在超过 10,000 行的 sheet 上使用 'A:Z' 这类无界范围可能导致超时；始终用行限制来界定范围
• 追加会遵循检测到的 tableRange；使用返回的 updatedRange 验证放置位置

2. 创建和管理电子表格

使用场景：用户想要创建新电子表格或管理其中的标签页

工具顺序：

1. GOOGLESHEETS_CREATE_GOOGLE_SHEET1 - 创建新电子表格 [必需]
2. GOOGLESHEETS_ADD_SHEET - 添加新标签页/工作表 [必需]
3. GOOGLESHEETS_UPDATE_SHEET_PROPERTIES - 重命名、隐藏、重新排序或为标签页设置颜色 [可选]
4. GOOGLESHEETS_GET_SPREADSHEET_INFO - 获取完整的电子表格元数据 [可选]
5. GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE - 检查特定标签页是否存在 [可选]

关键参数：

• title：电子表格或 sheet 标签页名称
• spreadsheetId：目标电子表格 ID
• forceUnique：如果标签页名称已存在，自动追加后缀（默认 true）
• properties.gridProperties：设置行/列数、冻结行

易错点：

• Sheet 名称在同一个电子表格内必须唯一
• 默认 sheet 名称取决于语言环境（英文为 'Sheet1'，西班牙文为 'Hoja 1'）
• 并行创建多个 sheet 时不要使用 index（会导致 'index too high' 错误）
• 如果账户缺少访问权限，GOOGLESHEETS_GET_SPREADSHEET_INFO 可能返回 403

3. 搜索和筛选行

适用场景：用户想查找特定行或筛选工作表数据

工具调用顺序：

1. GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW - 查找与单元格值完全匹配的首行 [必需]
2. GOOGLESHEETS_SET_BASIC_FILTER - 对某个范围应用筛选/排序 [替代方案]
3. GOOGLESHEETS_CLEAR_BASIC_FILTER - 移除现有筛选条件 [可选]
4. GOOGLESHEETS_BATCH_GET - 读取筛选结果 [可选]

关键参数：

• query：要匹配的确切文本值（匹配整个单元格内容）
• range：要搜索的 A1 表示法范围
• case_sensitive：是否区分大小写的布尔值（默认值为 false）
• filter.range：包含 sheet_id 的基本筛选网格范围
• filter.criteria：基于列的筛选条件
• filter.sortSpecs：排序规范

注意事项：

• GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW 匹配整个单元格内容，而不是子字符串
• 名称中带空格的工作表必须在范围中加单引号（例如，"'My Sheet'!A:Z"）
• 查找不支持不带范围的工作表名称；务必指定范围

4. 按键值插入或更新行

适用场景：用户想根据唯一键列更新现有行或插入新行

工具调用顺序：

1. GOOGLESHEETS_UPSERT_ROWS - 更新匹配的行或追加新行 [必需]

关键参数：

• spreadsheetId：目标电子表格 ID
• sheetName：工作表标签名称
• keyColumn：用作唯一标识符的列标题名称（例如，'Email'、'SKU'）
• headers：数据的列名称列表
• rows：数据行的二维数组
• strictMode：列数不匹配时是否报错（默认值为 true）

注意事项：

• keyColumn 必须是实际的标题名称，而不是列字母（例如，'Email'，而不是 'A'）
• 如果未提供 headers，则将 rows 的第一行视为标题
• 当 strictMode=true 时，值的数量多于标题的行会导致错误
• 会自动将缺失的列添加到工作表中

5. 设置单元格格式

适用场景：用户想为单元格应用格式（粗体、颜色、字号）

工具调用顺序：

1. GOOGLESHEETS_GET_SPREADSHEET_INFO - 获取目标工作表标签的数字 sheetId [前置条件]
2. GOOGLESHEETS_FORMAT_CELL - 对某个范围应用格式 [必需]
3. GOOGLESHEETS_UPDATE_SHEET_PROPERTIES - 更改冻结行、列宽 [可选]

关键参数：

• spreadsheet_id：电子表格 ID
• worksheet_id：数字 sheetId（不是工作表标签名称）；通过 GET_SPREADSHEET_INFO 获取
• range：A1 表示法（例如，'A1:F1'）——优先于索引字段
• bold、italic、underline、strikethrough：布尔格式选项
• red、green、blue：背景颜色，取值为 0.0-1.0 的浮点数（不是 0-255 的整数）
• fontSize：字号，单位为点

注意事项：

• 需要数字 worksheet_id，而非工作表标签标题；从电子表格元数据中获取
• 颜色通道取值为 0-1 的浮点数（例如，纯红色为 1.0），而非 0-255 的整数
• 响应可能返回空回复对象（[{}]）；请通过回读验证格式
• 每次调用只能设置一个范围的格式；批量设置格式需要分别调用

常见模式

ID 解析

• 电子表格名称 -> ID：使用带有 query 的 GOOGLESHEETS_SEARCH_SPREADSHEETS
• 工作表标签名称 -> sheetId：使用 GOOGLESHEETS_GET_SPREADSHEET_INFO，从 sheets 元数据中提取
• 检查工作表标签是否存在：GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE

速率限制

Google Sheets 实施严格的速率限制：

• 每分钟最多读取 60 次、写入 60 次
• 超出限制会导致错误；尽可能使用批量操作
• 使用 GOOGLESHEETS_BATCH_GET 和 GOOGLESHEETS_BATCH_UPDATE 提高效率

数据模式

• 写入前务必先读取，以了解现有布局
• 对于 CRM 同步、库存更新和去重场景，使用 GOOGLESHEETS_UPSERT_ROWS
• 追加模式（省略 first_cell_location）是添加新记录最稳妥的方式
• 使用 GOOGLESHEETS_CLEAR_VALUES 清除内容，同时保留格式

已知陷阱

• 工作表名称：默认名称因区域设置而异；非英语账户中可能不存在“Sheet1”
• 范围表示法：名称中包含空格的工作表在 A1 表示法中需要用单引号括起来
• 无界范围：大型工作表可能导致超时；务必指定行范围（例如，“A1:Z10000”）
• 二维数组：所有值参数都必须是列表的列表，即使只有一行也不例外
• 颜色值：使用 0.0-1.0 的浮点数，而不是 0-255 的整数
• 格式设置 ID：FORMAT_CELL 需要数值型 sheetId，而不是工作表标签名称
• 速率限制：每分钟 60 次读取和 60 次写入；请使用批处理以避免超出限制
• 删除维度：GOOGLESHEETS_DELETE_DIMENSION 不可撤销；请仔细检查边界

快速参考

任务	工具标识	关键参数
搜索电子表格	GOOGLESHEETS_SEARCH_SPREADSHEETS	query, search_type
创建电子表格	GOOGLESHEETS_CREATE_GOOGLE_SHEET1	title
列出工作表标签	GOOGLESHEETS_GET_SHEET_NAMES	spreadsheet_id
添加工作表标签	GOOGLESHEETS_ADD_SHEET	spreadsheetId, title
读取数据	GOOGLESHEETS_BATCH_GET	spreadsheet_id, ranges
读取单个范围	GOOGLESHEETS_VALUES_GET	spreadsheet_id, range
写入数据	GOOGLESHEETS_BATCH_UPDATE	spreadsheet_id, sheet_name, values
更新范围	GOOGLESHEETS_VALUES_UPDATE	spreadsheet_id, range, values
追加行	GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND	spreadsheetId, range, values
插入或更新行	GOOGLESHEETS_UPSERT_ROWS	spreadsheetId, sheetName, keyColumn, rows
查找行	GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW	spreadsheet_id, query
设置单元格格式	GOOGLESHEETS_FORMAT_CELL	spreadsheet_id, worksheet_id, range
设置筛选器	GOOGLESHEETS_SET_BASIC_FILTER	spreadsheetId, filter
清除值	GOOGLESHEETS_CLEAR_VALUES	spreadsheet_id, range
删除行/列	GOOGLESHEETS_DELETE_DIMENSION	spreadsheet_id, sheet_name, dimension
电子表格信息	GOOGLESHEETS_GET_SPREADSHEET_INFO	spreadsheet_id
更新工作表标签属性	GOOGLESHEETS_UPDATE_SHEET_PROPERTIES	spreadsheetId, properties

数据和写入边界

连接预期的 Google 账户，并且只授予所需的电子表格权限范围；仅有 MCP 端点并不能授权访问。写入前，请确认电子表格 ID、工作表标签和确切范围。界面筛选器不会让读取的值仅包含可见行：请读取数据，并明确应用预期的筛选条件。对于不可信的纯文本，请使用 RAW；USER_ENTERED 可能会将内容解析为公式。检查插入或更新操作的键是否重复，以及是否存在并发写入者；如果追加结果不确定，应核对相应范围，而不是盲目重试。安排批量操作前，请确认实际项目/用户和方法适用的配额限制。

适用场景

当需要执行概述中所述的工作流或操作时，可以使用此技能。

示例

用户请求：

通过 Rube MCP（Composio）自动执行 Google Sheets 操作（读取、写入、格式设置、筛选、管理电子表格）。

限制

• 仅当任务明确符合上述范围时才使用此技能。
• 请勿将输出视为针对特定环境的验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。