Ir al contenido

Creëren van native API's (Query)

Ontwikkelings- en metadatastructureringsgids voor het publiceren van high-performance RESTful/OData V4-endpoints in AL.

0lecturas

Om onze geoptimaliseerde data-architectuur (ELT) op te bouwen, ontwikkelen we onze eigen API's in de taal AL met behulp van het object Query.

In tegenstelling tot traditionele API's waar we expliciete routes en controllers programmeren, definiëren we in AL een declaratieve structuur die de Business Central-engine automatisch blootstelt als een RESTful endpoint (OData V4).

Elk query API-object moet beginnen met een zeer strikte header die de routing en categorisering definieert.

query 50100 "Movs_Productos_API"
{
// 1. Declaración obligatoria para exponerlo como Endpoint
QueryType = API;
// 2. Enrutamiento de la URL OData
APIPublisher = 'portelcore';
APIGroup = 'api_portelcore_1';
APIVersion = 'v1.0';
// 3. Nomenclatura del recurso JSON
EntityName = 'movimiento';
EntitySetName = 'movimientos';
// 4. Integración con Power BI / Excel
QueryCategory = 'api_portelcore_1';
}
  • QueryType = API;: Deze regel zet de SQL-query om in een HTTP Web Service die van buitenaf toegankelijk is.

  • Routering (Het strikte patroon van Microsoft): De uiteindelijke URL die we consumeren volgt altijd dit onveranderlijke patroon: .../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}

    DevSecOps-notitie: Microsoft verbiedt het gebruik van schuine strepen / om te proberen logische “submappen” te creëren. Daarom gebruiken we, als we hiërarchie willen, naamconventies met underscores (api_portelcore_1).

  • EntityName en EntitySetName: Bepalen hoe de objecten in de resulterende JSON worden benoemd. EntitySetName (meervoud) zal de uiteindelijke tabelnaam zijn in de OData-URL.

  • QueryCategory: Door deze waarde toe te wijzen, zorgen we ervoor dat de native Business Central-connector in tools zoals Excel, Power Automate of Power BI onze API visueel kan lokaliseren binnen de map “Advanced APIs”.

De elements sectie van de query komt overeen met onze SQL-clausules SELECT en FROM. In plaats van generieke kolommen te declareren, 'projecteren' we alleen die kolommen die analytische waarde toevoegen.

elements
{
// Esto equivale al FROM "Item Ledger Entry"
dataitem(itemLedgerEntry; "Item Ledger Entry")
{
// Las columnas proyectadas (El SELECT)
column(Tipo_Movimiento; "Entry Type") { }
column(Num_Documento; "Document No.") { }
column(Fecha_Registro; "Posting Date") { }
column(Cantidad; Quantity) { }
// Opcional: El SystemId es vital si el destino requiere una clave única o UUID
column(systemId; SystemId) { }
}
}

Architectonisch Voordeel (Column Renaming)

Sección titulada «Ventaja Arquitectónica (Column Renaming)»

Zoals te zien is in de code, kunnen we aan de linkerkant (column(MiNombre; "Nombre Original")) de kolommen een nieuwe naam geven.

Dit stelt ons in staat om principes van Data Governance vanaf de bron toe te passen. Navision-databases hebben namen met spaties, punten en vreemde notaties (Shortcut Dimension 1 Code). Door ze te herschrijven als Cod_Dimension_1, besparen we transformatiestappen in Power Query en leveren we een veel schoner analytisch model aan het Business Intelligence-team.

  • ✓ Routing: Expliciete definitie van APIPublisher, APIGroup en APIVersion zonder schuine strepen / om compileerfouten te voorkomen.
  • ✓ Governance: Kolommen correctelijk hernoemd aan de bron met gebruik van een schone Snake_Case-notatie om modellering te vergemakkelijken.
  • ✓ Optimalisatie: Inclusie van SystemId (UUID) om te dienen als unieke primaire sleutel in de doelopslag.