Ir al contenido

Creación de APIs Nativas (Query)

Guía de desarrollo y estructuración de metadatos para la publicación de endpoints RESTful/OData V4 de alto rendimiento en AL.

0lecturas

Aby sme vytvorili našu optimalizovanú dátovú architektúru (ELT), my sme vyvinuli naše vlastné API v jazyku AL pomocou objektu Query.

A diferencia de las APIs tradicionales donde programamos rutas y controladores explícitos, en AL definimos una estructura declarativa que el motor de Business Central expone automáticamente como un endpoint RESTful (OData V4).

Každý objekt query typu API musí začať veľmi prísnou hlavičkou, ktorá definuje jeho smerovanie a kategorizáciu.

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 riadok je ten, ktorý konvertuje SQL dotaz na Web Service HTTP prístupný zvonku.

  • Trasovanie (obmedzený vzor spoločnosti Microsoft): Cieľová adresa URL vždy nasleduje tento nemenný vzor: .../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}

    Poznámka DevSecOps: Spoločnosť Microsoft zakazuje použitie lomítok / na pokus o vytvorenie logických „podpriečinkov“. Preto, ak chceme hierarchiu, používame konvencie názvov s podčiarkovníkom (api_portelcore_1).

  • EntityName a EntitySetName: Definujú, ako sa pomenujú objekty v výslednom JSON. EntitySetName (množné číslo) bude konečný názov tabuľky v adrese URL OData.

  • QueryCategory: Priradením tejto hodnoty umožňujeme, aby natívny konektor Business Central v nástrojoch ako Excel, Power Automate alebo Power BI lokalizoval naše API graficky v priečinku „Advanced APIs“.

Sekcia elements dotazu zodpovedá našej klauzule SELECT a FROM SQL. Namiesto deklarovania generických stĺpcov „projekujeme“ len tie, ktoré poskytujú analytickú 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) { }
}
}

Ako je zrejmé z kódu, na ľavej strane (column(MiNombre; "Nombre Original")) môžeme premenovať stĺpce.

To nám umožňuje aplikovať princípy Data Governance od začiatku. Databáze Navision majú názvy s medzerami, bodkami a zvláštnymi zápismi (Shortcut Dimension 1 Code). Ich prepisovaním na Cod_Dimension_1 ušetríme kroky transformácie v Power Query a dodáme analytickému tímu omnoho čistejší model.

  • ✓ Smerovanie: Explicitná definícia APIPublisher, APIGroup a APIVersion bez lomítok / na zabránenie zlyhaniu kompilácie.
  • ✓ Governance: Primerane premenované stĺpce na zdroji pomocou čistej notácie Snake_Case pre uľahčenie modelovania.
  • ✓ Optimalizácia: Zahrnutie SystemId (UUID) ako jednoznačného primárneho kľúča v cieľovom úložisku.