ToolJet 接入 Google Sheets 數(shù)據(jù)源OAuth 配置、連接授權(quán)與 7 大增刪改查操作實(shí)戰(zhàn)指南【免費(fèi)下載鏈接】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 項(xiàng)目地址: https://gitcode.com/GitHub_Trending/to/ToolJetToolJet 內(nèi)置的 Google Sheets 數(shù)據(jù)源插件支持通過 OAuth 2.0 安全連接 Google 表格實(shí)現(xiàn)數(shù)據(jù)的讀取與寫入。本文基于 ToolJet 3.0.0-LTS 官方文檔與倉(cāng)庫(kù)中的插件源碼完整講解自托管部署下的環(huán)境變量配置、連接授權(quán)范圍選擇、查詢面板操作流程以及創(chuàng)建、讀取、追加、更新、刪除等全部?jī)?nèi)置操作的參數(shù)細(xì)節(jié)與底層實(shí)現(xiàn)原理幫助你直接在內(nèi)部工具、儀表盤與業(yè)務(wù)應(yīng)用中把 Google Sheets 當(dāng)作可讀寫的數(shù)據(jù)庫(kù)使用。連接能力概覽ToolJet 的 Google Sheets 數(shù)據(jù)源由倉(cāng)庫(kù)中的googlesheetsv2插件實(shí)現(xiàn)插件清單定義在 plugins/packages/googlesheetsv2/lib/manifest.json支持兩種認(rèn)證方式OAuth 2.0與Service Account服務(wù)賬號(hào)。無論采用哪種方式插件最終都會(huì)以BearerToken 的方式調(diào)用 Google Sheets API v4https://sheets.googleapis.com/v4/spreadsheets并額外申請(qǐng)drive.metadata.readonly權(quán)限用于枚舉用戶有權(quán)限訪問的表格列表。從源碼結(jié)構(gòu)看插件的運(yùn)行入口 plugins/packages/googlesheetsv2/lib/index.ts 負(fù)責(zé) OAuth 授權(quán)流程、Token 刷新與服務(wù)賬號(hào)令牌簽發(fā)而所有針對(duì)表格的具體請(qǐng)求讀取、追加、批量更新、刪除等都封裝在 plugins/packages/googlesheetsv2/lib/operations.ts 中。自托管配置Self-Hosted Configuration如果你使用的是 ToolJet 官方托管的云服務(wù)直接進(jìn)入「連接」章節(jié)即可但若是自托管部署則必須先完成以下三個(gè)步驟否則無法完成 OAuth 授權(quán)配置 Google OAuth 2.0 相關(guān)設(shè)置按照 Google OAuth 2.0 配置指南 中的步驟在 Google Cloud PlatformGCP控制臺(tái)創(chuàng)建 OAuth 憑據(jù)。設(shè)置環(huán)境變量將上一步獲取的值分別填入以下環(huán)境變量GOOGLE_CLIENT_IDGoogle OAuth 客戶端 IDGOOGLE_CLIENT_SECRETGoogle OAuth 客戶端密鑰TOOLJET_HOSTToolJet 實(shí)例的對(duì)外訪問地址用于拼裝 OAuth 回調(diào)地址{TOOLJET_HOST}/oauth2/authorize若配置了SUB_PATH子路徑也會(huì)被拼接在內(nèi)啟用 Google Sheets API在 GCP 控制臺(tái)中激活 Google Sheets API 服務(wù)。環(huán)境變量的官方說明同樣收錄于 docs/versioned_docs/version-3.0.0-LTS/setup/env-vars.md 的 Google OAuth 小節(jié)。在源碼中自托管模式對(duì)應(yīng)插件清單里的oauth_type: custom_app授權(quán)時(shí)使用client_id/client_secret字段即環(huán)境變量中配置的值而云端托管模式則使用tooljet_app由 ToolJet 平臺(tái)統(tǒng)一托管憑據(jù)見 plugins/packages/googlesheetsv2/lib/index.ts 中accessDetailsFrom與refreshToken的分支邏輯。建立連接Connection建立 Google Sheets 數(shù)據(jù)源連接有兩種入口點(diǎn)擊查詢面板中的 Add new Data source按鈕或通過 ToolJet 儀表盤進(jìn)入Data Sources頁面。授權(quán)范圍Authorization Scopes連接時(shí)需要在兩種權(quán)限范圍中二選一Read Only只讀僅允許讀取 Google Sheets 中的數(shù)據(jù)Read and Write讀寫同時(shí)授予讀取與修改寫入、追加、刪除權(quán)限。源碼中將此選擇映射為 Google OAuth 的 scope讀寫對(duì)應(yīng)https://www.googleapis.com/auth/spreadsheets只讀對(duì)應(yīng)https://www.googleapis.com/auth/spreadsheets.readonly并且始終附帶https://www.googleapis.com/auth/drive.metadata.readonly用于拉取表格列表見 plugins/packages/googlesheetsv2/lib/index.ts 的authUrl方法。因此如果你后續(xù)需要執(zhí)行寫入類操作Append / Update / Delete務(wù)必在連接時(shí)選擇Read and Write范圍。OAuth 授權(quán)完成后插件會(huì)將access_token與refresh_token保存在數(shù)據(jù)源憑據(jù)中當(dāng) Token 過期API 返回 401時(shí)refreshToken方法會(huì)調(diào)用https://oauth2.googleapis.com/token以grant_typerefresh_token自動(dòng)續(xù)期無需用戶重新授權(quán)。查詢 Google SheetsQuerying Google Sheet新建查詢的通用流程如下點(diǎn)擊編輯器底部查詢管理器中的 Add按鈕在數(shù)據(jù)源區(qū)域選擇Google Sheet數(shù)據(jù)源從操作下拉框中選擇所需操作點(diǎn)擊Preview按鈕預(yù)覽輸出或點(diǎn)擊Run按鈕創(chuàng)建并執(zhí)行查詢。通過 Google Sheets 數(shù)據(jù)源你可以在應(yīng)用中執(zhí)行以下操作創(chuàng)建電子表格列出電子表格中的所有工作表讀取電子表格數(shù)據(jù)向電子表格追加數(shù)據(jù)獲取電子表格信息更新電子表格單行數(shù)據(jù)從電子表格刪除行提示如何獲取 Spreadsheet IDSpreadsheet ID 可以從表格 URL 中提取。例如在 URLhttps://docs.google.com/spreadsheets/d/1W2S4re7zNaPk9vqv6_CqOpPdm_mDEqmLmzjVe7Nb9WM/edit#gid0中1W2S4re7zNaPk9vqv6_CqOpPdm_mDEqmLmzjVe7Nb9WM即 Spreadsheet ID。另外插件還內(nèi)置了getSpreadsheets/getSheets兩個(gè)動(dòng)態(tài)方法見 plugins/packages/googlesheetsv2/lib/index.ts 的invokeMethod操作表單中的 Spreadsheet、Sheet 下拉框可以自動(dòng)拉取并填充可選值也可以手動(dòng)輸入。創(chuàng)建電子表格Create a Spreadsheet該操作用于新建一個(gè)電子表格。必填參數(shù)Title新電子表格的標(biāo)題。源碼實(shí)現(xiàn)中createSpreadSheet會(huì)向POST https://sheets.googleapis.com/v4/spreadsheets發(fā)送{ properties: { title } }請(qǐng)求體成功后返回spreadsheetId、title與可訪問的spreadsheetUrl見 plugins/packages/googlesheetsv2/lib/operations.ts 的createSpreadSheet函數(shù)如果標(biāo)題為空會(huì)直接拋出Spreadsheet title is required錯(cuò)誤。列出電子表格中的所有工作表List All Sheets of a Spreadsheet該操作用于列出指定電子表格內(nèi)的所有工作表Sheet。必填參數(shù)Spreadsheet ID目標(biāo)電子表格 ID。對(duì)應(yīng)源碼為listAllSheets請(qǐng)求GET https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet_id}并僅返回響應(yīng)中的sheets數(shù)組每個(gè)元素包含工作表元數(shù)據(jù)如properties.title、properties.sheetId見 plugins/packages/googlesheetsv2/lib/operations.ts。讀取電子表格數(shù)據(jù)Read Data From a Spreadsheet該操作將表格中的數(shù)據(jù)以JSON 對(duì)象數(shù)組的形式返回第一行作為表頭字段名后續(xù)每一行成為一個(gè)對(duì)象。必填參數(shù)Spreadsheet ID目標(biāo)電子表格 ID?？蛇x參數(shù)Range讀取范圍默認(rèn)值為A1:Z500源碼中run方法對(duì)未填寫的范圍會(huì)回退到該默認(rèn)值Sheet工作表名稱留空時(shí)使用第一個(gè)工作表。底層實(shí)現(xiàn)上插件請(qǐng)求GET https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{sheet}!{range}然后在readDataFromSheet函數(shù)中把二維數(shù)組按首行表頭重組為對(duì)象數(shù)組見 plugins/packages/googlesheetsv2/lib/operations.ts。同時(shí)該操作還支持三個(gè)可選渲染參數(shù)在操作配置中可手動(dòng)選擇Major DimensionsROWS默認(rèn)按行返回或COLUMNS按列返回Value renderFORMATTED_VALUE默認(rèn)返回格式化后的顯示值、UNFORMATTED_VALUE或FORMULA返回公式文本Date TimeSERIAL_NUMBER默認(rèn)日期以序列號(hào)返回或FORMATTED_STRING以格式化字符串返回。這些參數(shù)會(huì)作為查詢字符串附加到讀取請(qǐng)求 URL 中見 plugins/packages/googlesheetsv2/lib/operations.ts 的makeRequestToReadValues函數(shù)。向電子表格追加數(shù)據(jù)Append Data to a Spreadsheet該操作用于在表格末尾追加新行。必填參數(shù)Spreadsheet ID目標(biāo)電子表格 IDRows待追加的數(shù)據(jù)為 JSON 對(duì)象數(shù)組每個(gè)對(duì)象的鍵對(duì)應(yīng)表頭列名?？蛇x參數(shù)Sheet工作表名稱留空時(shí)使用第一個(gè)工作表。示例 Rows 數(shù)據(jù)[ { 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 } ]追加時(shí)插件會(huì)先讀取表頭行A1:Z1確定列順序再把每個(gè)對(duì)象按鍵映射到對(duì)應(yīng)列的位置最終調(diào)用POST https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{sheet}!A:Z:append?valueInputOptionUSER_ENTERED寫入見 plugins/packages/googlesheetsv2/lib/operations.ts 的appendDataToSheet。注意Rows 參數(shù)在源碼中會(huì)經(jīng)過JSON.parse處理因此必須傳入合法的 JSON 數(shù)組文本。獲取電子表格信息Get Spreadsheet Info該操作返回電子表格的基礎(chǔ)信息包括工作表數(shù)量、主題theme、時(shí)區(qū)time zone、格式format以及 URL 等。該操作僅需Spreadsheet ID。實(shí)現(xiàn)上由插件run方法直接調(diào)用GET https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}并將完整響應(yīng)原樣返回見 plugins/packages/googlesheetsv2/lib/index.ts 中case info分支。更新電子表格單行數(shù)據(jù)Update Single Row of a Spreadsheet該操作根據(jù)條件定位行并更新該行中指定字段的值。必填參數(shù)Spreadsheet ID目標(biāo)電子表格 IDWhere條件字段要匹配的列名Operator比較運(yùn)算符當(dāng)前版本僅支持Value條件字段需要匹配的值Body要寫入的字段與值組成的 JSON 對(duì)象。可選參數(shù)Range查詢范圍默認(rèn)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方式讀取指定范圍的數(shù)據(jù)用WhereOperator()找到所有滿足條件的行號(hào)getRowsIndex把 Body 中每個(gè)鍵映射為對(duì)應(yīng)的列字母超過 26 列時(shí)自動(dòng)轉(zhuǎn)換為AA、AB等多字母列號(hào)組合成{sheet}!{列字母}{行號(hào)}單元格地址最后通過POST .../values:batchUpdate一次性批量寫入valueInputOption固定為USER_ENTERED。如果找不到匹配行g(shù)etRowsIndex返回 -1則不會(huì)發(fā)生任何更新因此請(qǐng)確保 Where 字段的值與表格中的實(shí)際值完全一致。從電子表格刪除行Delete Row From a Spreadsheet該操作刪除指定工作表中的某一行。必填參數(shù)Spreadsheet ID目標(biāo)電子表格 IDDelete row number要?jiǎng)h除的行號(hào)從 1 開始計(jì)數(shù)。可選參數(shù)GID工作表標(biāo)識(shí)在操作表單中為 Sheet 下拉框選擇目標(biāo)工作表。底層實(shí)現(xiàn)中插件首先根據(jù)工作表名稱解析出其內(nèi)部sheetIdgetSheetId未指定時(shí)使用第一個(gè)工作表然后調(diào)用POST https://sheets.googleapis.com/v4/spreadsheets/{id}:batchUpdate構(gòu)造deleteDimension請(qǐng)求刪除startIndex rowIndex - 1到endIndex rowIndex的整行見 plugins/packages/googlesheetsv2/lib/operations.ts 的deleteDataFromSheet。注意行號(hào)基于表格中的物理行位置刪除后下方數(shù)據(jù)會(huì)上移。進(jìn)階操作源碼中可用的擴(kuò)展能力除官方文檔列出的 7 項(xiàng)操作外googlesheetsv2插件的操作清單plugins/packages/googlesheetsv2/lib/operations.json還注冊(cè)了以下擴(kuò)展操作可按需選用List all spreadsheets分頁列出 Drive 中有權(quán)限的所有電子表格支持page_size、page_token與filter如name contains report底層調(diào)用 Drive API v3Delete data from a spreadsheet by data filter按數(shù)據(jù)過濾器批量清除數(shù)據(jù)batchClearByDataFilterBulk update using primary key以指定列為主鍵primary_key批量更新已存在行的單元格主鍵不存在的記錄自動(dòng)追加為新行Copy data between spreadsheets將一個(gè)電子表格的范圍數(shù)據(jù)復(fù)制到另一個(gè)電子表格Delete data from a spreadsheet by range刪除指定 A1 范圍如A1:C5的數(shù)據(jù)可指定ROWS或COLUMNS位移方向Update a spreadsheet直接向指定范圍寫入二維數(shù)組值values支持RAW、USER_ENTERED、FORMULA三種輸入選項(xiàng)默認(rèn)USER_ENTERED。這些操作與文檔中的 7 大操作共同構(gòu)成了完整的 Google Sheets 讀寫能力矩陣你可以在查詢編輯器中直接選用。常見問題與注意事項(xiàng)只能讀不能寫檢查連接數(shù)據(jù)源時(shí)選擇的授權(quán)范圍是否為Read and Write只讀范圍下寫入類操作會(huì)因 scope 不足返回 403 錯(cuò)誤源碼中 403 會(huì)以 QueryError 形式將 Google 原始錯(cuò)誤信息透?jìng)鹘o用戶而不是靜默重定向。OAuth 回調(diào)失敗自托管部署時(shí)確認(rèn)TOOLJET_HOST以及SUB_PATH配置正確Google Cloud Console 中 OAuth 重定向 URI 必須包含{TOOLJET_HOST}/oauth2/authorize。Token 過期插件內(nèi)置了自動(dòng)刷新機(jī)制若刷新失敗如 refresh_token 丟失查詢會(huì)提示重新授權(quán)。從源碼看refreshToken與accessDetailsFrom均依賴環(huán)境變量GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRETtooljet_app模式或數(shù)據(jù)源中保存的client_id/client_secretcustom_app模式。服務(wù)賬號(hào)Service Account方式在連接時(shí)選擇 Service Account 認(rèn)證粘貼 JSON 格式的服務(wù)賬號(hào)私鑰即可無需 OAuth 交互授權(quán)插件會(huì)用googleapis的 JWT 客戶端簽發(fā)訪問令牌且連接測(cè)試Test Connection僅對(duì)服務(wù)賬號(hào)模式開放。注意服務(wù)賬號(hào)需要先在 Google Sheets 中把其郵箱添加為協(xié)作者才能訪問對(duì)應(yīng)表格。【免費(fèi)下載鏈接】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 項(xiàng)目地址: https://gitcode.com/GitHub_Trending/to/ToolJet創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考