Node-RED Contrib for Feishu Bitable

这是一个为 Node-RED 创建的自定义节点包，用于通过飞书/Lark 开放平台的 服务端 API 操作多维表格 (Bitable)。它允许您在 Node-RED 的流编辑器中以拖拽的方式，轻松实现对多维表格数据的增、删、改、查 (CRUD) 等操作。

所有节点都归属于统一的 Feishu Bitable 分类下，方便查找和使用。

功能节点

本节点包提供以下三个核心节点：

1. Bitable 认证配置 (lark-bitable-config): 一个配置节点，用于安全地存储飞书应用的 App ID 和 App Secret，并自动获取和刷新 tenant_access_token，为其他节点提供统一的认证支持。
2. Bitable 记录 (lark-bitable-record): 核心操作节点，用于对指定表格中的记录执行列表 (List)、获取 (Get)、创建 (Create)、更新 (Update) 和 删除 (Delete) 操作。
3. Bitable 表 (lark-bitable-table): 辅助节点，用于列出指定 Base (App) 下的所有表 (listTables) 或获取单个表的元信息 (getTableMeta)。

安装与加载

有两种方式可以将此节点包加载到您的 Node-RED 环境中：

方式一：直接复制文件夹 (推荐)

1. 将整个 node-red-contrib-feishu-bitable 文件夹复制到您的 Node-RED 用户目录下的 nodes 文件夹中。Node-RED 的用户目录通常是：
   • Windows: C:\Users\<YourUsername>\.node-red\nodes
   • Linux/macOS: ~/.node-red/nodes
2. 在 ~/.node-red 目录下运行 npm install axios 来安装依赖。
3. 重启您的 Node-RED 服务。

方式二：使用 npm 链接 (适用于开发)

1. 将 node-red-contrib-feishu-bitable 文件夹放置在任意位置。
2. 打开终端，进入该文件夹，运行 npm install 来安装依赖。
3. 然后，进入您的 Node-RED 用户目录 (~/.node-red)，运行以下命令来创建一个符号链接：

   npm link /path/to/your/node-red-contrib-feishu-bitable

4. 重启 Node-RED 服务。

重启后，您应该能在左侧的节点面板中看到一个新的分类 Feishu Bitable，其中包含了“Bitable 记录”和“Bitable 表”两个节点。

使用说明

1. 配置认证节点 (lark-bitable-config)

在使用任何操作节点之前，您必须先添加并配置一个认证节点。

1. 在流中拖入一个“Bitable 记录”或“Bitable 表”节点，双击打开其编辑界面。
2. 在“认证配置”字段旁边，点击铅笔图标来添加一个新的 lark-bitable-config 节点。
3. 在弹出的配置窗口中，填写以下信息：
   • 名称: 为此配置起一个易于识别的名字，例如“我的 Bitable 认证”。
   • Base URL: 飞书/Lark API 的根地址。默认为 https://open.larkoffice.com (国际版)。如果使用国内版飞书，请修改为 https://open.feishu.cn。
   • App ID: 您在飞书开放平台创建的企业自建应用的 App ID。
   • App Secret: 对应应用的 App Secret。此字段为凭据类型，其值会被 Node-RED 安全存储，不会随流程导出。
4. 点击“添加”按钮保存配置。

2. 获取 app_token 和 table_id

操作节点需要 app_token (即 Base 的唯一标识) 和 table_id (表的唯一标识)。您可以按以下方式获取：

1. 打开您的飞书多维表格。
2. 在浏览器地址栏中，URL 的结构通常如下： https://<domain>/base/<app_token>/table/<table_id>?...
3. 从 URL 中复制对应的 app_token 和 table_id 值，并填入节点的相应字段中。

3. 导入示例 Flow

为了快速上手，您可以导入项目 examples 目录下的 bitable_crud_flow.json 文件。

1. 点击 Node-RED 右上角的菜单按钮，选择 导入。
2. 选择“从文件上传”，然后选中 bitable_crud_flow.json 文件。
3. 导入后，您会看到一个包含了所有基本操作的示例流程。

4. 拖拽与编排

• 触发: 使用 Inject 节点来手动触发流程。
• 传递参数: 您可以在 Inject 节点中设置 msg 对象的属性 (如 msg.app_token, msg.table_id, msg.record_id, msg.payload) 来动态传递参数给 Bitable 节点。如果节点自身的配置字段为空，它会尝试从 msg 对象中读取同名参数。
• 创建/更新数据: 对于“创建”和“更新”操作，您有两种方式提供要写入的数据：
  1. 字段 JSON: 在节点的 fieldsJson 文本框中直接写入一个 JSON 对象，例如 {"字段A": "值1", "字段B": 123}。
  2. msg.payload: 将节点的 fieldsJson 留空，然后通过上游节点将一个 JSON 对象赋值给 msg.payload。
