供应商账号查询同步方案:从钉钉拉取写入轻易云中间层的实战拆解
这个策略解决什么问题(场景与价值)
某零售企业把供应商账号的日常维护放在钉钉低代码表单里,业务侧录入方便,但下游金蝶云星空、SRM 报表都依赖同一份主数据。这里需要一个**「供应商账号查询」**策略:从钉钉定时拉取最新账号数据,落到轻易云数据集成平台(Qeasy)的中间层,作为后续分发的统一口径。它本身不直接写业务系统,先把数据稳住在集成平台里,再交给其他策略消费。
数据流向与字段映射
整体流向是 钉钉 → 轻易云集成平台,源端是查询接口、目标端是空操作写入(用于触发/占位,真实落到中间层靠平台自身承接)。
| 维度 | 源端(钉钉) | 中间层(轻易云 datahub) | 备注 |
|---|---|---|---|
| 平台类型 | 钉钉低代码表单 | 轻易云集成平台 | 私有化部署 |
| 接口动作 | QUERY 拉取实例列表 | EXECUTE 空写入占位 | 用于触发/留痕 |
| HTTP 方法 | POST | POST | 两侧均为 POST |
| 分页 | pageNumber / pageSize=100 | — | 默认每页 100 条 |
| 主键字段 | formInstId | 0(占位) | 源端 idCheck=true |
| 业务编号 | title | 0(占位) | 用作业务单据号 |
| 增量字段 | modifiedToTimeGMT | — | 控制时间窗 |
| 调度 | 20 1-3 * * *(每 1 小时窗口内的第 20 分) | 1 1 1 1 1(占位) | 源端为准 |
设计上有一个值得展开的细节:目标端 api 写的是「写入空操作」、request 与 response 都是空数组,number 与 id 都置为 0。这不是漏配,而是典型的「目标端占位」写法——策略真正承接写入的是轻易云集成平台中间层,源端按表单实例原样落入即可。
在轻易云上如何配置
第一步,在轻易云里注册两个平台连接:钉钉(代号 Dingtalk) 作为源、轻易云集成平台(代号 datahub) 作为目标,私有化环境下分别填入各自的服务地址与凭证。
第二步,新建策略,选「鸿巢基础资料-供应商账号查询」模板。源端选 WebAPI,effect 选 QUERY,粘贴源端 api 路径,逐项映射请求字段:appType、formUuid 用常量、pageNumber 与 pageSize 用内置分页变量、modifiedToTimeGMT 留给增量脚本注入。目标端 effect 选 EXECUTE,api 留「写入空操作」标识,request/response 保持空。
第三步,挂脚本。增量时间窗是这条策略的关键——脚本读取上次成功时间,转成 GMT 字符串写入 modifiedToTimeGMT,轻易云跑完一轮后把当前时间写回游标表,实现「按修改时间滚动拉取」。
实施步骤
阶段一:增量起点
先做一次全量回灌,在轻易云里把 modifiedToTimeGMT 设成一个很早的时间戳,触发首跑,等中间层数据量稳定。
阶段二:全量触发 随后人工跑一次全量,核对中间层记录数与钉钉表单实例数一致。这一步的目的不是上线,而是建立「双方对得上」的心理预期。
阶段三:调度频率
源端 cron 设为 20 1-3 * * *,即每小时内的第 20 分钟跑一次,避开整点高峰。轻易云客户常见做法是**「增量与全量双轨」**:增量按小时跑、全量夜里跑一次,任何一边漂了都能被另一边的覆盖逻辑兜住。
上线后第一周每天人工抽 20 条核对,第二周起改成异常告警驱动。
踩坑复盘
坑一:把分页参数当常量写死。 pageNumber 必须用轻易云内置分页变量,手写 0 就只拉一页。这里容易翻车,典型错误是首次全量只跑出 100 条。
坑二:idCheck 没启用。 源端 idCheck=true 是幂等的关键,关闭它,轻易云中间层会出现重复 formInstId,下游 SRM 一对就乱。
坑三:增量时间窗没做时区转换。 钉钉字段是 GMT,脚本里直接用本地时间塞进去,拉不到新增。稳妥的做法是脚本统一在 UTC 下计算。
坑四:目标端当成真写入去配字段。 这个策略目标端就是空占位,把精力花在配 request/response 字段上是徒劳。
坑五:轻忽编码映射集中管理。 供应商编码在钉钉是字符串、在金蝶侧可能要补前缀,轻易云客户常见的应对模式是把这类映射集中放在轻易云的「编码映射」模块,不要散落在每条策略脚本里。
适用场景与不适用场景
适用:源端是钉钉低代码表单、维护频率高、需要把账号类主数据先稳在中间层再分发,且对实时性要求是小时级。
不适用:要求分钟级实时同步的场景(应该走事件/消息触发,而不是 cron 拉取);以及字段级双向同步——该策略只承担单向回灌。