金蝶云星空组织数据查询同步实战教程
小满OKKICRM金蝶云星空基础资料同步私有化部署executeBillQuery组织主数据
这个策略解决什么问题
在 CRM 与 ERP 的基础资料同步链路里,「组织」往往是第一张多米诺骨牌。小满 OKKI CRM 要把客户、订单、报价等业务单据推给金蝶云星空,前提是两边对「组织/部门/业务单元」的编码理解是一致的。我们在实际项目里见过太多情况:组织没先打通,下游物料、客户、销售订单同步过去全是错位。因此「查询金蝶组织」这条策略的本质是:在每日凌晨定时从金蝶云星空拉取组织档案,以 FNumber 为唯一键,落到轻易云数据集成平台作为后续所有单据同步的「基线参考表」。
数据流向与字段映射
整条链路是单向拉取:金蝶云星空 → 轻易云数据集成平台。源端走的是金蝶标准的 executeBillQuery WebAPI,目标端在轻易云侧是一个写入空操作节点(用于承载拉回来的数据并落库)。关键字段对照如下:
| 字段 | 源(金蝶云星空) | 中间层(轻易云) | 作用 |
|---|---|---|---|
| FNumber | 组织编码 | 主键 | 全局唯一标识,下游物料、客户都靠它关联 |
| FName | 组织名称 | 名称 | 展示、辅助识别 |
| Limit / StartRow / TopRowCount | 分页参数 | 调度器注入 | 控制单次拉取行数,默认 2000 一页 |
源端元数据里把 number 和 id 都指向 FNumber,这是金蝶这类基础资料常见的做法——编码本身就是业务键,不必再额外造主键。
在轻易云上如何配置
在轻易云数据集成平台里配置这条策略,典型分四块:
- 注册金蝶云星空连接器:填好私有化部署的访问地址、账套信息、认证方式。私有化环境下建议单独建一个只读账号,避免和高频写操作的业务账号混用。
- 配置源端元数据:API 选
executeBillQuery,method 设为 POST,把FName、FNumber放到 request 字段里,Limit、StartRow、TopRowCount放到 otherRequest,并把分页参数值用{{PAGINATION_PAGE_SIZE}}、{{PAGINATION_START_ROW}}这类占位符交给轻易云调度器注入。 - 配置目标端节点:目标端的
api设为「写入空操作」,因为本策略只负责把组织数据落到平台中间库,真正的分发留给下游策略(比如物料、客户)。这种「先落中间层、再按需分发」的做法,是轻易云客户常见的应对模式,后面想加转换、加校验、改目标系统,都不必回头改源。 - 打开编码映射集中管理:在轻易云的「映射管理」里统一维护 FNumber → 内部组织编码 的对照。新接入一个业务系统时,只需要在这一个地方加映射规则,所有依赖组织的下游策略都能自动复用。
实施步骤
调度设计上,我们一般分三段跑:
- 第一次跑:做一次全量,把金蝶当前所有组织档案一次性拉过来。这一步通常放在凌晨业务低峰期,源端 crontab 设为
3 2 * * *(每天凌晨 2:03),配合目标端的23 2 * * *(2:23)留出窗口期,让源端先写完、目标端再消费,避免两端抢资源。 - 稳态增量:全量跑完之后,切换到增量。增量起点可以用一个「上次最大更新时间」或者直接用 FNumber 排序的游标,确保新增和修改的组织都能被覆盖。
- 调度频率:组织这类基础资料变更频率很低,每天一次足够。但我们建议保留「全量触发」开关,作为季度对账的兜底——增量久了,难免漏掉边缘场景,这时候手动触一次全量,半小时内就能把两边数字拉平。
踩坑复盘
- 分页参数别写死。金蝶的
Limit如果硬编码成 2000,数据量超过 2000 行就漏。这里稳妥的做法是用轻易云的分页占位符,让平台按页循环拉。 - 私有化环境时间不同步。金蝶服务器、轻易云调度器、数据库服务器时钟偏几分钟,会导致调度窗口错位。建议在轻易云里统一配 NTP,并在策略里加一个「源端时间窗口」的过滤条件。
- FNumber 重复别忽视。同一个组织在金蝶里如果被禁用又重新启用,会出现两条 FNumber 相同的记录,idCheck 设成 false 容易把脏数据带过来。稳妥的做法是目标端加一个去重步骤,以最新修改时间为准。
- 目标端别真的「空操作」。虽然 metadata 里 api 叫「写入空操作」,但底层是落到了轻易云中间库,后续查询、关联都靠这张表。命名上要清楚它就是组织基线表,别让运维同事误以为可以清理。
- 下游策略别硬编码组织编码。组织拉过来之后,物料、客户、销售订单这些下游策略都应该通过编码映射集中管理查表,而不是在脚本里写死「01 代表华东大区」。
适用场景与不适用场景
适用:私有化部署的 ERP + CRM 集成,需要为下游业务单据同步提供组织基线;组织变更频率低,但必须保证全局一致。 不适用:组织高频变动、需要实时推送(分钟级) 的场景;以及没有金蝶 executeBillQuery 权限、只能走数据库直连的环境——那种情况得另开一条链路,本策略不能复用。
本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/solutions/strat-okkicrm-kingdee-cloud-3152-ok-2f8ae756