Ir al contenido

Troubleshooting van API's en gegevens

Responseprotocollen voor fouten bij massale extractie, OData-netwerklatentie en architecturale beperkingen in Business Central.

0lecturas

In ons DevSecOps-werk om de integriteit van datapijplijnen (Data Pipelines) te waarborgen, kan de integratie tussen Business Central en Business Intelligence-platforms knelpunten en netwerkbelemmeringen opleveren.

Dit document beschrijft de hoofdoorzaken van de ernstigste fouten die zijn aangetroffen en hun definitieve oplossingen op basis van de geïmplementeerde architectuur.

Incident 1: "Externe host heeft de verbinding verbroken" (OData Timeout)

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

Bij het proberen een historische dataset bij te werken (bijv. meer dan 200.000 rijen) vanuit Power Query, Power BI Desktop of via een Python-script, laadt de verbinding gedurende enkele minuten en wordt deze plotseling afgebroken met de foutmelding: La conexión subyacente se cerró: El host remoto forzó la interrupción de la conexión. (OData Timeout).

Dit is een fout door Bronuitputting in de NST (Navision Server Tier). Het treedt op wanneer het doel eindpunt geen geoptimaliseerde API (Query) is, maar een standaardpagina die is gepubliceerd als webservice (bijv. pagina 38). Bij het verzoeken van duizenden rijen naar een webpagina, probeert de Business Central-server visuele componenten te renderen, triggers uit te voeren en complexe subconsultaties (FlowFields) in het RAM-geheugen voor elke rij te berekenen. Wanneer de verwerking de tijdelijke limieten (meestal 10 of 15 minuten) overschrijdt, snijdt de Azure-balancer de HTTP-verbinding voor beveiliging om een crash van de ERP te voorkomen.

DevSecOps-oplossing (Geïmplementeerd)

Sección titulada «Solución DevSecOps (Implementada)»
  1. Afstappen van Page-gebaseerde Web Services: Verwijder alle consumptie van massale gegevens via Web Services van het type 'pagina' uit de architectuur.
  2. Natuurlijke API's (Query) ontwikkelen: Migreer de aanvraag naar een AL-object query. Door dit te doen, slaat de uitvoering de interface-laag over en wordt het een pure SQL-statement, waardoor de responstijd wordt verkort van 15 minuten naar minder dan 30 seconden.
  3. Paginering (Externe Scripts): Als we een taal als Python gebruiken voor ETL, moeten we ervoor zorgen dat we de token @odata.nextLink die door de server wordt geretourneerd, respecteren en de tracking ervan programmeren, aangezien Business Central een maximum aantal rijen per geretourneerde JSON-pagina oplegt.

Incident 2: Onmogelijkheid om submappen te maken in API-routes

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

Tijdens de ontwikkeling van een nieuwe API in AL, wanneer geprobeerd wordt een logische hiërarchie van afdelingen te maken door een schuine streep (/) in de API-eigenschappen in te voeren, geeft de Visual Studio Code-compiler een fatale fout en blokkeert het de generatie van het bestand .app.

Voorbeeld van defecte code:

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

De OData V4-generatiemotor van Microsoft Business Central heeft strikt hardcoded structurele paden.

De server verwacht altijd en alleen een onveranderlijk 3-laags model: {APIPublisher} / {APIGroup} / {APIVersion}

Er is geen technische capaciteit of toestemming op containerniveau om de HTTP-orchestrator te wijzigen en extra segmenten of "submappen" toe te voegen aan de URL's van de Custom API's.

Strikte naamgevingsconventies hanteren (Naming Conventions).

Omdat we geen fysieke paden kunnen maken die gescheiden zijn door /, simuleren we de hiërarchie met underscores (Snake_case) binnen APIGroup of APIPublisher.

  • Correcte implementatie (Logische groep):

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

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

  • Alternatieve implementatie (Logische Publisher):

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

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

  • ✓ Prestaties: Volledige vervanging van pagina-type services door Query API objecten om timeouts door RAM-overbelasting in de NST te voorkomen.
  • ✓ Routingformaat: Strikte naleving van het door de AL-compiler vereiste 3-levels schema, waarbij Snake_Case wordt gebruikt voor logische hiërarchieën.
  • ✓ Synchronisatie: Voorafgaande opschoning van lokale client-caches om herontdekking van schema's na herconfiguratie af te dwingen.