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.
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).
1. Estructura y Metadatos de Cabecera
Sección titulada «1. Estructura y Metadatos de Cabecera»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';}Análisis de los Parámetros Críticos
Sección titulada «Análisis de los Parámetros Críticos»-
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). -
EntityNameaEntitySetName: 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“.
2. Telo dotazu (elements)
Sección titulada «2. El Cuerpo de la Consulta (elements)»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) { } } }Ventaja Arquitectónica (Column Renaming)
Sección titulada «Ventaja Arquitectónica (Column Renaming)»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.
3. Checklist de Validación de API Query
Sección titulada «3. Checklist de Validación de API Query»- ✓ Smerovanie: Explicitná definícia
APIPublisher,APIGroupaAPIVersionbez 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.

