金蝶云星空多组织查询接口(ExecuteBillQuery · ORG_Organizations)字段手册与实战教程

这个接口解决什么问题

在金蝶云星空与钉钉的集成场景里,「组织」是数据隔离、权限控制和单据归属的核心维度。该接口通过 ExecuteBillQuery 查询金蝶 ORG_Organizations 表,把多组织主数据按增量方式同步到集成平台,用于组织架构同步、组织选择器数据源、多组织映射以及与钉钉部门建立对应关系。它本身是只读查询,不承担写入,是多组织集成链路里的"地基"。

接口能力总览

• 接口名称:ExecuteBillQuery(金蝶云星空通用单据查询接口)
• FormId:ORG_Organizations(组织表)
• 请求方法:POST
• 策略类型:QUERY(仅查询,不写入目标系统)
• 认证方式:通过金蝶云星空 API 网关进行用户身份认证,集成平台侧在轻易云里配置应用凭证即可
• 请求结构:核心参数包括 FormId、FieldKeys(要返回的字段集合)、FilterString(过滤条件,支持 FModifyDate 增量)、OrderString、Limit、StartRow、TopRowCount
• 分页模式:Limit + StartRow 组合分页,Limit 默认 100,StartRow 默认 0;TopRowCount 用于返回总行数评估
• 增量模式:FilterString 使用 FModifyDate>'{{LAST_SYNC_TIME|datetime}}' 形式,按修改时间滚动拉取
• 执行频率:每 3 小时执行一次(crontab: 3 * * * *)

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,这个接口被封装成「金蝶云星空查询」适配器,源端动作直接选 ExecuteBillQuery,FormId 填 ORG_Organizations。平台会提供可视化的元数据浏览,自动把 Number / Name / ParentOrg_* / FModifyDate 等字段拉成可拖拽的列。

• 凭证:在轻易云的连接管理处维护金蝶云星空的应用 ID 与密钥,平台会自动处理签名与会话。
• 字段映射:通过轻易云的字段映射器,把金蝶侧的 Number 映射到目标平台的 organization_code,Name 映射到 organization_name,ParentOrg_Number 映射到 parent_organization_code,FModifyDate 映射到 last_modified_at。审计链字段(以 _Id/_Name/_Number 结尾)在映射器里可一键展开。
• 增量策略:轻易云支持把 {{LAST_SYNC_TIME|datetime}} 直接作为变量注入 FilterString,平台会按上次同步成功时间自动滚动。
• 调度:轻易云调度器里把 crontab 设为 3 * * * *,并开启「失败重试 + 断点续跑」。

跨方案实战要点

1. Number 是唯一"锚点":金蝶侧 id 与 number 都配置为 FNumber,跨系统匹配必须以 Number 为准,不要用 Name,容易重名。
2. 增量条件只看 FModifyDate:不要混用 CreateDate 或 AUDITDATE 做增量,FModifyDate 才能覆盖所有类型的变更。
3. ParentOrg 必带:多组织映射到钉钉部门时,ParentOrg_Number 是构建树形结构的关键,缺失会导致下游无法构建层级。
4. 禁用与状态双过滤:建议在 FilterString 里追加 FForbidStatus='A' AND FDocumentStatus='C',只同步已审核未禁用的组织,避免把脏数据带入下游。
5. 分页 Limit 不要设太大:金蝶侧单次返回过大容易超时,稳妥的做法是 Limit=200、配合 Limit+StartRow 翻页。
6. 审计字段展平再映射:CreatorId_* 等是对象结构,在轻易云字段映射器里要先展开成 _Id/_Name/_Number 三列再映射,避免下游收到嵌套对象。

踩坑复盘

1. FilterString 时间格式不对:金蝶要求 yyyy-MM-dd HH:mm:ss,如果传 ISO 字符串会直接返回空。这里容易翻车,稳妥的做法是在轻易云里用平台内置的 datetime 格式化器。
2. 增量漏数据:只过滤 FModifyDate 但没考虑跨时区,服务器时区与金蝶时区不一致会导致漏拉。建议在请求前统一按 FTimeZone 做时区换算。
3. ParentOrg_Number 为空:顶层法人组织的 ParentOrg 为空,映射到下游时要做空值保护,不然树形结构会断根。
4. Limit 超限被截断:Limit 设成 2000 以上时,金蝶会强制截断并只返回前 N 条,容易被误认为"已经查完"。一定要结合 TopRowCount 判断是否还有下一页。
5. 审计链字段是对象不是字符串:直接把 CreatorId_Name 当字符串映射会失败,在轻易云里要勾选「对象展平」选项。

何时选用

当你的场景需要把金蝶云星空的多组织主数据同步到下游(钉钉、HR、ERP、BI),并以此构建组织选择器、数据权限或审批流时,适用本接口。边界:它只负责"查询组织主数据",不写入任何目标系统;若需要把组织写入钉钉或回写金蝶,需配合其他写入类策略组合使用。