Ir al contenido

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.

0čtení

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).

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';
}
  • 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).

  • EntityName a EntitySetName: 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“.

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, APIGroup a APIVersion bez 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.