查询简道云物料表单数据接口字段手册权威教程

这个接口解决什么问题

在销售订单集成场景里,物料主数据是「编码—名称—规格—单位」四位一体的基础资料,几乎所有下游单据(订单、出库、发票)都要拿它做联动。简道云常作为前端业务录入入口,金蝶云星空则承担正式 ERP 台账。该接口负责按 entry 把简道云物料表单的数据批量拉出,作为下游金蝶物料同步、销售订单映射的查询底座。

接口能力总览

• 认证方式:简道云 API Key(Authorization 头),在轻易云凭证管理里配置后由平台自动注入。
• 请求结构:GET /api/v2/app/{app_id}/entry/{entry_id}/data,核心参数为 fields(逗号分隔字段)、limit(1~100,默认 10)、filter(可选过滤)。
• 响应结构:JSON 对象包含 data 数组(每条记录即一行物料)、data.total(满足条件的总数),便于做全量核对。
• 分页/增量:原 API 不直接提供游标,实际方案中我们以 limit 翻页拉满,再用 filter 做增量条件(如最近更新时间);在轻易云里通常以「分页拉取+主键去重」封装成可观测的查询策略。
• 策略类型:Target 配置为「写入空操作」,即 QUERY_ONLY,不会回写目标系统。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,该接口通常以「简道云表单查询适配器」的方式被封装:

• 适配器:选择「简道云-表单数据查询」,填入 appId、entryId,选择数据对象为「物料」。
• 字段映射器:平台会读取 metadata,把 _id 标记为 id、_widget_1669962898406 标记为 number,字段映射器会自动展开所有 _widget_* 字段,直接拖拽到目标字段即可。
• 策略配置:Target 选择「写入空操作」表示纯查询;idCheck 启用主键校验;定时任务(如 */17 2-23 * * *)控制拉取频率,避免压垮源端。
• 依赖编排:通常作为「金蝶物料同步简道云」「修改简道云物料数据」的前置查询节点,轻易云的策略编排图可显式声明 depends_on。

跨方案实战要点

1. _id 必须当作主键而不是「_id 字段值」:简道云主键是系统生成的字符串,不要和业务编码混用,否则更新时找不到记录。
2. 物料编号要与金蝶 FNumber 严格一致:两端都建议做左去空格、大小写规范,这是跨系统做对照的根基。
3. 规格型号字段要按业务选一个:同一个中文标签可能对应单行+多行两个 widget,真实场景里我们通常二选一,否则金蝶侧 FSpecification 会出现冲突。
4. 分页+过滤并用:大表单一定要用 filter 收窄范围,否则反复拉全量既慢又贵。
5. idCheck 与定时任务一起开:定时跑的数据若不勾主键校验,后续同步策略可能出现「同一编码产生多条」的事故。
6. 作为纯查询节点要显式声明:Target 选「写入空操作」,避免误把查询结果当成写入动作触发下游更新。

踩坑复盘

• 坑 1:把 _id 当物料编码。简道云 _id 是系统主键,不能直接和金蝶 FNumber 对照,稳的做法是用 _widget_1669962898406 做业务编码映射。
• 坑 2:规格型号两个字段都映射。两个 widget 中文名相同,容易同时映射到金蝶 FSpecification,造成「同一字段值不一致」告警。
• 坑 3:忘记 limit 默认值是 10。一次性业务同步容易因为默认分页太小而漏数据;稳妥的做法是显式传 limit=100 并做翻页。
• 坑 4:filter 表达式写错字段名。简道云 filter 只认 widget ID 不是中文名,字段名一旦填错就返回空集合,排查时要先 dump 一条样本核对。
• 坑 5:把查询策略误配成同步策略。缺少「写入空操作」配置时,查询结果可能被当成增量回写,造成简道云侧脏数据。

何时选用

该接口适用于「需要把简道云物料作为基础资料提供给下游(金蝶、ERP、MES)」的纯查询场景,典型如销售订单、出库单中的物料联动选择。若业务需要把物料从其他系统写入简道云,则应改用「写入/更新物料」类策略而非本查询接口。