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.
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)»Sintomo
Sección titulada «Síntoma»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).
Diagnosi alla Radice
Sección titulada «Diagnóstico Raíz»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.
Soluzione DevSecOps (Implementata)
Sección titulada «Solución DevSecOps (Implementada)»- Abbandonare i Web Service basati su Page: Eliminare dall'architettura qualsiasi consumo massivo di dati tramite Web Service di tipo pagina.
- Sviluppare API Native (Query): Migrare la richiesta a un oggetto
queryin 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. - Paginazione (Script Esterni): Se utilizziamo un linguaggio come Python per l'ETL, dobbiamo assicurarci di rispettare e programmare il monitoraggio del token
@odata.nextLinkrestituito 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»Sintomo (Nomenclatura e Routing)
Sección titulada «Síntoma (Nomenclatura y Enrutamiento)»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 enrutamientoAPIGroup = 'portelcore/departamentos/finanzas';Diagnosi alla Radice
Sección titulada «Diagnóstico Raíz»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.
Soluzione / Workaround Architetturale
Sección titulada «Solución / Workaround Arquitectónico»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/
3. Checklist di Diagnostica di API e Dati
Sección titulada «3. Checklist de Diagnóstico de API y Datos»- ✓ Performance: Sostituzione totale dei servizi di tipo pagina con oggetti
Query APIper 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.

