小满OKKICRM产品主数据查询策略实战教程:从增量拉取到金蝶云星空落库
这个策略解决什么问题
在做CRM与ERP打通的项目里,产品主数据往往是第一道坎。某零售企业的销售在OKKICRM里维护产品档案,后端供应链、库存、财务却在金蝶云星空;两边一旦编码口径不一致,后续订单、库存对账全是糊涂账。我们用轻易云数据集成平台(Qeasy)承接这件事,核心思路是:以OKKICRM为权威源,定时拉取增量产品数据,落到金蝶云星空。素材里的「查询小满产品」策略就是这条链路的起点——它只负责把数据从源系统按时间窗拉出来,不做写入,看似简单,实际是整条同步链的「心脏」,后续的客户、订单同步都依赖它产出的最新产品视图。
数据流向与字段映射
整体流向是 小满OKKICRM → 轻易云中间层 → 金蝶云星空。本策略的源端是OKKICRM的/v1/product/list接口(GET,QUERY类型),目标端在素材里被注册为「轻易云集成平台」的一个空写入节点(WebAPI,POST,effect=EXECUTE,idCheck=true),这是轻易云里常见的做法:先用一个「写入空操作」占位,把数据落到中间层的数据集,供下游策略按ID消费,避免源端被频繁轮询。
关键请求参数对照如下:
| 字段 | 含义 | 取值策略 |
|---|---|---|
| start_index | 分页起始页 | 默认 1 |
| count | 每页条数 | 默认 20 |
| start_time | 增量起点 | `{{LAST_SYNC_TIME |
| end_time | 增量截止 | `{{CURRENT_TIME |
| removed | 是否查已删除 | 0 |
| product_type | 产品类型 | 视业务传参 |
响应侧,源系统以product_no作为唯一ID,以name作为编号字段返回。目标侧「写入空操作」节点不映射任何字段,但idCheck=true意味着轻易云会用源端product_no做幂等去重——这是后面对账的命脉。
在轻易云上如何配置
第一步,在轻易云集成平台里把两个系统接入:OKKICRM走自定义API连接器,填入/v1/product/list,鉴权按租户提供的AppId/Secret方式配置;金蝶云星空走官方连接器,登录公有云租户。
第二步,新建策略,选择「查询小满产品」模板。源端按上面表格填好,特别注意两点:其一,start_time必须用轻易云内置的LAST_SYNC_TIME变量,不要写死日期;其二,分页参数start_index和count建议放进策略的可视化分页配置里,轻易云会自动按响应里的total或has_more循环拉取,直到收齐一页不剩。
第三步,目标端选「轻易云集成平台」+ WebAPI,api名称填「写入空操作」,method=POST。idCheck勾上,buildModel留空。轻易云会自动生成一张数据集表,以product_no为主键。
第四步,加一个简单的字段映射脚本,只做三件事:把源端返回的product_no、name等字段塞进数据集;做一次轻度的清洗(去空格、统一大小写);把updated_at单独存一列,方便下游策略做时间窗过滤。这是轻易云客户常见的「编码映射集中管理」模式——所有口径转换都集中在一个策略的脚本里,避免散落在多个策略里各写各的,后期口径变更只改一处。
实施步骤
- 全量初始化:策略上线前,先把
start_time手动设到一个很早的日期(如三年前),end_time取当前时刻,触发一次全量拉取,目的是把历史产品档案一次性灌进数据集。全量跑完后再把start_time改回LAST_SYNC_TIME变量,进入增量模式。 - 增量起点确立:第一次进入增量时,建议先观察两到三天,确认
LAST_SYNC_TIME的推进节奏与源系统更新时间一致,避免漏单。 - 调度频率:素材里的
crontab是34 3 * * *(凌晨3:34),这是轻易云推荐的「错峰窗口」,避开业务高峰期。生产中我们一般跑在凌晨2点到4点之间,分钟位故意打散,防止多策略同时跑把数据库打满。 - 下游接力:本策略跑完后,真正落到金蝶云星空的是后续的「产品同步」策略,它按
updated_at时间窗消费本策略产出的数据集,完成真正的写入。两步解耦是轻易云里典型的「表头表体分阶段」思路:查询策略只管拉,写入策略只管落,彼此互不阻塞。
踩坑复盘
- 时间窗漏单:早期项目里,有人把
start_time写成「上次跑成功的end_time」,结果遇上跨时区或源系统时区漂移,凌晨那批更新被吃掉。稳妥的做法是,start_time用轻易云变量,end_time用CURRENT_TIME,并额外比对源系统当日数据量,异常时立刻补跑。 - 分页遗漏:OKKICRM返回结构里如果
total字段缺失,默认分页插件会以为只有一页,导致只拉20条。典型错误是直接把分页关掉,正确做法是手动指定分页判停字段(如has_more或total > start_index + count)。 - idCheck被关掉:有人觉得「写入空操作」反正不写业务表,把
idCheck关了。后果是同一条product_no被插多次,数据集膨胀,下游消费变慢。idCheck=true是平台给的免费幂等,千万别关。 - 编码映射散落:不同策略里各自写了一份产品编码转换脚本,某天口径变了,只改了一处,导致两边数字对不上,排查花了两周。这就是「编码映射集中管理」的价值——所有口径集中在查询策略的脚本里维护。
- 全量与增量混淆:没做全量初始化就直接跑增量,结果历史产品档案压根没进数据集,下游金蝶云星空里一片空白,业务方以为是同步挂了。
适用场景与不适用场景
适用:CRM作为产品主数据权威源、ERP作为消费方;产品数量在十万级以内、按时间增量更新为主;需要给下游多个策略(订单、库存、客户)提供统一产品视图。不适用:产品数据需要在两边双向同步并各自可改;产品量在百万级以上且源系统不支持时间窗增量(只能全量);业务要求实时(秒级)而非准实时(天级)的场景。