Tworzenie natywnych API (zapytania)
Przewodnik po rozwoju i strukturze metadanych do publikowania wysokowydajnych punktów końcowych RESTful/OData V4 w AL.
Aby zbudować naszą optymalną architekturę danych (ELT), rozwijamy własne API w języku AL z wykorzystaniem obiektu Query.
W przeciwieństwie do tradycyjnych API, gdzie programujemy explicitnie trasy i kontrolery, w AL definiujemy deklaratywną strukturę, którą silnik Business Central automatycznie exposes jako endpoint RESTful (OData V4).
1. Struktura i metadane nagłówka
Sección titulada «1. Estructura y Metadatos de Cabecera»Każdy obiekt query typu API musi zaczynać się od bardzo ściśle określonej nagłówki, która definiuje jego trasowanie i kategoryzację.
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';}Analiza parametrów krytycznych
Sección titulada «Análisis de los Parámetros Críticos»-
QueryType = API;: To jest linia, która przekształca zapytanie SQL w usługę sieciową HTTP dostępną z zewnątrz. -
Routing (wzorzec restrykcyjny Microsoft): Ostateczny adres URL, który będziemy konsumować, zawsze podąża za tym niezmiennym wzorcem:
.../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}Nota DevSecOps: Microsoft zabrania używania ukośników
/w celu tworzenia „podfolderów” logicznych. Dlatego jeśli chcemy hierarchii, używamy konwencji nazewniczych z podkreśleniami (api_portelcore_1). -
EntityNameiEntitySetName: Definiują one, jak nazywane są obiekty w wynikowym JSON.EntitySetName(liczba mnoga) będzie ostateczną nazwą tabeli w adresie URL OData. -
QueryCategory: Przypisując tę wartość, pozwalamy, aby natywny łącznik Business Central w narzędziach takich jak Excel, Power Automate lub Power BI mógł znaleźć naszą API w sposób graficzny w folderze „Advanced APIs”.
2. Treść zapytania (elements)
Sección titulada «2. El Cuerpo de la Consulta (elements)»Sekcja elements zapytania jest równoznaczna z naszą klauzulą SELECT i FROM w SQL. Zamiast deklarować ogólne kolumny, „projektujemy” tylko te, które zapewniają wartość analityczną.
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) { } } }Zaleta architektoniczna (zmiana nazwy kolumny)
Sección titulada «Ventaja Arquitectónica (Column Renaming)»Jak widać w kodzie, po lewej stronie (column(MiNombre; "Nombre Original")) możemy przemianowywać kolumny.
To pozwala nam stosować zasady Zarządzania Danymi od samego początku. Bazy danych Navision mają nazwy z spacjami, kropkami i niezwykłymi notacjami (Shortcut Dimension 1 Code). Przepisując je jako Cod_Dimension_1, oszczędzamy kroki transformacji w Power Query i dostarczamy model analityczny znacznie bardziej czysty zespołowi Business Intelligence.
3. Lista kontrolna walidacji zapytania API
Sección titulada «3. Checklist de Validación de API Query»- ✓ Route: Jawna definicja
APIPublisher,APIGroupiAPIVersionbez ukośników/, aby uniknąć błędów kompilacji. - ✓ Zarządzanie: Kolumny odpowiednio przemianowane w źródle, używając notacji Snake_Case w celu ułatwienia modelowania.
- ✓ Optymalizacja: Włączenie
SystemId(UUID), aby służyć jako unikalny klucz pierwotny w miejscu przechowywania.

