ToolJet Airtable 数据源接入指南：从连接配置到五种记录操作的完整实战

ToolJet Airtable 数据源接入指南从连接配置到五种记录操作的完整实战【免费下载链接】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 提供了开箱即用的 Airtable 数据源插件允许你在内部工具、仪表盘和业务应用中直接对 Airtable Base 进行读、写与删除操作。本文以 version-3.0.0-LTS 版本文档 为主线结合仓库中 Airtable 插件源码 与 测试用例系统讲解连接建立、五种受支持操作List records、Retrieve record、Create record、Update record、Delete record的参数细节、示例值与响应结构帮助你直接在 ToolJet 可视化编辑器中完成 Airtable 数据集成。一、建立 Airtable 数据源连接在 ToolJet 中接入 Airtable 有两种入口在应用编辑器的**查询面板Query Panel**中点击 Add new Data source按钮从 ToolJet 工作台左侧导航进入Data Sources页面添加。进入数据源列表后在 APIs 或对应分类下找到Airtable点击Add即可将数据源集成到当前工作区。数据源一旦添加到工作区同一工作区内的所有应用都可以共享使用参见 Data Sources 概览。1.1 认证方式Personal Access Token连接 Airtable 所需的核心凭据是Personal Access Token个人访问令牌你需要在 Airtable 个人账户的 Developer Hub开发者中心中创建并生成 Personal Access Token创建时建议按最小权限原则勾选所需作用域如data.records:read、data.records:write、schema.bases:read等。在 ToolJet 的数据源配置表单中将生成的令牌粘贴到Personal access token字段即可。从插件配置清单 manifest.json 可以看到该字段的完整定义{ properties: { personal_access_token: { type: string, title: Personal access token, description: Personal access token for airtable } }, tj:encrypted: [personal_access_token], required: [personal_access_token] }其中tj:encrypted声明该令牌在存储时会被加密required表明它是建立连接的必要字段。1.2 源码视角插件如何发起请求Airtable 插件的核心实现在 index.ts 中。它继承自统一的QueryService接口通过got库调用 Airtable REST APIauthHeader(token: string): Headers { return { Authorization: Bearer ${token}, Content-Type: application/json }; }在run()方法开头插件对旧式 API Key 做了向后兼容处理// Below condition for API Key is kept for Backward compatibility and needs migration to be removed later on. if (sourceOptions.api_key) apiToken sourceOptions.api_key; if (sourceOptions.personal_access_token) apiToken sourceOptions.personal_access_token;即优先使用personal_access_token仅当旧数据源仍配置了api_key时回退到 API Key——这也解释了为什么文档中明确要求使用 Personal Access Token 而非旧 API Key。类型定义见 types.ts。testConnection()方法通过调用https://api.airtable.com/v0/meta/whoami来验证令牌有效性若返回 401 状态码则会抛出 Authentication failed: Invalid personal access token 错误见 index.ts。因此保存数据源时 ToolJet 会真实校验令牌而不只是做格式检查。1.3 速率限制说明Airtable API 存在速率限制在编写本文档时其限制为每个 Base 每秒 5 次请求。当你在 ToolJet 中频繁触发查询尤其是依赖轮询或自动刷新的场景时需要自行控制调用频率否则可能收到 429 限流响应。完整速率限制说明以 Airtable API 官方文档 为准。二、在查询面板中发起 Airtable 查询连接建立后即可按以下步骤创建查询点击编辑器底部**查询管理器Query Manager**的 Add按钮在数据源下拉框中选择上一步添加的Airtable数据源从Operation下拉框中选择所需操作并填写对应参数点击Preview预览输出结果或点击Run执行查询。从 operations.json 可以看到操作下拉框由插件清单驱动共提供五种操作值list_records、retrieve_record、create_record、update_record、delete_record。每个操作都会动态渲染各自的参数字段类型为codehinter支持输入静态值或 {{ 表达式 }} 动态值。三、支持的五种记录操作详解操作对应 operation 值底层 HTTP 调用列出记录list_recordsPOST /v0/{baseId}/{table}/listRecords检索记录retrieve_recordGET /v0/{baseId}/{table}/{recordId}创建记录create_recordPOST /v0/{baseId}/{table}更新记录update_recordPATCH /v0/{baseId}/{table}删除记录delete_recordDELETE /v0/{baseId}/{table}/{recordId}说明底层 HTTP 端点来自 index.ts 的switch分支实现测试用例 airtable.test.js 亦按此五种操作逐一构造 nock mock 进行验证。3.1 List Records列出记录从指定表中检索记录列表。必填参数Base IDAirtable Base 的唯一标识符以app开头。Table name目标表的名称或表 ID以tbl开头。可选参数Page size每页返回的记录条数。Offset分页游标用于获取下一批记录。Filter by formula用于过滤记录的 Airtable 公式。Fields指定响应中需要包含的字段JSON 数组字符串。Timezone日期时间字段所使用的时区。User locale日期时间字段格式化所用的区域设置。Cell format单元格值的返回形式可选值json按字段类型返回 JSON 对象默认值string以字符串形式返回单元格值。View指定从哪个视图检索记录。Sort定义记录的排序方式字段 升序/降序方向。示例值完整参考Base ID: appO4WnRU3eTWnrDB Table name: tblAPbj6KMjS8pxhH // 可以是表名称或表 ID Page size: 100 Offset: itrU18e2y6ITuMs1n/recjR8UdOZKjZ7aK3 Fields: [Date, Email, Usage (# Weeks)] Filter by formula: IF({Usage (# Weeks)} 10, 1, 0) // 仅返回 Usage (# Weeks) 小于 10 的记录 Timezone: America/Chicago User locale: en-gb Cell format: string // Cell format 必须为 stringTimezone 与 User locale 才能生效 View: All Responses Sort: createdTime // 选择方向Ascending 或 Descending响应示例{ records: [ { id: recToGRP6bWUG6djd, createdTime: 2016-11-21T20:21:40.000Z, fields: { Usage (# Weeks): 3, Email: Edith Lindon, Date: 11-21-2016 } }, { id: recnUVJ8wwZbdECLk, createdTime: 2016-11-21T20:21:40.000Z, fields: { Usage (# Weeks): 3, Email: Marcellus Wong, Date: 11-21-2016 } }, { id: recStKhQYw4Fn2qpj, createdTime: 2016-11-21T20:21:40.000Z, fields: { Usage (# Weeks): 2, Email: Lorraine Ljuba, Date: 11-21-2016 } } ] }源码级细节Fields 参数解析插件会先对fields字符串执行JSON.parse若格式非法会抛出 Invalid JSON format for fields 错误index.ts因此输入必须是合法的 JSON 数组字符串。Page size 数值化pageSize会被转换为数字类型Number(pageSize)见 index.ts。Sort 处理排序参数经公共工具函数sanitizeSortPairs过滤掉空值后被转换为[{ field, direction }]结构提交见 index.ts 与 utils.helper.ts。底层调用的是 Airtable 的List Records 端点POST .../listRecords与老版 REST API 的 GET 分页方式不同见 index.ts。时区与区域设置的依赖关系Timezone 与 User locale 相互依赖提供了 timezone 就必须同时提供 user locale反之亦然。这两个属性仅在cell format 设置为 string时才生效。为了正确格式化日期时间字段请确保 Airtable 中列的类型设置为Date 或 Date Time。插件在构造请求体时对二者做了去首尾空格处理timezone.trim()、userLocale.trim()见 index.ts。3.2 Retrieve Record检索记录获取指定表中的单条记录。必填参数Base IDTable nameRecord ID目标记录的唯一标识以rec开头响应示例{ id: recu9xMnUdr2n2cw8, fields: { Notes: Discuss project timeline, Name: Michael Scott }, createdTime: 2021-05-12T14:30:33.000Z }源码级细节该操作直接向https://api.airtable.com/v0/{baseId}/{tableName}/{recordId}发起GET请求并解析响应体index.ts。测试用例以GET /v0/1/consumer/1模拟验证airtable.test.js。3.3 Create Record创建记录在指定表中创建一条或多条新记录。必填参数Base IDTable nameRecordsBody要创建的记录列表格式为 JSON 数组每项包含fields对象。示例Records 参数[{ fields: { Name: Katrina Petersons, Email: katrina.petersionsexample.com } }]响应示例{ records: [ { id: recu6jhA7tzv4K66s, createdTime: 2024-06-11T06:01:44.000Z, fields: { Name: Katrina Petersons, Email: katrina.petersionsexample.com, Date: 06-11-2024 } } ] }源码级细节插件将body参数经JSON.parse解析后包装成{ records: [...] }发送给POST /v0/{baseId}/{tableName}index.ts。表单中的 Records 输入框在 operations.json 中被定义为高度 150px 的多行 codehinter 编辑器placeholder 为[{ fields: {} }]便于粘贴整段 JSON。3.4 Update Record更新记录按 Record ID 更新指定记录的部分字段。必填参数Base IDTable nameRecord IDBody需要更新的字段对象JSON。示例Body 参数{ Email: katrina.petersions2example.com }响应示例{ records: [ { id: recu6jhA7tzv4K66s, createdTime: 2024-06-11T07:01:44.000Z, fields: { Name: Katrina Petersons, Email: katrina.petersions2example.com, Date: 06-11-2024 } } ] }源码级细节插件将{ id: record_id, fields: JSON.parse(body) }包装进records数组通过PATCH /v0/{baseId}/{tableName}提交index.ts。PATCH 语义意味着只更新 Body 中出现的字段未提及的字段保持不变测试用例以intercept(/v0/1/consumer, patch)模拟验证airtable.test.js。3.5 Delete Record删除记录从指定表中删除一条记录。必填参数Base IDTable nameRecord ID响应示例{ deleted: true, id: recIKsyZgqI4zoqS7 }源码级细节插件向DELETE /v0/{baseId}/{tableName}/{recordId}发起请求并解析响应index.ts。注意删除操作不可撤销建议在业务设计中加入二次确认或审计日志。四、错误处理与查询结果的使用错误处理插件在run()方法中对所有操作统一捕获异常index.ts若 Airtable 返回带响应体的错误插件会优先解析其中的message与error字段封装为QueryError抛出供查询面板展示明确的失败原因。结果绑定查询执行成功后的返回值结构统一为return { status: ok, data: result, };在 ToolJet 编辑器中你可以在其他组件的属性中通过{{ queries.查询名.data.records }}等方式引用查询结果例如将 List records 的结果直接绑定到 Table 组件的数据源实现可视化数据展示或将表单提交事件绑定到 Create/Update 操作实现写回 Airtable 的完整闭环。五、小结要点说明认证使用 Personal Access Token保存时经/v0/meta/whoami校验操作List / Retrieve / Create / Update / Delete 五种覆盖常见 CRUD分页List records 支持 page_size 与 offset 游标过滤排序支持 filter_by_formula、view、sortfield direction格式化timezone user_locale 必须成对使用且 cell format 需为 string限流每 Base 每秒约 5 次请求需控制调用频率通过以上配置你即可在 ToolJet 中像使用内部数据库一样操作 Airtable 数据将表格数据接入内部工具、看板与自动化工作流。相关实现可进一步查阅 Airtable 插件目录、插件类型定义 与 插件测试用例。【免费下载链接】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），仅供参考