物料主数据从源系统同步到金蝶云星空:金蝶物料查询策略实战教程
这个策略解决什么问题
某零售企业的物料从源系统(ERP/WMS)推送到金蝶云星空后,常出现一个尴尬问题:接口返回成功,但下游业务(采购、销售、库存模块)在几分钟后看到的物料状态还是"未审核"或"暂存"。根因往往是金蝶云星空保存物料时采用异步提交,以及部分字段依赖组织级配置回写。直接复用推送接口的响应去做下游分发,数据"看似落库,实则未生效"。
我们用轻易云数据集成平台(Qeasy)承接的做法是:物料写入接口完成后,另起一条策略——按调度定时回查金蝶云星空的物料数据(FNumber/FMasterId 双键校验),用"查询-再分发"链路把已确认落库的版本送往下游。下面把这一个策略讲透。
数据流向与字段映射
整体链路是 源系统 → 轻易云中间层 → 金蝶云星空(回查源) → 轻易云中间层 → 下游消费系统。其中金蝶云星空在本策略里既是被回查对象,也是事实数据的权威源。
| 维度 | 源(物料回查请求) | 中间层(轻易云) | 目标(金蝶云星空 executeBillQuery) |
|---|---|---|---|
| 接口 | 内部触发器 | 调度任务 | executeBillQuery(POST) |
| 主键字段 | FMasterId / FNumber | 透传 | FNumber(编码)、FMasterId(内码) |
| 组织字段 | FCreateOrgId.FNumber | 透传 | 创建组织、使用组织(均必填) |
| 业务开关 | FIsBatchManage / FIsKFPeriod | 透传 | 启用批号管理、启用保质期 |
| 响应方向 | — | 整行回写 | FMasterId(去重键) |
源端的请求字段全部走 value 直引字段名(FMasterId、FNumber、FCreateOrgId.FNumber),金蝶云星空的元数据模型会根据这些值自动展开为带组织内码的查询条件。idCheck=true 这一参数用于在中间层用 FMasterId 做幂等去重,避免同一物料被下游重复消费。
在轻易云上如何配置
在轻易云数据集成平台里,这个策略被建模为"源 → 目标"两条配置:
源端(读取金蝶云星空)
- 数据源平台:金蝶云星空(Kingdee.Cloud)
- 元数据 API:
executeBillQuery,类型 QUERY,效果 QUERY - HTTP 方法:POST
- 主键:
FNumber,内码:FMasterId buildModel=true:轻易云会根据请求字段自动构建请求模型- 请求字段按
field / label / type / is_required四个属性描述,value直接引用金蝶字段名(如FCreateOrgId.FNumber)
目标端(下游分发占位)
- 数据源平台:轻易云集成平台(datahub)
- 元数据 API:"写入空操作"(WebAPI/EXECUTE/POST)
idCheck=true,主键与内码均为 0- 该端不真正写第三方,只作为调度落点和下游订阅入口
crontab 方面,源端定义为 08 01,03 * * *(凌晨 1:03 与 3:08 两次),目标端定义为 23 2 * * *(凌晨 2:23)。两端调度错峰,既避免同时抢占金蝶云星空连接池,也给下游留出消费窗口。
实施步骤
我们把这个策略上线到生产,通常走四个阶段:
- 建模与连通性验证:在轻易云里把源端、目标端两条 metadata 各注册一遍,先用单条 FNumber 跑通 executeBillQuery,确认能拿到 FMasterId 回包。
- 增量起点确认:以物料最后修改时间作为分界点,先一次性把存量物料按 FNumber 列表分页回查一遍,作为下游冷启动基线。
- 双轨调度上线:日常工作流采用增量(按修改时间窗口),每周末或每月固定时间触发一次全量回查,核对两边数量与状态——这是轻易云客户常见的"增量与全量双轨"做法。
- 调度频率调优:观察金蝶云星空返回耗时与连接池使用率,把 1:03 / 3:08 这两个时点错开,避免与上游写入策略在同一时刻打满连接。
编码映射集中在轻易云的「映射表」里维护,新增组织、新增物料类型时只改一处,不会散落在多个策略里——这是很多客户上线半年后仍然能稳定运行的关键。
踩坑复盘
- 直接复用写入响应:典型错误是把保存接口返回的 FMasterId 立刻分发出去。金蝶云星空对部分字段(组织、批号、保质期)是后置刷新的,稳的做法是先落库、再定时回查、再分发。
- 组织字段为空被拒:executeBillQuery 的
FCreateOrgId_FNumber、FUseOrgId_FNumber是必填项,漏填会整批报错。建议在轻易云的请求组装阶段就把这两个值作为常量注入,不要依赖上游传。 - idCheck 误关:如果不打开
idCheck,同一物料在窗口期内多次回查会被下游当成多条新数据处理,导致下游重复触发单据。我们的做法是 FMasterId 作为幂等键,中间层做去重。 - 调度与写入撞车:本策略 crontab 设的是凌晨,但上游写入策略如果也在凌晨,金蝶云星空的连接池很容易打满。把两端错峰 20-30 分钟,基本就不会再出现超时熔断。
- 批号/保质期开关位回写错位:
FIsBatchManage、FIsKFPeriod这类业务开关回写有延迟,不能仅凭源系统推送结果判定,必须等回查结果确认。
适用场景与不适用场景
适用:物料主数据需要在金蝶云星空权威落库后,再统一分发到下游多个业务系统(采购、销售、电商中台、WMS),且下游对"暂存/未审核"状态敏感的场景。
不适用:下游能容忍直接消费写入接口响应、不要求按物料最新已确认版本同步的场景;以及物料体量极小、无需错峰调度的轻量集成。