金蝶云星空辅助资料-区查询接口字段手册：executeBillQuery 实战教程

这个接口解决什么问题

在旺店通与金蝶云星空的供应链集成场景里,「区」级行政区划是地址、收货区域、客户/供应商档案里绕不开的字典类基础数据。不同系统对「区」的编码、名称各自为政,如果不在初期建立统一的主数据映射,后续的客户、订单、收货单很容易出现地址错位、区域无法匹配的问题。本接口通过金蝶 WebAPI 的 executeBillQuery,按辅助资料类别 D01 把金蝶侧的「区」明细批量拉出来,供下游系统做编码对照与名称展示,是典型的「只查询、不写入」的主数据同步前置动作。

接口能力总览

• 所属系统:金蝶云星空(BOS 平台)。
• 调用方式:HTTPS POST,走金蝶 WebAPI 的 executeBillQuery 统一入口。
• 请求参数:核心三件套——FormId=BOS_ASSISTANTDATA_DETAIL(辅助资料明细表)、FilterString=FId.FNumber='D01'(只查「区」类别)、FieldKeys(返回字段集合)。
• 分页模式:金蝶标准的 StartRow + Limit(默认 2000/页,部分环境支持 5000),大数据量场景需要循环翻页直到返回为空。
• 增量模式:原生 executeBillQuery 不提供基于时间的增量字段,通常以 FEntryID 或最后修改时间作为外部水位线,每日 0:00 全量重拉一次,在消费端做差异比对。
• 响应结构:每条记录是一个字典项明细,含 FEntryID(主键)、FNumber(编码)、FDataValue(名称)等核心字段,外层由 Result 列表承载。

典型字段映射

在轻易云数据集成平台里,这个接口通常以「金蝶辅助资料查询」适配器封装,字段映射器会自动识别 FEntryID 为主键、FNumber 为业务编码,无需手工在脚本里二次声明。

在轻易云上如何配置

1. 数据源适配:选择「金蝶云星空」连接器,填入认证信息(数据中心 ID、应用 ID、密钥、用户),平台已内置 executeBillQuery 调用模板。
2. 策略类型:选「QUERY 仅查询」,Target 端配置为「写入空操作」,这正是本接口的标准用法。
3. 过滤条件:在可视化配置面板里,把 FilterString 写成 FId.FNumber='D01',平台会把它原样透传给金蝶 API,不需要额外的脚本预处理。
4. 字段映射器:把返回的 FEntryID、FNumber、FDataValue 映射到目标端的 district_id、district_code、district_name 字段,轻易云的字段映射器会自动处理类型转换。
5. 定时调度:按本策略默认 0 0 * * * 每日 0:00 全量拉取一次,放在旺店通地址类同步策略的前置依赖位,确保下游消费时主数据已就绪。

跨方案实战要点

1. D01 不是通用编码:不同客户环境里,辅助资料类别「区」的编码未必都是 D01,务必先用 SELECT * FROM T_BAS_ASSISTANTDATA_L WHERE FName LIKE '%区%' 之类的方式在金蝶侧确认一遍,再决定 FilterString。
2. FNumber 与 FDataValue 不要混用:在多个客户方案里都见过工程师把 FDataValue(名称)误当作业务编码去建主数据映射,导致同名区县冲撞。编码永远是 FNumber,名称仅用于展示。
3. 父子层级别拍脑袋:金蝶辅助资料支持省/市/区层级,跨系统拉取时只取叶子级「区」即可,过早把省、市拉进主数据池,会让地址字段填值时无所适从。
4. 分页上限别卡满:2000 条/页是金蝶推荐值,虽然部分环境能放到 5000,但跨客户复用策略模板时,稳妥做法是统一用 2000,避免某个环境超限直接报错。
5. 依赖顺序要显式声明:在供应链集成方案里,「区」主数据应当显式声明为「客户地址」「供应商地址」「收货地址」等策略的 depends_on 前置,否则首次同步时下游会拿到空映射。
6. 全量重拉的代价:D01 类别一般几千到上万条,全量重拉对金蝶 API 压力可控;但如果扩展到「省」「市」级别(单类超 10 万),建议改成按修改时间增量,否则容易触发金蝶侧的限流。

踩坑复盘

• 坑 1:FId.FNumber 写成中文:FilterString 里把 D01 误写成「区」,金蝶返回为空,但平台不报错,导致下游永远拿到空主数据。应对:过滤条件必须用类别编码,而不是类别名称。
• 坑 2:把 FDataValue 当主键:用「朝阳区」这种名称字符串当主键,后续金蝶侧名称变更后,所有外键引用全断。应对:主键统一用 FEntryID,业务编码统一用 FNumber。
• 坑 3:忽略父子层级:把省、市、区一锅端拉回来,在旺店通地址字段填值时不知道该选哪一层,出现「省写到区字段」的脏数据。应对:FilterString 严格限定到 D01,只取叶子级。
• 坑 4:分页漏掉末页:循环里只判断了「数据非空」,没判断「数据条数 < Limit」,导致最后一页被重复拉取甚至死循环。应对:循环条件同时校验 len(rows) < Limit,优雅退出。
• 坑 5:调度时间与下游重叠:每日 0:00 全量拉取,但下游客户同步策略也跑在 0 点附近,造成「主数据还没拉到、下游已经开始消费」的空指针。应对:把主数据策略提前到 23:30,或显式配置下游策略的 depends_on。

何时选用

适用于需要从金蝶云星空按类别批量获取字典类主数据、且消费端在旺店通或其他外部系统的供应链集成场景,尤其是地址类字段对行政区划编码有强依赖的业务。若你需要的不是「区」而是「省」「市」或自定义辅助资料类别,只需替换 FilterString 即可复用同一接口模板,但超大规模(10 万+)的类别建议改用增量接口。