Ir al contenido

Troubleshooting de APIs y Datos

Protocolos de respuesta frente a fallos de extracción masiva, latencia de red OData y restricciones arquitectónicas en Business Central.

0lecturas

En nuestra labor DevSecOps asegurando la integridad de las canalizaciones de datos (Data Pipelines), la integración entre Business Central y plataformas de Business Intelligence puede presentar cuellos de botella e impedimentos de red.

Este documento detalla las causas raíz de los fallos más graves encontrados y sus soluciones definitivas basadas en la arquitectura implementada.

Incidente 1: “Host remoto forzó la interrupción” (Timeout OData)

Sección titulada «Incidente 1: “Host remoto forzó la interrupción” (Timeout OData)»

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).

Este es un fallo por Agotamiento de Recursos en el NST (Navision Server Tier). Ocurre cuando el endpoint objetivo no es una API optimizada (Query), sino una página estándar publicada como Web Service (ej. Página 38). Al solicitar miles de filas a una página web, el servidor de Business Central intenta renderizar componentes visuales, ejecutar triggers y calcular subconsultas complejas (FlowFields) en la memoria RAM para cada fila. Cuando el procesamiento supera los límites temporales (habitualmente 10 o 15 minutos), el balanceador de Azure corta la conexión HTTP por seguridad para evitar una caída del ERP.

  1. Abandonar Web Services basados en Page: Eliminar de la arquitectura cualquier consumo de datos masivos a través de Web Services tipo página.
  2. 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.
  3. 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: Imposibilidad de Crear Subcarpetas en Rutas API

Sección titulada «Incidente 2: Imposibilidad de Crear Subcarpetas en Rutas API»

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.

Ejemplo de código defectuoso:

// ERROR FATAL DE COMPILACIÓN: Microsoft prohíbe las barras en metadatos de enrutamiento
APIGroup = 'portelcore/departamentos/finanzas';

El motor de generación OData V4 de Microsoft Business Central tiene rutas estructurales estrictamente codificadas de fábrica (hardcoded).

El servidor espera siempre y únicamente un modelo de 3 niveles inmutables: {APIPublisher} / {APIGroup} / {APIVersion}

No existe capacidad técnica ni permisos a nivel de contenedor para alterar el orquestador HTTP y añadir segmentos o “subcarpetas” extra en las URLs de las Custom APIs.

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/

  • ✓ 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.