文档说明

在此前的文章中，我们介绍了知行之桥具备集成飞书多维表的能力：知行之桥集成飞书多维表：让 EDI 订单从报文走向可视化协同，本文提供一套可重复实践的完整路径：在飞书开放平台创建并发布企业自建应用，完成多维表授权；在知行之桥中部署驱动、配置 Bitable 端口及连接，并通过工作流实现数据查询与写入。后半部分以 X12 850 采购订单为例，演示如何将包含多条 PO1 的订单扁平化为飞书记录并完成验证。

1 学习目标与整体架构

完成本文实践后，你将能够：

• 在知行之桥中完成 Bitable 驱动部署与连接配置。

• 配置飞书开放平台 API 权限及目标多维表编辑权限。

• 正确区分 App ID、App Secret、AppToken 和 Table ID。

• 通过 SQL 查询和写入 Records，并按字段类型完成数据清洗。

• 结合日志、数据结构和字段类型排查认证、权限及 invalid request 等问题。

• 完成 X12 850 到飞书多维表的扁平化同步与结果验证。

2 环境准备与安全要求

3 安装 Bitable 驱动

3.1 为什么需要安装

本文操作基于知行之桥™ 2026（26.3.9746.0 及以上的 .NET 版本）。由于验证环境默认未安装相关驱动，需要将驱动文件和 Profile 手动部署到知行之桥 AppDirectory，并重启服务完成注册。不同服务器的安装路径可能不同，请以当前环境的实际路径和截图中的相对位置为准，避免直接照搬绝对路径。

注：相关驱动文件请联系我们获取。

3.2 安装步骤

步骤 1 备份现有配置

记录知行之桥版本及驱动、Profile 目录，并备份现有相关文件，以便出现问题时回滚。

步骤 2 停止服务

停止知行之桥服务，避免驱动部署过程中仍有工作流调用。本文采用重启方式加载驱动。

步骤 3 部署驱动

将驱动包System.Data.CData.API.dll按其目录结构复制到知行之桥安装根目录下的 www/bin 目录。

知行之桥安装根目录及驱动目录

步骤 4 部署 Profile

将 Bitable.apip 文件放入知行之桥 AppDirectory 下的 cdata-drivers/profiles 目录。如该目录不存在，请先手动创建。

Bitable Profile 文件所在目录和文件名

步骤 5 修改 Web.config 文件

进入知行之桥安装根目录下的 www 文件夹，使用文本编辑器打开 Web.config 文件。在 <DbProviderFactories> 节点内部、结束标签 </DbProviderFactories> 之前插入以下内容：

<remove invariant="System.Data.CData.API" />
<add name="CData ADO.NET Provider for API" invariant="System.Data.CData.API" description="CData ADO.NET Provider for API" type="System.Data.CData.API.APIProviderFactory, System.Data.CData.API" />

Web.config 文件的编辑位置

步骤 6 重启并检查注册结果

重启知行之桥服务后，打开端口列表，确认是否显示 API Profile For Bitable 端口。若未显示，请检查启动日志中的驱动加载、依赖缺失或 Profile 解析错误。

知行之桥重启后在端口列表中可看到 API Profile For Bitable 端口

4 飞书上创建多维表

4.1 使用飞书 AI 创建初始表结构

在飞书中新建一个空白多维表，并将以下提示词复制给飞书 AI。建表完成后，请按照 4.2 节核对字段名称、字段类型、单选项及公式等。

请在当前飞书多维表中创建一张用于接收 X12 004010 版本 EDI 850 采购订单的扁平数据表，并严格按照以下要求配置。

一、总体要求

1. 数据表名称：EDI_850_Orders_Flat。
2. 只创建一张数据表，不创建关联表或关联字段。
3. 数据粒度：一个 PO1 行项目对应一条记录。同一份 850 中的订单头信息重复保存到每条 PO1 明细记录。
4. 字段名称必须与下方清单逐字一致，不要擅自增加空格、修改大小写或改写名称。
5. “订单明细标识”必须设置为主字段。
6. UPC、GTIN、邮编、控制号和行号必须使用文本字段，避免丢失前导零。
7. “行金额”使用公式计算，不创建为普通数字字段，公式为：订购数量 * 单价。
8. 日期时间字段必须启用具体时间。

