Ir al contenido

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.

0lecturas

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

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

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.

  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: Impossibilidade de Criar Subpastas em Rotas 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.

Exemplo de código defeituoso:

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

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.

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.