API和数据故障排除
应对大规模提取故障、OData网络延迟和Business Central架构限制的响应协议。
在我们的DevSecOps工作中,确保数据管道(Data Pipelines)的完整性时,Business Central与商业智能平台的集成可能会出现瓶颈和网络障碍。
本文件详细说明了发现的最严重故障的根本原因及其基于已实施架构的最终解决方案。
事件1: “远程主机强制中断” (OData超时)
Sección titulada «Incidente 1: “Host remoto forzó la interrupción” (Timeout OData)»当尝试通过 Power Query、Power BI Desktop 或 Python 脚本更新历史数据集(例如超过 200,000 行)时,连接会加载数分钟,然后突然中断并返回错误:La conexión subyacente se cerró: El host remoto forzó la interrupción de la conexión. (OData Timeout)。
这是由 NST (Navision Server Tier) 资源耗尽 引起的故障。 当目标端点不是经过优化的 API (Query),而是作为 Web Service 公布的标准页面(例如:页面 38)时,就会发生这种情况。当向网页请求数千行数据时,Business Central 服务器会尝试在 RAM 中为每一行渲染视觉组件、执行触发器并计算复杂的子查询 (FlowFields)。当处理时间超过限制(通常为 10 或 15 分钟)时,Azure 负载均衡器会出于安全考虑切断 HTTP 连接,以防止 ERP 系统崩溃。
DevSecOps解决方案(已实施)
Sección titulada «Solución DevSecOps (Implementada)»- < strong >放弃基于Page的Web Services:</ strong >从架构中删除任何通过Page类型Web Services进行大规模数据消费的组件。
- 开发原生 API (Query): 将请求迁移到 AL 的
query对象。通过这种方式,执行过程将跳过界面层,转变为纯 SQL 语句,将响应时间从 15 分钟缩短至 30 秒以内。 - 分页(外部脚本): 如果我们使用 Python 等语言进行 ETL,必须确保遵守并编程跟踪服务器返回的
@odata.nextLink令牌,因为 Business Central 对返回的每个 JSON 页面的最大行数有限制。
事件2: 在API路径中无法创建子文件夹
Sección titulada «Incidente 2: Imposibilidad de Crear Subcarpetas en Rutas API»在 AL 中开发新 API 时,如果尝试通过在 API 属性中输入斜杠 (/) 来创建部门的逻辑层级,Visual Studio Code 编译器会抛出致命错误并阻止生成文件 .app。
错误代码示例:
// ERROR FATAL DE COMPILACIÓN: Microsoft prohíbe las barras en metadatos de enrutamientoAPIGroup = 'portelcore/departamentos/finanzas';Microsoft Business Central的OData V4生成引擎具有< strong >严格硬编码的结构化路径</ strong >。
服务器始终且仅预期一个不可变的 3 层模型:
{APIPublisher} / {APIGroup} / {APIVersion}
容器级别没有技术能力或权限来修改HTTP协调器并添加额外的“子文件夹”到Custom APIs的URL中。
采用严格的命名约定(< strong >Naming Conventions</ strong >)
由于无法通过 / 创建物理路径,我们通过在 APIGroup 或 APIPublisher 中使用下划线 (Snake_case) 来模拟层级结构。
-
正确实现(逻辑组):
APIPublisher = 'portelcore';APIGroup = 'api_portelcore_finanzas_1';APIVersion = 'v1.0';OData 结果:
.../api/portelcore/api_portelcore_finanzas_1/v1.0/ -
替代实现(逻辑发布者):
APIPublisher = 'portelcore_finanzas';APIGroup = 'analitica';APIVersion = 'v1.0';OData 结果:
.../api/portelcore_finanzas/analitica/v1.0/
- ✓ 性能: 将页面类型的服务完全替换为
Query API对象,以避免因 NST 的 RAM 溢出导致超时。 - ✓ 路由格式: 严格遵守AL编译器要求的三级架构规范,使用蛇形命名法表示逻辑层级。
- ✓ 同步: 清除客户端本地缓存以强制在重新配置后重新发现架构。

