仅查询策略实战:从金蝶云·星空旗舰版定时拉取收料通知单

这个策略解决什么问题

在供应链集成里,"仅查询"策略看似不起眼,实际是排查与对账的关键抓手。一次实际项目中,某零售企业的仓库反馈:旺店通里的收货数和实际到货数差几十条,业务方要求每天核对金蝶侧的收料通知单,却不希望立刻回写,只想先把数据拿出来比对。这个场景下,典型的"仅查询-金蝶收料通知单"策略就登场了:定时从金蝶云·星空旗舰版把收料通知单拉到中间层,不落库、不回写,纯粹充当"数据探针"。这种策略常用于上线前的数据摸底、上线初期的口径核对,以及排查上下游单据不一致问题。

数据流向与字段映射

数据流向为单向拉取:金蝶云·星空旗舰版 → 中间层(轻易云数据集成平台) → 目标空操作。源端 API 是金蝶的 /kapi/v2/dtog/im/im_purreceivebill/getList_01,类型 RESTful,POST 方法,效果为 QUERY。目标端配置为"写入空操作"(WebAPI,EXECUTE),目的是让策略在平台上完整跑通链路但不对外系统产生副作用。

关键字段对照表(脱敏整理):

编码映射集中管理是轻易云客户的常见做法:把金蝶与旺店通之间所有编码映射放进一个独立映射表,本策略虽然只做查询,后续真正回写时复用同一张映射表,避免在策略里散落硬编码。

在轻易云上如何配置

在轻易云数据集成平台中,新建策略时把"源系统"指向金蝶云·星空旗舰版,"目标系统"指向轻易云集成平台(空操作)。源端 API 选 /kapi/v2/dtog/im/im_purreceivebill/getList_01,effect 选 QUERY,method 选 POST。idCheck 设为 true,平台会用 billno 做幂等去重,即使空操作也能确保不重复拉取同一单据。autoFillResponse 保持开启,平台会自动把响应里的 billno、id 填回策略元数据,排查日志时一目了然。

目标端配置保持极简:API 设为"写入空操作",request/response 留空。这样策略在轻易云上是一条完整的链路,后续切换为真实目标时只需替换目标端元数据,源端和中间层完全不用动。

调度方面,源端 crontab 写 0-59/5 7-22 * * *,也就是每天 7 点到 22 点,每 5 分钟跑一次。目标端 crontab 写 1 1 1 1 1,看似永不到点,实际是平台对空操作的占位写法,意思是"不主动触发"。

实施步骤

第一步,确定增量起点。收料通知单一般按单据编号(FBillNo)或单据创建时间增量拉取。项目里我们以 billno 作为水位线,第一次全量拉取后,后续按最大 billno 增量推进。

第二步,触发全量验证。把分页大小(pageSize)调到 10,在轻易云上手动跑一次,确认响应结构与预期一致;全量跑完后再切回增量模式。

第三步,调度频率上线。白天 7-22 点每 5 分钟一轮,夜里不跑——夜间业务不收货,跑也是空转,只会浪费资源。轻易云上可以把源端调度时间窗口和业务时段绑定,客户现场常见做法是工作日全跑、周末只跑一次全量。

第四步,日志与告警。轻易云会自动记录每次拉取的总条数、耗时、异常单据号,客户通常会把"连续 3 轮条数为 0"和"响应耗时 > 10 秒"作为告警阈值。

第五步,后续衔接。等数据稳定后,可把目标端从"空操作"替换为真实回写策略,源端零改动就能复用。增量与全量双轨的应对模式在这里特别合适:平时跑增量,每天凌晨追加一次全量兜底。

踩坑复盘

第一,空操作别写错元数据。有的工程师把目标端 API 留成"请选择",平台不会报错,但日志里看不到任何回执,排查时一头雾水。稳妥的做法是显式选择"写入空操作"。

第二,pageSize 别贪大。金蝶接口在大数据量下 pageSize 设到 100 以上,响应会明显变慢。客户现场实测:pageSize=10,单轮平均 1.2 秒;pageSize=50,单轮平均 3.8 秒。

第三,billno 一定要做幂等。idCheck=true 不能省,否则重跑策略会把同一张单据拉多次,数据探针的"探"就变成了"重复探测"。

第四,别忽略权限和租户差异。金蝶侧接口对租户隔离非常敏感,轻易云上的平台实例、租户编码必须与金蝶侧授权范围一致,否则接口会直接返回空数据。

第五,夜间调度窗口要谨慎。如果金蝶侧有夜间批处理(月末结账、库存结账),避开那个窗口,否则拉到一半接口突然变慢甚至 500,策略会整体失败。

适用场景与不适用场景

适用:上线前数据摸底、上线初期口径核对、上下游单据对账、数据延迟排查、接口性能基线测试。不适用:需要实时落库的库存同步、需要双向回写的业务单据同步、对账完成后仍依赖此策略做日常业务支撑的场景——这些应当升级为完整的数据同步策略。