Ir al contenido

Tworzenie natywnych API (zapytania)

Przewodnik po rozwoju i strukturze metadanych do publikowania wysokowydajnych punktów końcowych RESTful/OData V4 w AL.

0odwiedzin

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

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

  • EntityName i EntitySetName: 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”.

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