Troubleshooting de APIs y Datos
Protocols de resposta davant errors d'extracció massiva, latència de xarxa OData i restriccions arquitectòniques a Business Central.
En la nostra tasca DevSecOps assegurant la integritat de les canalitzacions de dades (Data Pipelines), la integració entre Business Central i plataformes de Business Intelligence pot presentar colls d'ampolla i impediments de xarxa.
Aquest document detalla les causes arrel de les fallades més greus trobades i les seves solucions definitives basades en l'arquitectura implementada.
Incident 1: “L'amfitrió remot ha forçat la interrupció” (Timeout OData)
Sección titulada «Incidente 1: “Host remoto forzó la interrupción” (Timeout OData)»Símptoma
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òstic Arrel
Sección titulada «Diagnóstico Raíz»Aquest és un error per Agotamiento de Recursos en el NST (Navision Server Tier). Ocorregut quan l'endpoint objectiu no és una API optimitzada (Query), sinó una pàgina estàndard publicada com a Web Service (ex. Pàgina 38). En sol·licitar milers de files a una pàgina web, el servidor de Business Central intenta renderitzar components visuals, executar triggers i calcular subconsultes complexes (FlowFields) en la memòria RAM per a cada fila. Quan el processament supera els límits temporals (habitualment 10 o 15 minuts), l'equilibrador d'Azure retalla la connexió HTTP per seguretat per evitar una caiguda de l'ERP.
Solució 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ó (Scripts Externs): Si utilitzem un llenguatge com Python per a l'ETL, hem d'assegurar-nos de respectar i programar el seguiment del token
@odata.nextLinkretornat pel servidor, ja que Business Central imposa un límit màxim de files per pàgina JSON retornada.
Incident 2: Impossibilitat de Crear Subcarpetes en Rutes API
Sección titulada «Incidente 2: Imposibilidad de Crear Subcarpetas en Rutas API»Símptoma (Nomenclatura i Enrutament)
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.
Exemple de codi defectuós:
// ERROR FATAL DE COMPILACIÓN: Microsoft prohíbe las barras en metadatos de enrutamientoAPIGroup = 'portelcore/departamentos/finanzas';Diagnòstic Arrel
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).
El servidor espera sempre i únicament un model de 3 nivells immutable:
{APIPublisher} / {APIGroup} / {APIVersion}
No existeix capacitat tècnica ni permisos a nivell de contenidor per alterar l'orquestrador HTTP i afegir segments o “subcarpetes” extra en les URLs de les Custom APIs.
Solució / Workaround Arquitectònic
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òstic d'API i Dades
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.

