Vytváření nativních API (Query)
Průvodce vývojem a strukturováním metadat pro publikaci vysoce výkonných RESTful/OData V4 endpointů v AL.
Pro vybudování naší optimalizované datové architektury (ELT) vyvíjíme vlastní API v jazyce AL pomocí objektu Query.
Na rozdíl od tradičních API, kde programujeme explicitní cesty a kontrolery, v AL definujeme deklarativní strukturu, kterou engine Business Central automaticky vystavuje jako RESTful endpoint (OData V4).
1. Struktura a metadata hlavičky
Sección titulada «1. Estructura y Metadatos de Cabecera»Každý objekt query typu API musí začínat velmi přísnou záhlaví, které definuje jeho směrování a kategorizaci.
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';}Analýza kritických parametrů
Sección titulada «Análisis de los Parámetros Críticos»-
QueryType = API;: Tento řádek je ten, který převádí dotaz SQL na webovou službu HTTP dostupnou z vnějšku. -
Enrutamiento (El Patrón Restricto de Microsoft):\r La URL final que consumiremos siempre sigue este patrón inmutable:\r
.../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}Poznámka DevSecOps: Microsoft zakazuje používání lomítka
/pokusy o vytváření logických „podsložek“. Proto, pokud chceme hierarchii, používáme konvence názvů s podtržítky (api_portelcore_1). -
EntityNameaEntitySetName: Definují, jak jsou pojmenovány objekty ve výsledném JSONu.EntitySetName(množné číslo) bude finálním názvem tabulky v OData URL. -
QueryCategory: Přiřazením této hodnoty umožníme nativnímu konektoru Business Central v nástrojích jako Excel, Power Automate nebo Power BI vizuálně lokalizovat naše API ve složce „Advanced APIs“.
2. Tělo dotazu (elements)
Sección titulada «2. El Cuerpo de la Consulta (elements)»Sekce elements dotazu odpovídá našim SQL klauzulím SELECT a FROM. Místo deklarace obecných sloupců pouze „projektujeme“ ty, které přinášejí analytickou hodnotu.
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) { } } }Architektonická výhoda (přejmenování sloupců)
Sección titulada «Ventaja Arquitectónica (Column Renaming)»Jak je vidět v kódu, na levé straně (column(MiNombre; "Nombre Original")) můžeme sloupce přejmenovat.
To nám umožňuje aplikovat principy správy dat již od zdroje. Databáze Navision mají názvy s mezerami, tečkami a zvláštními zápisy (Shortcut Dimension 1 Code). Přepsáním do podoby Cod_Dimension_1 šetříme kroky transformace v Power Query a dodáváme mnohem čistší analytický model týmu Business Intelligence.
3. Kontrolní seznam pro ověření API Query
Sección titulada «3. Checklist de Validación de API Query»- ✓ Routing: Explicitní definice
APIPublisher,APIGroupaAPIVersionbez lomítek/, aby se předešlo chybám při kompilaci. - ✓ Správa: Sloupce jsou ve zdroji řádně přejmenovány pomocí čistého zápisu Snake_Case, což usnadňuje modelování.
- ✓ Optimalizace: Včetně
SystemId(UUID), který slouží jako unikátní primární klíč v cílovém úložišti.

