Ir al contenido

Troubleshooting von APIs und Daten

Antwortprotokolle bei Fehlern bei Massenextraktionen, OData-Netzwerklatenz und architektonischen Einschränkungen in Business Central.

0Lesungen

In unserer DevSecOps-Arbeit zur Sicherstellung der Integrität von Datenpipelines (Data Pipelines) kann die Integration zwischen Business Central und Business-Intelligence-Plattformen Engpässe und Netzwerkbehinderungen aufweisen.

Dieses Dokument beschreibt die Grundursachen der schwerwiegendsten aufgetretenen Fehler und ihre endgültigen Lösungen basierend auf der implementierten Architektur.

Vorfall 1: „Remote-Host hat die Verbindung erzwungen getrennt“ (OData-Timeout)

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

Beim Versuch, einen historischen Datensatz (z. B. mehr als 200.000 Zeilen) über Power Query, Power BI Desktop oder ein Python-Skript zu aktualisieren, lädt die Verbindung mehrere Minuten lang und bricht dann plötzlich mit der Fehlermeldung ab: La conexión subyacente se cerró: El host remoto forzó la interrupción de la conexión. (OData Timeout).

Dies ist ein Fehler durch Ressourcenerschöpfung im NST (Navision Server Tier). Er tritt auf, wenn der Ziel-Endpoint keine optimierte API (Query) ist, sondern eine Standardseite, die als Web Service veröffentlicht wurde (z. B. Seite 38). Wenn tausende Zeilen an eine Webseite angefordert werden, versucht der Business Central Server, visuelle Komponenten zu rendern, Trigger auszuführen und komplexe Unterabfragen (FlowFields) für jede Zeile im RAM zu berechnen. Wenn die Verarbeitung die Zeitlimits überschreitet (üblicherweise 10 oder 15 Minuten), trennt der Azure Load Balancer die HTTP-Verbindung aus Sicherheitsgründen, um einen Absturz des ERP zu verhindern.

  1. Verzicht auf page-basierte Web Services: Entfernen Sie jeglichen Massendatenverbrauch über Web Services vom Typ 'Page' aus der Architektur.
  2. Entwicklung nativer APIs (Query): Migrieren Sie die Anfrage auf ein query AL-Objekt. Durch diesen Schritt wird die UI-Schicht übersprungen und die Ausführung erfolgt als reiner SQL-Befehl, wodurch die Antwortzeit von 15 Minuten auf weniger als 30 Sekunden reduziert wird.
  3. Paginierung (Externe Skripte): Wenn wir eine Sprache wie Python für das ETL verwenden, müssen wir sicherstellen, dass wir das vom Server zurückgegebene @odata.nextLink-Token berücksichtigen und dessen Verfolgung programmieren, da Business Central ein Limit für die maximale Anzahl an Zeilen pro zurückgegebener JSON-Seite festlegt.

Vorfall 2: Unmöglichkeit, Unterordner in API-Routen zu erstellen

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

Während der Entwicklung einer neuen API in AL führt der Versuch, eine logische Hierarchie von Abteilungen durch Eingabe eines Schrägstrichs (/) in den API-Eigenschaften zu erstellen, zu einem fatalen Fehler im Visual Studio Code-Compiler, der die Generierung der Datei .app blockiert.

Beispiel für fehlerhaften Code:

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

Die OData-V4-Generierungs-Engine von Microsoft Business Central verfügt über strikt hardcodierte Strukturpfade.

Der Server erwartet stets und ausschließlich ein unveränderliches 3-Schichten-Modell: {APIPublisher} / {APIGroup} / {APIVersion}

Es gibt weder die technische Möglichkeit noch Berechtigungen auf Container-Ebene, um den HTTP-Orchestrator zu ändern und zusätzliche Segmente oder „Unterordner“ in den URLs der Custom APIs hinzuzufügen.

Einführung von strikten Benennungskonventionen (Naming Conventions).

Da keine getrennten physischen Pfade über / erstellt werden können, simulieren wir die Hierarchie durch Unterstriche (Snake_case) innerhalb von APIGroup oder APIPublisher.

  • Richtige Implementierung (logische Gruppe):

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

    OData-Ergebnis: .../api/portelcore/api_portelcore_finanzas_1/v1.0/

  • Alternative Implementierung (logischer Herausgeber):

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

    OData-Ergebnis: .../api/portelcore_finanzas/analitica/v1.0/

  • ✓ Query API, um RAM-Overflow-Timeouts im NST zu vermeiden.
  • ✓
  • ✓