二、唯一标识字段

1. 订单明细标识：单行文本，主字段，必建。测试值为 PO850TEST001-10，由采购订单号和行号组合。
2. 同步键：单行文本，必建。由交易伙伴代码、采购订单号和行号组合，用于防止重复写入。

三、订单头字段

1. 交易伙伴代码：单行文本，必建，来源为知行之桥配置或 ISA/GS 标识。
2. 采购订单号：单行文本，必建，来源为 BEG03。
3. 订单日期：日期，必建，来源为 BEG05。
4. 订单用途代码：单选，必建，来源为 BEG01。
5. 订单类型：单选，必建，来源为 BEG02。
6. 币种：单选，必建，来源为 CUR02。
7. 买方名称：单行文本，必建，来源为 N1*BY。
8. 买方代码：单行文本，必建，来源为 N1*BY 标识。
9. 收货方名称：单行文本，必建，来源为 N1*ST。
10. 收货方代码：单行文本，必建，来源为 N1*ST 标识。
11. 收货地址1：单行文本，必建，来源为 N3。
12. 收货地址2：单行文本，非必建，来源为 N3 第二地址，可为空。
13. 收货城市：单行文本，必建，来源为 N4。
14. 收货州省：单行文本，非必建，来源为 N4，可为空。
15. 收货邮编：单行文本，非必建，来源为 N4，必须保留前导零。
16. 收货国家：单选，必建，来源为 N4。
17. 要求交货日期：日期，必建，来源为 DTM 限定符对应日期；当前测试使用 DTM*002，正式使用时以交易伙伴规范为准。
18. 部门代码：单行文本，非必建，来源为 REF*DP 或交易伙伴指定字段。
19. 订单状态：单选，必建，由知行之桥赋值。

四、订单明细字段

1. 行号：单行文本，必建，来源为 PO101，使用文本以兼容非纯数字行号并保留前导零。
2. 订购数量：数字，必建，来源为 PO102。
3. 单位：单选，必建，来源为 PO103。
4. 单价：数字，必建，来源为 PO104，保留 2 至 4 位小数，不要使用固定人民币货币类型。
5. 价格基准：单行文本，非必建，来源为 PO105，报文不存在时留空。
6. 买方SKU：单行文本，必建，来源为 PO1 产品限定符及编号，当前测试使用 SK。
7. 供应商SKU：单行文本，必建，来源为 PO1 产品限定符及编号，当前测试使用 VN。
8. UPC：单行文本，非必建，来源为 PO1 产品限定符及编号，必须保留前导零。
9. GTIN：单行文本，非必建，来源为 PO1 产品限定符及编号，必须保留前导零。
10. 商品描述：多行文本，必建，来源为 PID。
11. 行金额：公式，必建，公式为“订购数量 * 单价”，不由知行之桥写入。
12. 行状态：单选，必建，由知行之桥赋值。

五、EDI 追踪字段

1. 850 ISA控制号：单行文本，必建，来源为 ISA13。
2. 850 GS控制号：单行文本，必建，来源为 GS06。
3. 850 ST控制号：单行文本，必建，来源为 ST02。
4. 知行之桥 MessageId：单行文本，必建，来源为知行之桥消息元数据。
5. 原始文件名：单行文本，必建，来源为知行之桥消息元数据。
6. 接收时间：日期时间，必建，来源为知行之桥消息时间，必须启用具体时间。
7. 最后同步时间：日期时间，必建，来源为知行之桥处理时间，必须启用具体时间。
8. 同步状态：单选，必建，由知行之桥赋值。
9. 同步错误：多行文本，非必建，成功时留空，失败时记录脱敏后的错误摘要。

六、单选字段及选项

