Ir al contenido

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.

0lectures

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

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

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.

  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ó (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.nextLink retornat 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»

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

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.