【联动查询】金蝶商品查询策略深度教程:基于时间窗的增量拉取与落地设计
这个策略解决什么问题
在某零售企业的供应链集成里,商品主数据是后续所有单据(销售出库、采购入库、调拨)的基础。源系统侧的商品一旦改名、改单位、改条码,如果不及时拉回集成平台,下游单据就会出现"两边数字对不上"的尴尬。
我们用轻易云数据集成平台承接的【联动查询】金蝶商品查询,核心目标就是:按"修改时间"增量拉取金蝶云星辰V2的商品档案,落地到集成平台的中间层,为后续向旺店通的推送提供干净、统一、带状态的主数据。
数据流向与字段映射(源 → 中间层 → 目标)
数据流向很清晰:金蝶云星辰V2(源)→ 轻易云集成平台(中间层) → 后续策略再向旺店通推送。本次策略只覆盖前两段。
源端用的是金蝶云星辰V2的 /jdy/v2/bd/material 接口,GET 方式拉取商品主数据列表,配合 /jdy/v2/bd/material_detail 取明细。下表是本次策略里最关键的几组字段对照:
| 维度 | 源端字段(金蝶云星辰V2) | 中间层处理 | 落地形态(轻易云) |
|---|---|---|---|
| 主键 | number(编码)、id | 以 number 为主键,id 校验 | 主数据条目 |
| 增量起点 | modify_start_time(毫秒时间戳) | {{LAST_SYNC_TIME}}000 | 平台上下文变量 |
| 增量终点 | modify_end_time(毫秒时间戳) | {{CURRENT_TIME}}000 | 平台上下文变量 |
| 分页 | page / page_size | page_size=20,循环翻页 | 请求参数 |
| 联动明细 | detailAPI = /jdy/v2/bd/material_detail | 列表+明细二段式 | otherRequest 扩展 |
值得注意的是,毫秒时间戳末尾的 000 是必须的,因为金蝶字段声明是字符串型但语义是毫秒,直接把秒级戳塞进去会被服务端忽略。
在轻易云上如何配置
在轻易云集成平台里,这个策略被建模为一条"源查询 + 落地空操作"的流水线:
- 源平台节点:选择金蝶云星辰V2,API 选
/jdy/v2/bd/material,Effect=QUERY,Method=GET。 - 增量变量绑定:
modify_start_time绑{{LAST_SYNC_TIME}}000,modify_end_time绑{{CURRENT_TIME}}000。这一步是命脉,绑定错就直接拉空或拉全量,排查起来很费时间。 - 联动明细钩子:在 otherRequest 里把
detailAPI配成/jdy/v2/bd/material_detail,列表返回的每条number/id会自动按需去拉明细。 - 目标平台节点:选轻易云集成平台本身,API 用"写入空操作",Effect=EXECUTE,Method=POST。这里的 number/id 都设为
0,idCheck 仍保持true,作用是把上游数据落到平台中间库。 - 响应自动建模:源端
autoFillResponse=true,省去手工建表的成本,但明细字段仍要在第一次跑通后人工核对一次。
这是轻易云客户最常见的应对模式之一:编码映射集中管理 + 表头表体分阶段——先用这条策略把商品档案的"骨架"拉齐,后续推送策略再按编码去匹配旺店通。
实施步骤(分阶段调度)
我们建议把首次落地拆成三段:
- 第一阶段:全量触发。把
{{LAST_SYNC_TIME}}手动置为业务起点(如某零售企业的系统上线日),把{{CURRENT_TIME}}置为当前,手动跑一次,把历史主数据一次性拉到中间层。这一步务必在业务低峰期做。 - 第二阶段:增量起点固定。全量跑完后,把
{{LAST_SYNC_TIME}}切回到"上一次同步成功时间",从此进入增量。 - 第三阶段:调度频率。源端 crontab 设为
15 3 * * *(凌晨 3 点 15),目标端空操作 crontab 设为23 2 * * *(凌晨 2 点 23),让落库动作在查询动作之前完成(实际是目标节点先于源节点执行下一轮上下文回写),形成稳定的双轨节奏。
如果中间层需要更复杂的清洗(比如单位换算、多语言名称),可以在源节点之后、目标节点之前插入一个轻量映射脚本,但本策略只解决"拉回并落地"这一段。
踩坑复盘
- 毫秒戳忘了乘 1000。这是典型错误,有人直接传秒级时间戳,服务端返回空列表却"没报错",排查半天才发现是单位问题。稳妥的做法是在轻易云的请求参数里就拼好
000后缀,并在自测阶段用 Postman 对拍一次毫秒戳。 page_size默认值被误用。金蝶默认page_size=10,但文档说"默认10",实际跑起来 10 条太碎、循环翻页太频繁。我们固定改成20,性能与稳定性最合适;再大就要考虑服务端限流。detailAPI漏配导致表体为空。金蝶主数据是表头+表体结构,只配列表不配 detail,看起来"跑通了",其实后续推送策略拿到的是空表体。otherRequest里必须把detailAPI显式写上。- 首次跑全量误触发了旺店通端的下游策略。全量拉取通常不带
idCheck校验,但下游策略会跟着联动。我们在客户现场的做法是:全量阶段临时把下游策略停掉,确认中间层数据干净后再放开。 LAST_SYNC_TIME在跨天边界跳变。如果调度在凌晨触发,而源端有跨天写入,容易漏掉最后一分钟的数据。我们把源端 crontab 放在15 3,而不是整点,就是给边界留出 15 分钟缓冲。
适用场景与不适用场景
适用:商品档案变更频次中等(每日几十到几千条),且下游策略(例如向旺店通的商品推送)依赖中间层的统一编码。不适用:金蝶端每日变更超过 5 万条且需近实时(分钟级)反映的场景,这种规模建议走消息队列而非 HTTP 轮询;也不适用于没有 modify_start_time 这类字段的老版本金蝶接口,需要改用全量对账。