Troubleshooting de APIs y Datos
Protocolos de resposta frente a falhas de extração massiva, latência de rede OData e restrições arquitetônicas em Business Central.
Em nosso trabalho DevSecOps garantindo a integridade dos pipelines de dados (Data Pipelines), a integração entre o Business Central e plataformas de Business Intelligence pode apresentar gargalos e impedimentos de rede.
Este documento detalha as causas raiz das falhas mais graves encontradas e suas soluções definitivas baseadas na arquitetura implementada.
Incidente 1: “Host remoto forçou a interrupção” (Timeout OData)
Sección titulada «Incidente 1: “Host remoto forzó la interrupción” (Timeout OData)»Sintoma
Sección titulada «Síntoma»Al intentar actualizar un conjunto de datos histórico (ej. más de 200.000 filas) desde Power Query, Power BI Desktop o mediante un script de Python, la conexión carga durante varios minutos y, repentinamente, se aborta devolviendo el error: La conexión subyacente se cerró: El host remoto forzó la interrupción de la conexión. (OData Timeout).
Diagnóstico Raiz
Sección titulada «Diagnóstico Raíz»Esta é uma falha por Esgotamento de Recursos no NST (Navision Server Tier). Ocorre quando o endpoint de destino não é uma API otimizada (Query), mas sim uma página padrão publicada como Web Service (ex: Página 38). Ao solicitar milhares de linhas a uma página web, o servidor do Business Central tenta renderizar componentes visuais, executar triggers e calcular subconsultas complexas (FlowFields) na memória RAM para cada linha. Quando o processamento excede os limites temporais (habitualmente 10 ou 15 minutos), o balanceador do Azure corta a conexão HTTP por segurança para evitar uma queda do ERP.
Solução DevSecOps (Implementada)
Sección titulada «Solución DevSecOps (Implementada)»- Abandonar Web Services basados en Page: Eliminar de la arquitectura cualquier consumo de datos masivos a través de Web Services tipo página.
- Desarrollar APIs Nativas (Query): Migrar la petición a un objeto query de AL. Al hacer esto, la ejecución salta la capa de interfaz y se convierte en una sentencia SQL pura, reduciendo el tiempo de respuesta de 15 minutos a menos de 30 segundos.
- Paginación (Scripts Externos): Si usamos un lenguaje como Python para el ETL, debemos asegurarnos de respetar y programar el seguimiento del token @odata.nextLink devuelto por el servidor, ya que Business Central impone un límite máximo de filas por página JSON devuelta.
Incidente 2: Impossibilidade de Criar Subpastas em Rotas API
Sección titulada «Incidente 2: Imposibilidad de Crear Subcarpetas en Rutas API»Sintoma (Nomenclatura e Roteamento)
Sección titulada «Síntoma (Nomenclatura y Enrutamiento)»Durante el desarrollo de una nueva API en AL, al intentar crear una jerarquía lógica de departamentos introduciendo una barra inclinada (/) en las propiedades de la API, el compilador de Visual Studio Code arroja un error fatal y bloquea la generación del archivo .app.
Exemplo de código defeituoso:
// ERROR FATAL DE COMPILACIÓN: Microsoft prohíbe las barras en metadatos de enrutamientoAPIGroup = 'portelcore/departamentos/finanzas';Diagnóstico Raiz
Sección titulada «Diagnóstico Raíz»El motor de generación OData V4 de Microsoft Business Central tiene rutas estructurales estrictamente codificadas de fábrica (hardcoded).
O servidor espera sempre e unicamente um modelo de 3 níveis imutáveis:
{APIPublisher} / {APIGroup} / {APIVersion}
Não existe capacidade técnica nem permissões a nível de contêiner para alterar o orquestrador HTTP e adicionar segmentos ou “subpastas” extras nas URLs das Custom APIs.
Solução / Workaround Arquitetônico
Sección titulada «Solución / Workaround Arquitectónico»Adoptar convenciones de nomenclatura estrictas (Naming Conventions).
Al no poder crear rutas físicas separadas por /, simulamos la jerarquía mediante guiones bajos (Snake_case) dentro del APIGroup o del APIPublisher.
-
Implementación correcta (Grupo Lógico):
APIPublisher = 'portelcore';APIGroup = 'api_portelcore_finanzas_1';APIVersion = 'v1.0';Resultado OData: .../api/portelcore/api_portelcore_finanzas_1/v1.0/
-
Implementación alternativa (Publisher Lógico):
APIPublisher = 'portelcore_finanzas';APIGroup = 'analitica';APIVersion = 'v1.0';Resultado OData: .../api/portelcore_finanzas/analitica/v1.0/
3. Checklist de Diagnóstico de API e Dados
Sección titulada «3. Checklist de Diagnóstico de API y Datos»- ✓ Rendimiento: Sustitución total de servicios de tipo página por objetos Query API para evitar timeouts por desbordamiento de RAM en el NST.
- ✓ Formato de Enrutamiento: Cumplimiento estricto del esquema de 3 niveles exigido por el compilador AL, empleando Snake_Case para jerarquías lógicas.
- ✓ Sincronización: Limpieza previa de cachés locales del cliente para forzar el redescubrimiento de esquemas tras la reconfiguración.