1. 订单用途代码：00。
2. 订单类型：SA。
3. 币种：USD、CAD、CNY。
4. 收货国家：CN、US、CA。
5. 单位：EA、CA。
6. 订单状态：新订单、已确认、已变更、已取消、部分发货、已完成、异常。
7. 行状态：新建、已确认、已变更、已取消、部分发货、已完成、异常。
8. 同步状态：待处理、成功、失败。

七、创建视图

1. 全部订单明细：显示全部记录和字段。
2. 按采购订单号分组：按采购订单号分组，组内显示所有行项目，并对订购数量和行金额显示汇总。
3. 新订单：筛选“订单状态 = 新订单”。
4. 待交货订单：按要求交货日期排序。
5. 异常记录：筛选“订单状态 = 异常”或“同步状态 = 失败”。
6. 按SKU查看：按买方SKU或供应商SKU分组。

八、完成后反馈

完成创建后，请返回以下检查结果：

1. 实际创建的数据表名称。
2. 实际创建的字段总数（预期为 42 个），以及每个字段的名称和类型。
3. “订单明细标识”是否为主字段。
4. “行金额”的实际公式。
5. 已创建的单选项和视图。
6. 无法自动创建或需要人工确认的项目。

4.2 人工核对 AI 建表结果

重点检查以下项目：

• 数据表名称是否为 EDI_850_Orders_Flat。
• “订单明细标识”是否为主字段，字段名称是否逐字一致。
• 数量和单价是否为数字，日期和日期时间类型是否正确。
• UPC、GTIN、邮编、控制号和行号是否为文本类型。
• 单选项是否完整，“行金额”是否为公式字段且计算正确。
• AI 未完成或提示需要确认的字段和视图是否已经人工补齐。

5 创建飞书应用并完成双重授权

5.1 创建企业自建应用

步骤 1 进入飞书开放平台

登录飞书开放平台开发者后台，创建企业自建应用。应用名称建议能体现系统和用途，例如 Bitable Workflow。

飞书开发者后台新建企业自建应用页面

步骤 2 添加多维表 API 权限

在权限管理中搜索多维表相关权限，开通记录读取、记录写入及必要的表结构读取权限。测试环境可临时开通全部 Bitable 权限，生产环境应遵循最小权限原则。

权限管理中开通的多维表权限列表

步骤 3 创建并发布版本

新建应用版本，填写版本说明并发布。新增权限需在版本发布后才能生效。

应用版本发布页面

步骤 4 获取凭证

进入“凭证与基础信息”页面，获取并妥善保存 App ID 和 App Secret。

凭证页面

5.2 将应用添加到目标多维表

开放平台权限决定应用可以调用哪些 API，文档权限决定应用可以访问哪些多维表，两者缺一不可。

步骤 1 打开目标多维表

使用具有管理权限的账号打开需要授权的飞书多维表。

步骤 2 添加文档应用

从多维表右上角更多菜单或应用管理入口选择添加文档应用，搜索刚刚发布的企业自建应用。不同飞书版本的菜单名称可能略有差异。

目标多维表中添加文档应用的入口

步骤 3 授予可编辑权限

将应用权限设置为“可编辑”。如果仅授予查看权限，只能查询数据，无法执行 INSERT 或 UPDATE 操作。

文档应用权限设置为可编辑

常见问题： 应用已创建且 API 权限已发布，但未添加到目标多维表，或文档权限仍为“仅查看”，都会导致数据写入失败。遇到写入失败时，请优先检查这两项配置。

6 获取 AppToken 和 Table ID

6.1 四个标识不要混用

6.2 从 URL 识别 AppToken 和 Table ID

在浏览器中打开目标多维表，通过地址栏中的 URL 识别 AppToken 和 Table ID。 

示意 URL：
https://example.feishu.cn/base/<AppToken>?table=<TableId>&view=<ViewId>

填写：
AppToken = <AppToken>
Table ID = <TableId>    # 通常以 tbl 开头
View ID  = <ViewId>     # 查询或展示可能使用，但不等于 Table ID

