Dépannage d'API et de données
Protocoles de réponse face aux échecs d'extraction massive, à la latence réseau OData et aux contraintes architecturales dans Business Central.
Dans notre travail DevSecOps visant à assurer l'intégrité des pipelines de données (Data Pipelines), l'intégration entre Business Central et les plateformes de Business Intelligence peut présenter des goulots d'étranglement et des obstacles réseau.
Ce document détaille les causes profondes des défaillances les plus graves rencontrées et leurs solutions définitives basées sur l'architecture implémentée.
Incident 1 : « L'hôte distant a forcé l'interruption » (Timeout OData)
Sección titulada «Incidente 1: “Host remoto forzó la interrupción” (Timeout OData)»Symptôme
Sección titulada «Síntoma»Lors de la tentative de mise à jour d'un ensemble de données historiques (ex. plus de 200 000 lignes) à partir de Power Query, Power BI Desktop ou via un script Python, la connexion charge pendant plusieurs minutes puis s'interrompt soudainement en renvoyant l'erreur : La conexión subyacente se cerró: El host remoto forzó la interrupción de la conexión. (OData Timeout).
Diagnostic racine
Sección titulada «Diagnóstico Raíz»Ceci est une erreur due à l'épuisement des ressources sur le NST (Navision Server Tier). Cela se produit lorsque l'extrémité cible n'est pas une API optimisée (requête), mais une page standard publiée en tant que service Web (par exemple, page 38). Lors de la demande de milliers de lignes à une page Web, le serveur Business Central tente de restituer des composants visuels, d'exécuter des déclencheurs et de calculer des sous-requêtes complexes (FlowFields) en mémoire RAM pour chaque ligne. Lorsque le traitement dépasse les limites de temps (généralement 10 ou 15 minutes), l'équilibreur de charge Azure coupe la connexion HTTP pour des raisons de sécurité pour éviter une panne de l'ERP.
Solution DevSecOps (Implémentée)
Sección titulada «Solución DevSecOps (Implementada)»- Abandonner les Web Services basés sur les pages : Éliminer de l'architecture toute consommation massive de données via des Web Services de type page.
- Développer des API natives (Query) : Migrer la requête vers un objet
queryen AL. Ce faisant, l'exécution contourne la couche d'interface et devient une instruction SQL pure, réduisant le temps de réponse de 15 minutes à moins de 30 secondes. - Pagination (Scripts externes) : Si nous utilisons un langage comme Python pour l'ETL, nous devons nous assurer de respecter et de programmer le suivi du jeton
@odata.nextLinkrenvoyé par le serveur, car Business Central impose une limite maximale de lignes par page JSON renvoyée.
Incident 2 : Impossibilité de créer des sous-dossiers dans les routes API
Sección titulada «Incidente 2: Imposibilidad de Crear Subcarpetas en Rutas API»Symptôme (Nomenclature et Routage)
Sección titulada «Síntoma (Nomenclatura y Enrutamiento)»Lors du développement d'une nouvelle API en AL, en tentant de créer une hiérarchie logique de départements en introduisant une barre oblique (/) dans les propriétés de l'API, le compilateur de Visual Studio Code renvoie une erreur fatale et bloque la génération du fichier .app.
Exemple de code défectueux :
// ERROR FATAL DE COMPILACIÓN: Microsoft prohíbe las barras en metadatos de enrutamientoAPIGroup = 'portelcore/departamentos/finanzas';Diagnostic racine
Sección titulada «Diagnóstico Raíz»Le moteur de génération OData V4 de Microsoft Business Central possède des routes structurelles strictement codées en dur (hardcoded).
Le serveur attend toujours et uniquement un modèle à 3 niveaux immuable:
{APIPublisher} / {APIGroup} / {APIVersion}
Il n'y a ni capacité technique ni autorisations au niveau du conteneur pour modifier l'orchestrateur HTTP et ajouter des segments ou des « sous-dossiers » supplémentaires dans les URL des API personnalisées (Custom APIs).
Solution / Contournement architectural
Sección titulada «Solución / Workaround Arquitectónico»Adopter des conventions de nommage strictes (Naming Conventions).
Ne pouvant pas créer de routes physiques séparées par /, nous simulons la hiérarchie à l'aide de tirets bas (Snake_case) à l'intérieur du APIGroup ou du APIPublisher.
-
Implémentation correcte (Groupe logique) :
APIPublisher = 'portelcore';APIGroup = 'api_portelcore_finanzas_1';APIVersion = 'v1.0';Résultat OData :
.../api/portelcore/api_portelcore_finanzas_1/v1.0/ -
Implémentation alternative (Éditeur logique) :
APIPublisher = 'portelcore_finanzas';APIGroup = 'analitica';APIVersion = 'v1.0';Résultat OData :
.../api/portelcore_finanzas/analitica/v1.0/
3. Liste de contrôle de diagnostic d'API et de données
Sección titulada «3. Checklist de Diagnóstico de API y Datos»- ✓ Performance : Remplacement complet des services de type page par des objets
Query APIpour éviter les timeouts dus à un dépassement de la RAM sur le NST. - ✓ Format de routage : Conformité stricte au schéma à 3 niveaux exigé par le compilateur AL, en utilisant le Snake_Case pour les hiérarchies logiques.
- ✓ Synchronisation : Nettoyage préalable des caches locaux du client pour forcer la redécouverte des schémas après la reconfiguration.