• 查看结果: 连接一个 Debug 节点到 Bitable 节点的输出端，并将 Debug 节点的输出设置为“完整的 msg 对象”，以查看 API 返回的完整结果。

常见错误与调试

• 401 Unauthorized / 认证失败:

  • 检查您的 App ID 和 App Secret 是否正确。
  • 确保您的应用已在飞书开放平台发布，并具备访问多维表格的权限。
  • 检查 Base URL 是否与您所在的服务器匹配（国内版 vs 国际版）。

• 参数错误 (如 invalid params):

  • 确认 app_token 和 table_id 是否正确无误。
  • 对于“创建/更新”，检查 fieldsJson 或 msg.payload 中的字段名是否与表格中的字段名完全一致。
  • 对于“获取/更新/删除”，确保 record_id 是有效的。

• 接口速率限制:

  • 飞书 API 对请求频率有限制。如果您在短时间内大量触发节点，可能会收到速率限制的错误。请在两次请求之间加入适当的延时 (例如使用 Delay 节点)。

• 国内与国际域名切换:

  • 请在 lark-bitable-config 配置节点中正确设置 Base URL。
  • 国内版飞书: https://open.feishu.cn
  • 国际版 Lark: https://open.larkoffice.com 或 https://open.larksuite.com

查看飞书具体错误

当 API 调用失败时，节点会在输出消息中附加 msg.feishuError，包含服务器返回的 code、msg、data（如有）、httpStatus，以及隐私安全的请求概要 request: { url, method, params, bodyKeys }（不包含 Authorization 令牌，也不包含原始请求体）。

使用方法：将一个 Debug 节点连接到 Bitable 节点的输出，并把 Debug 节点的输出设置为“完整的 msg 对象”。在调试面板中查看 msg.feishuError，即可快速定位参数格式错误、缺失字段或权限问题。

刷新表列表按钮（动态加载）

• 在节点编辑窗的 App Token 字段右侧新增了“刷新表列表”按钮。点击后，编辑器会调用内置管理端点：
  • GET /feishu-bitable/tables/{configId}/{app_token}
  • 后端会使用认证配置获取 tenant_access_token，请求 /open-apis/bitable/v1/apps/{app_token}/tables 并返回表列表；前端据此将 Table ID 字段切换为可下拉选择的 TypedInput。
• 使用步骤：
  1. 选择或创建认证配置（lark-bitable-config），并填写 App Token（可从多维表格 URL 中的 base/<app_token> 片段复制）。
  2. 点击“刷新表列表”，成功后即可在 Table ID 的下拉框里选择具体表（展示名称与 table_id）。
  3. 若未拉到任何表，请检查：应用是否被添加为该文档的协作者、Base URL 是否与所在区域一致（国内/国际）、app_token 是否正确。

权限说明（读与写）

• 只读操作（list、get、listTables、getTableMeta）需要为应用开通读取权限（例如 bitable:app:readonly 或相关读取范围）。
• 写操作（create、update、delete）需要开通 bitable:app:write。否则会返回 91403 Forbidden。
• 91403 Forbidden 的含义：当前应用对目标资源缺少写入权限或未被授予文档协作权限。
• 修复方法：
  • 在飞书开放平台开发者控制台为你的应用添加并发布 scope：bitable:app:write；
  • 并将该应用加入目标多维表格的“协作者”，授予相应编辑权限；
  • 重启 Node-RED 让 token 刷新后重试。

UX 改进：记住选择并显示友好名称

• 现在，节点在编辑器中会自动记住你上次选择的 Table ID，并在再次打开对话框时自动设置下拉框的当前值。
• 同时，节点会保存所选表的“友好名称”（表名），并在主画布的节点标签中优先显示：
  • 标签展示优先级：节点名称 > 选定表名 > 操作类型（例如：数据表 2 或 记录 list）。
• 这让主流程视图更直观，尤其在同时操作多张表时，更容易识别每个节点对应的目标表。

常见问题

• 操作下拉框不显示: 节点编辑对话框中的原生下拉选择（<select>）在部分浏览器或嵌入式运行环境中可能出现无法展开或不显示选项的情况。为提升兼容性，本包已将“操作”字段改为使用 Node-RED 编辑器内置的 TypedInput 组件，这能提供更稳定一致的体验。如仍遇显示问题，请尝试刷新编辑器页面或清理浏览器缓存。