ToolJet 接入 Google Sheets 数据源OAuth 配置、连接授权与 7 大增删改查操作实战指南【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJetToolJet 内置的 Google Sheets 数据源插件支持通过 OAuth 2.0 安全连接 Google 表格实现数据的读取与写入。本文基于 ToolJet 3.0.0-LTS 官方文档与仓库中的插件源码完整讲解自托管部署下的环境变量配置、连接授权范围选择、查询面板操作流程以及创建、读取、追加、更新、删除等全部内置操作的参数细节与底层实现原理帮助你直接在内部工具、仪表盘与业务应用中把 Google Sheets 当作可读写的数据库使用。连接能力概览ToolJet 的 Google Sheets 数据源由仓库中的googlesheetsv2插件实现插件清单定义在 plugins/packages/googlesheetsv2/lib/manifest.json支持两种认证方式OAuth 2.0与Service Account服务账号。无论采用哪种方式插件最终都会以BearerToken 的方式调用 Google Sheets API v4https://sheets.googleapis.com/v4/spreadsheets并额外申请drive.metadata.readonly权限用于枚举用户有权限访问的表格列表。从源码结构看插件的运行入口 plugins/packages/googlesheetsv2/lib/index.ts 负责 OAuth 授权流程、Token 刷新与服务账号令牌签发而所有针对表格的具体请求读取、追加、批量更新、删除等都封装在 plugins/packages/googlesheetsv2/lib/operations.ts 中。自托管配置Self-Hosted Configuration如果你使用的是 ToolJet 官方托管的云服务直接进入「连接」章节即可但若是自托管部署则必须先完成以下三个步骤否则无法完成 OAuth 授权配置 Google OAuth 2.0 相关设置按照 Google OAuth 2.0 配置指南 中的步骤在 Google Cloud PlatformGCP控制台创建 OAuth 凭据。设置环境变量将上一步获取的值分别填入以下环境变量GOOGLE_CLIENT_IDGoogle OAuth 客户端 IDGOOGLE_CLIENT_SECRETGoogle OAuth 客户端密钥TOOLJET_HOSTToolJet 实例的对外访问地址用于拼装 OAuth 回调地址{TOOLJET_HOST}/oauth2/authorize若配置了SUB_PATH子路径也会被拼接在内启用 Google Sheets API在 GCP 控制台中激活 Google Sheets API 服务。环境变量的官方说明同样收录于 docs/versioned_docs/version-3.0.0-LTS/setup/env-vars.md 的 Google OAuth 小节。在源码中自托管模式对应插件清单里的oauth_type: custom_app授权时使用client_id/client_secret字段即环境变量中配置的值而云端托管模式则使用tooljet_app由 ToolJet 平台统一托管凭据见 plugins/packages/googlesheetsv2/lib/index.ts 中accessDetailsFrom与refreshToken的分支逻辑。建立连接Connection建立 Google Sheets 数据源连接有两种入口点击查询面板中的 Add new Data source按钮或通过 ToolJet 仪表盘进入Data Sources页面。授权范围Authorization Scopes连接时需要在两种权限范围中二选一Read Only只读仅允许读取 Google Sheets 中的数据Read and Write读写同时授予读取与修改写入、追加、删除权限。源码中将此选择映射为 Google OAuth 的 scope读写对应https://www.googleapis.com/auth/spreadsheets只读对应https://www.googleapis.com/auth/spreadsheets.readonly并且始终附带https://www.googleapis.com/auth/drive.metadata.readonly用于拉取表格列表见 plugins/packages/googlesheetsv2/lib/index.ts 的authUrl方法。因此如果你后续需要执行写入类操作Append / Update / Delete务必在连接时选择Read and Write范围。OAuth 授权完成后插件会将access_token与refresh_token保存在数据源凭据中当 Token 过期API 返回 401时refreshToken方法会调用https://oauth2.googleapis.com/token以grant_typerefresh_token自动续期无需用户重新授权。查询 Google SheetsQuerying Google Sheet新建查询的通用流程如下点击编辑器底部查询管理器中的 Add按钮在数据源区域选择Google Sheet数据源从操作下拉框中选择所需操作点击Preview按钮预览输出或点击Run按钮创建并执行查询。通过 Google Sheets 数据源你可以在应用中执行以下操作创建电子表格列出电子表格中的所有工作表读取电子表格数据向电子表格追加数据获取电子表格信息更新电子表格单行数据从电子表格删除行提示如何获取 Spreadsheet IDSpreadsheet ID 可以从表格 URL 中提取。例如在 URLhttps://docs.google.com/spreadsheets/d/1W2S4re7zNaPk9vqv6_CqOpPdm_mDEqmLmzjVe7Nb9WM/edit#gid0中1W2S4re7zNaPk9vqv6_CqOpPdm_mDEqmLmzjVe7Nb9WM即 Spreadsheet ID。另外插件还内置了getSpreadsheets/getSheets两个动态方法见 plugins/packages/googlesheetsv2/lib/index.ts 的invokeMethod操作表单中的 Spreadsheet、Sheet 下拉框可以自动拉取并填充可选值也可以手动输入。创建电子表格Create a Spreadsheet该操作用于新建一个电子表格。必填参数Title新电子表格的标题。源码实现中createSpreadSheet会向POST https://sheets.googleapis.com/v4/spreadsheets发送{ properties: { title } }请求体成功后返回spreadsheetId、title与可访问的spreadsheetUrl见 plugins/packages/googlesheetsv2/lib/operations.ts 的createSpreadSheet函数如果标题为空会直接抛出Spreadsheet title is required错误。列出电子表格中的所有工作表List All Sheets of a Spreadsheet该操作用于列出指定电子表格内的所有工作表Sheet。必填参数Spreadsheet ID目标电子表格 ID。对应源码为listAllSheets请求GET https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet_id}并仅返回响应中的sheets数组每个元素包含工作表元数据如properties.title、properties.sheetId见 plugins/packages/googlesheetsv2/lib/operations.ts。读取电子表格数据Read Data From a Spreadsheet该操作将表格中的数据以JSON 对象数组的形式返回第一行作为表头字段名后续每一行成为一个对象。必填参数Spreadsheet ID目标电子表格 ID。可选参数Range读取范围默认值为A1:Z500源码中run方法对未填写的范围会回退到该默认值Sheet工作表名称留空时使用第一个工作表。底层实现上插件请求GET https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{sheet}!{range}然后在readDataFromSheet函数中把二维数组按首行表头重组为对象数组见 plugins/packages/googlesheetsv2/lib/operations.ts。同时该操作还支持三个可选渲染参数在操作配置中可手动选择Major DimensionsROWS默认按行返回或COLUMNS按列返回Value renderFORMATTED_VALUE默认返回格式化后的显示值、UNFORMATTED_VALUE或FORMULA返回公式文本Date TimeSERIAL_NUMBER默认日期以序列号返回或FORMATTED_STRING以格式化字符串返回。这些参数会作为查询字符串附加到读取请求 URL 中见 plugins/packages/googlesheetsv2/lib/operations.ts 的makeRequestToReadValues函数。向电子表格追加数据Append Data to a Spreadsheet该操作用于在表格末尾追加新行。必填参数Spreadsheet ID目标电子表格 IDRows待追加的数据为 JSON 对象数组每个对象的键对应表头列名。可选参数Sheet工作表名称留空时使用第一个工作表。示例 Rows 数据[ { name: John, email: johntooljet.com, date: 2024-09-16, status: Confirmed, phone: 123456789 }, { name: Jane, email: janetooljet.com, date: 2024-09-17, status: Pending, phone: 987654321 }, { name: Doe, email: doetooljet.com, date: 2024-09-18, status: Cancelled, phone: 112233445 } ]追加时插件会先读取表头行A1:Z1确定列顺序再把每个对象按键映射到对应列的位置最终调用POST https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{sheet}!A:Z:append?valueInputOptionUSER_ENTERED写入见 plugins/packages/googlesheetsv2/lib/operations.ts 的appendDataToSheet。注意Rows 参数在源码中会经过JSON.parse处理因此必须传入合法的 JSON 数组文本。获取电子表格信息Get Spreadsheet Info该操作返回电子表格的基础信息包括工作表数量、主题theme、时区time zone、格式format以及 URL 等。该操作仅需Spreadsheet ID。实现上由插件run方法直接调用GET https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}并将完整响应原样返回见 plugins/packages/googlesheetsv2/lib/index.ts 中case info分支。更新电子表格单行数据Update Single Row of a Spreadsheet该操作根据条件定位行并更新该行中指定字段的值。必填参数Spreadsheet ID目标电子表格 IDWhere条件字段要匹配的列名Operator比较运算符当前版本仅支持Value条件字段需要匹配的值Body要写入的字段与值组成的 JSON 对象。可选参数Range查询范围默认A1:Z500Sheet工作表名称。示例 Body{ id: 456, company: ABC Tech Solutions, position: Product Manager, url: https://abctech.com/careers, date-applied: 2024-09-10, status: Application Under Review }更新流程分两步见 plugins/packages/googlesheetsv2/lib/operations.ts 的batchUpdateToSheet与makeRequestBodyToBatchUpdate以majorDimensionCOLUMNS方式读取指定范围的数据用WhereOperator()找到所有满足条件的行号getRowsIndex把 Body 中每个键映射为对应的列字母超过 26 列时自动转换为AA、AB等多字母列号组合成{sheet}!{列字母}{行号}单元格地址最后通过POST .../values:batchUpdate一次性批量写入valueInputOption固定为USER_ENTERED。如果找不到匹配行getRowsIndex返回 -1则不会发生任何更新因此请确保 Where 字段的值与表格中的实际值完全一致。从电子表格删除行Delete Row From a Spreadsheet该操作删除指定工作表中的某一行。必填参数Spreadsheet ID目标电子表格 IDDelete row number要删除的行号从 1 开始计数。可选参数GID工作表标识在操作表单中为 Sheet 下拉框选择目标工作表。底层实现中插件首先根据工作表名称解析出其内部sheetIdgetSheetId未指定时使用第一个工作表然后调用POST https://sheets.googleapis.com/v4/spreadsheets/{id}:batchUpdate构造deleteDimension请求删除startIndex rowIndex - 1到endIndex rowIndex的整行见 plugins/packages/googlesheetsv2/lib/operations.ts 的deleteDataFromSheet。注意行号基于表格中的物理行位置删除后下方数据会上移。进阶操作源码中可用的扩展能力除官方文档列出的 7 项操作外googlesheetsv2插件的操作清单plugins/packages/googlesheetsv2/lib/operations.json还注册了以下扩展操作可按需选用List all spreadsheets分页列出 Drive 中有权限的所有电子表格支持page_size、page_token与filter如name contains report底层调用 Drive API v3Delete data from a spreadsheet by data filter按数据过滤器批量清除数据batchClearByDataFilterBulk update using primary key以指定列为主键primary_key批量更新已存在行的单元格主键不存在的记录自动追加为新行Copy data between spreadsheets将一个电子表格的范围数据复制到另一个电子表格Delete data from a spreadsheet by range删除指定 A1 范围如A1:C5的数据可指定ROWS或COLUMNS位移方向Update a spreadsheet直接向指定范围写入二维数组值values支持RAW、USER_ENTERED、FORMULA三种输入选项默认USER_ENTERED。这些操作与文档中的 7 大操作共同构成了完整的 Google Sheets 读写能力矩阵你可以在查询编辑器中直接选用。常见问题与注意事项只能读不能写检查连接数据源时选择的授权范围是否为Read and Write只读范围下写入类操作会因 scope 不足返回 403 错误源码中 403 会以 QueryError 形式将 Google 原始错误信息透传给用户而不是静默重定向。OAuth 回调失败自托管部署时确认TOOLJET_HOST以及SUB_PATH配置正确Google Cloud Console 中 OAuth 重定向 URI 必须包含{TOOLJET_HOST}/oauth2/authorize。Token 过期插件内置了自动刷新机制若刷新失败如 refresh_token 丢失查询会提示重新授权。从源码看refreshToken与accessDetailsFrom均依赖环境变量GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRETtooljet_app模式或数据源中保存的client_id/client_secretcustom_app模式。服务账号Service Account方式在连接时选择 Service Account 认证粘贴 JSON 格式的服务账号私钥即可无需 OAuth 交互授权插件会用googleapis的 JWT 客户端签发访问令牌且连接测试Test Connection仅对服务账号模式开放。注意服务账号需要先在 Google Sheets 中把其邮箱添加为协作者才能访问对应表格。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考