Ir al contenido

Troubleshooting di API e Dati

Protocolli di risposta di fronte a errori di estrazione massiva, latenza di rete OData e vincoli architettonici in Business Central.

0letture

Nel nostro lavoro DevSecOps per garantire l'integrità delle pipeline di dati (Data Pipelines), l'integrazione tra Business Central e le piattaforme di Business Intelligence può presentare colli di bottiglia e impedimenti di rete.

Questo documento descrive in dettaglio le cause principali dei guasti più gravi riscontrati e le relative soluzioni definitive basate sull'architettura implementata.

Incidente 1: "L'host remoto ha forzato l'interruzione" (Timeout OData)

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

Tentando di aggiornare un set di dati storico (es. più di 200.000 righe) da Power Query, Power BI Desktop o tramite uno script Python, la connessione carica per diversi minuti e, improvvisamente, viene interrotta restituendo l'errore: La conexión subyacente se cerró: El host remoto forzó la interrupción de la conexión. (OData Timeout).

Questo è un errore dovuto a Esaurimento delle Risorse nel NST (Navision Server Tier). Si verifica quando l'endpoint di destinazione non è un'API ottimizzata (Query), ma una pagina standard pubblicata come Web Service (ad es. Pagina 38). Quando si richiedono migliaia di righe a una pagina web, il server di Business Central tenta di eseguire il rendering di componenti visuali, eseguire trigger e calcolare query complesse (FlowFields) in memoria RAM per ogni riga. Quando l'elaborazione supera i limiti di tempo (solitamente 10 o 15 minuti), il bilanciamento di Azure interrompe la connessione HTTP per sicurezza per evitare il crash dell'ERP.

  1. Abbandonare i Web Service basati su Page: Eliminare dall'architettura qualsiasi consumo massivo di dati tramite Web Service di tipo pagina.
  2. Sviluppare API Native (Query): Migrare la richiesta a un oggetto query in AL. In questo modo, l'esecuzione salta lo strato dell'interfaccia e diventa un'istruzione SQL pura, riducendo il tempo di risposta da 15 minuti a meno di 30 secondi.
  3. Paginazione (Script Esterni): Se utilizziamo un linguaggio come Python per l'ETL, dobbiamo assicurarci di rispettare e programmare il monitoraggio del token @odata.nextLink restituito dal server, poiché Business Central impone un limite massimo di righe per pagina JSON restituita.

Incidente 2: Impossibilità di creare sottocartelle nei percorsi API

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

Durante lo sviluppo di una nuova API in AL, tentando di creare una gerarchia logica di dipartimenti inserendo una barra diagonale (/) nelle proprietà dell'API, il compilatore di Visual Studio Code restituisce un errore fatale e blocca la generazione del file .app.

Esempio di codice difettoso:

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

Il motore di generazione OData V4 di Microsoft Business Central ha percorsi strutturali strettamente hardcoded (codificati in fabbrica).

Il server si aspetta sempre e solo un modello a 3 livelli immutabili: {APIPublisher} / {APIGroup} / {APIVersion}

Non esiste capacità tecnica né permessi a livello di container per alterare l'orchestratore HTTP e aggiungere segmenti o "sottocartelle" extra negli URL delle Custom API.

Adottare convenzioni di denominazione rigorose (Naming Conventions).

Non potendo creare percorsi fisici separati da /, simuliamo la gerarchia tramite underscore (Snake_case) all'interno di APIGroup o APIPublisher.

  • Implementazione corretta (Gruppo Logico):

    APIPublisher = 'portelcore';
    APIGroup = 'api_portelcore_finanzas_1';
    APIVersion = 'v1.0';

    Risultato OData: .../api/portelcore/api_portelcore_finanzas_1/v1.0/

  • Implementazione alternativa (Publisher Logico):

    APIPublisher = 'portelcore_finanzas';
    APIGroup = 'analitica';
    APIVersion = 'v1.0';

    Risultato OData: .../api/portelcore_finanzas/analitica/v1.0/

  • ✓ Performance: Sostituzione totale dei servizi di tipo pagina con oggetti Query API per evitare timeout causati dall'overflow della RAM nel NST.
  • ✓ Formato di Routing: Rispetto rigoroso dello schema a 3 livelli richiesto dal compilatore AL, utilizzando Snake_Case per le gerarchie logiche.
  • ✓ Sincronizzazione: Pulizia preventiva delle cache locali del client per forzare la rediscovery degli schemi dopo la riconfigurazione.