浏览器地址栏中 AppToken 与 table 参数的位置

7 在知行之桥中创建连接并测试

7.1 新建连接

步骤 1 打开端口列表

新建 API Profile For Bitable 端口，并配置连接。

步骤 2 填写参数

OAuth Client Id 和 OAuth Client Secret 为端口必填项，但当前 Profile 不使用这两个参数进行飞书认证，可填写非敏感的占位值。请在 Profile Settings 中填写以下连接信息：

AppId=cli_xxxxxx;AppSecret=xxxxxxxxxx;AppToken=xxxxxxxx;TableId=xxxxxx

知行之桥 Bitable 连接参数页面

步骤 3 保存并测试

执行连接测试。

7.2 最小连通性测试

• 成功返回预览记录：认证、Base 和 Table 定位基本正确。

• 401 或鉴权失败：检查 App ID、App Secret、版本发布和凭证状态。

• 403 或 forbidden：检查 API 权限、文档应用授权和可编辑权限。

• 资源不存在：检查 AppToken、Table ID、URL 提取是否混淆。

• 连接类型不存在：回到驱动部署和 Profile 注册环节排查。

8 Select 查询实践

8.1 创建查询节点

步骤 1 新建隔离的查询端口

建议先创建独立的 SELECT 端口进行测试，确认查询正常后再接入正式工作流。创建端口时，选择已配置的 Bitable 连接并设置查询操作。 

步骤 2 执行小结果集查询

选择 Records，在 selectQuery 中编写查询语句，并使用 LIMIT 限制返回数量。确认字段结构后，再逐步添加筛选条件。

SELECT * FROM Records LIMIT 1

知行之桥 查询端口 SQL 和连接选择

步骤 3 查看输出结构

在事务页面点击“接收文件”，检查返回记录中的 RecordId 和 Fields。其中，RecordId 是后续执行 UPDATE 操作的必要标识。

Select 返回结果

9 Insert 写入实践

9.1 将示例工作流导入知行之桥

下载示例工作流 FEISHU_TEST.arcflow 并导入知行之桥工作区，然后在 Bitable_850_Flat_Upsert 端口的设置中选择已测试成功的 Bitable 连接。

9.2 工作流展示和端口职责

Feishu_850_X12_To_XML
        ↓
Feishu_850_Flat_Transform
        ↓
Bitable_850_Flat_Upsert

知行之桥工作区完整流程画布

9.3 实际操作步骤

步骤 1 准备测试 850

下载 X12 850 测试文件。

步骤 2 发送测试

将 X12 850 测试文件发送至 Feishu_850_X12_To_XML 端口。

步骤 3 核验三段交易

分别确认 X12、Script、Bitable 三个端口执行成功。

步骤 5 在飞书中查询结果

进入飞书多维表，确认写入的记录数量、关键字段及行金额等是否正确。

飞书表中对应的订单明细

步骤 6 使用 AI 生成订单展示页面

点击多维表右上角的“生成页面”，即可使用 AI 定制订单展示页面，如下图所示。

飞书表优化显示

10 结语：用知行之桥连接 EDI 与业务协作

完成上述配置后，知行之桥可以接收并解析 EDI 报文，将转换后的业务数据写入飞书多维表。业务人员可以直接在飞书中查看订单、跟踪处理状态和筛选异常记录。

本文以 X12 850 采购订单为例，介绍了从报文接收、PO1 明细拆分到飞书数据写入和结果验证的完整流程。相同的方式也可用于展示订单确认、发货通知和发票等其他 EDI 业务数据。

希望将更多 EDI 数据连接到飞书、ERP、WMS 或其他业务系统？ 了解知行之桥 · 申请免费试用 · 联系技术顾问

11 参考资料与相关阅读

• • 飞书多维表格概述
  • 飞书多维表新增记录
  • 飞书多维表查询记录
  • 飞书开放平台权限概述
  • 知行之桥 EDI 本地部署解决方案
  • 知行之桥产品文档
  • 联系知行软件