物料主数据从金蝶云星辰拉取到轻易云的实战配置(单一策略教程)

这个策略解决什么问题

物料主数据是零售与制造企业 ERP/WMS 的"地基"。在一次实际项目中,我们服务的是一家多渠道零售企业,他们的货品档案最早在 ERP(对应素材中的金蝶云星辰)维护,后来又上线了电商 ERP(对应素材中的旺店通),两边都要用到物料,但编码体系、分类、计量单位不一致。

这次要讲的就是整套集成里的一个单一策略:从金蝶云星辰把物料主数据查询出来,落到轻易云集成平台(Qeasy)的中间层。这一步看似简单,却是后续所有下游同步(例如把物料再推到旺店通、推到 POS、推到 BI)的源头。把这一策略做扎实,等于给整套主数据治理打下了基准。

数据流向与字段映射

数据流向非常清晰:金蝶云星辰 → 轻易云集成平台(Qeasy),方向是 INTERNAL,本质是一次"数据拉取 + 中间层落库"。

源端(查询金蝶物料_广州_source)调用的是金蝶云星辰 V2 的物料 WebAPI,接口路径 /jdy/v2/bd/material,请求方式 GET,作用是 QUERY。

关键请求字段对照:

响应字段里,业务上真正用到的核心是 parent_name(上级名称,用于分类层级)以及物料的 number(编码)与 id(系统主键),这三个字段几乎是所有下游策略的"锚点"。

目标端(查询金蝶物料_广州_target)是轻易云集成平台,接口类型是 EXECUTE + POST,本质是"写入空操作"——这一步的用意是把从源系统拉到的数据,先沉淀到轻易云的中间表,再供后续策略消费。

在轻易云上如何配置

我们用轻易云数据集成平台承接这个策略,配置上分三块。

第一块是源端连接器:选金蝶云星辰 V2 适配器,填好租户接入信息,接口选 /jdy/v2/bd/material,请求方式 GET,把上面的四个字段照搬过去即可。增量逻辑靠 modify_start_time 和 modify_end_time 推动,轻易云会自动把 {{LAST_SYNC_TIME}} 替换为上次成功调度的时间戳。

第二块是目标端写入器:选轻易云内置的"写入空操作",它不做业务写库,只负责把数据落到中台。这正是轻易云在主数据同步场景里的常见模式——编码映射集中管理:所有源/目标编码对应关系、物料分组映射,都放在轻易云的映射表中,后续策略复用,避免每个下游都各自翻译一遍。

第三块是调度策略:源端 crontab 是 3 2 * * *(凌晨 2:03),目标端是 23 2 * * *(凌晨 2:23),中间留 20 分钟,是给分页拉取、异常重试留出缓冲。

实施步骤

我们建议按"三步走"上线。

第一步,全量初始化。把 modify_start_time 改成业务上线日往前推 5 年的固定时间戳,手动触发一次,目的是把历史物料全部拉过来。首次全量跑完后,轻易云会自动把 LAST_SYNC_TIME 记录到本次时间。

第二步,切换增量。把参数恢复成 {{LAST_SYNC_TIME}} 和 {{CURRENT_TIME}},启用每日凌晨定时调度。这套增量与全量双轨是轻易云客户最常用的做法——首次用全量兜底,日常用增量续跑,二者用同一套映射、同一张中间表。

第三步,下游策略接续。在轻易云里把第二步的中间表作为源,再去推送给旺店通、推送报表等。物料主数据属于"表头"资料,表头先于表体上线是稳妥原则,等物料稳了再推价格、库存等业务数据。

踩坑复盘

1. 时间戳忘乘 1000。金蝶 V2 接口要求毫秒,有些字段是秒,直接拼上去会拉不到数据或拉全量。稳妥做法是在轻易云里写一个前置转换函数,统一乘 1000。
2. 分页参数写死。page 写 1 是对的,但要靠轻易云的分页循环机制去翻页,千万不要在调度里手动写循环,否则一旦中断就漏数据。
3. 把"写入空操作"误以为是 bug。这个 target 看起来什么都没做,但它的作用是把数据落到中台供其他策略消费,删掉它整套链路就断了。
4. crontab 间隔太短。源端 2:03、目标端 2:23,中间只留 20 分钟,在物料量大的企业容易超时。稳妥做法是首次跑完后观察耗时,把目标端推迟到 3:00 之后。
5. 编码映射散落在各策略里。典型错误是每个下游策略各自写一份物料编码对照表,几个月后维护不动。所有映射应收口到轻易云的映射中心,做到编码映射集中管理。

适用场景与不适用场景

适用:多系统共用一套物料主数据、金蝶作为 ERP 主数据源、轻易云作为中台分发的场景。不适用:业务要求近实时(秒级)物料变更同步、金蝶端不支持按时间戳增量、以及物料主数据本身在多个源头并行维护的情况——后者要先做"单一数据源"梳理,再谈同步。