Erstellung nativer APIs (Query)
Leitfaden zur Entwicklung und Metadatenstrukturierung für die Bereitstellung hochperformanter RESTful/OData V4-Endpunkte in AL.
Um unsere optimierte Datenarchitektur (ELT) aufzubauen, entwickeln wir unsere eigenen APIs in der Sprache AL unter Verwendung des Objekts Query.
Im Gegensatz zu herkömmlichen APIs, bei denen wir explizite Routen und Controller programmieren, definieren wir in AL eine deklarative Struktur, die die Business Central-Engine automatisch als RESTful-Endpunkt (OData V4) bereitstellt.
1. Struktur und Header-Metadaten
Sección titulada «1. Estructura y Metadatos de Cabecera»Jedes query-Objekt des Typs API muss mit einem sehr strengen Header beginnen, der sein Routing und seine Kategorisierung definiert.
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';}Analyse der kritischen Parameter
Sección titulada «Análisis de los Parámetros Críticos»-
QueryType = API;: Diese Zeile konvertiert die SQL-Abfrage in einen von außen erreichbaren HTTP-Webservice. -
Routing (Das strikte Muster von Microsoft): Die endgültige URL, die wir verwenden, folgt immer diesem unveränderlichen Muster:
.../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}DevSecOps-Hinweis: Microsoft verbietet die Verwendung von Schrägstrichen
/, um zu versuchen, logische „Unterordner“ zu erstellen. Wenn wir daher eine Hierarchie wünschen, verwenden wir Namenskonventionen mit Unterstrichen (api_portelcore_1]). -
EntityNameundEntitySetName: Definieren, wie die Objekte im resultierenden JSON benannt werden.EntitySetName(Plural) ist der endgültige Tabellenname in der OData-URL. -
QueryCategory: Durch die Zuweisung dieses Wertes ermöglichen wir es dem nativen Business Central-Connector in Tools wie Excel, Power Automate oder Power BI, unsere API grafisch innerhalb des Ordners „Advanced APIs“ zu finden.
2. Der Abfragekörper (elements)
Sección titulada «2. El Cuerpo de la Consulta (elements)»Der Abschnitt elements der Abfrage entspricht unseren SQL-Klauseln SELECT und FROM. Anstatt generische Spalten zu deklarieren, „projizieren“ wir nur diejenigen, die einen analytischen Mehrwert bieten.
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) { } } }Architektonischer Vorteil (Column Renaming)
Sección titulada «Ventaja Arquitectónica (Column Renaming)»Wie im Code ersichtlich, können wir auf der linken Seite (column(MiNombre; "Nombre Original")) die Spalten umbenennen.
Dies ermöglicht es uns, Prinzipien der Data Governance von der Quelle aus anzuwenden. Die Navision-Datenbanken haben Namen mit Leerzeichen, Punkten und ungewöhnlichen Notationen (Shortcut Dimension 1 Code). Durch das Umschreiben als Cod_Dimension_1 sparen wir Transformationsschritte in Power Query und liefern dem Business-Intelligence-Team ein wesentlich saubereres Analysemodell.
3. API-Query-Validierungs-Checkliste
Sección titulada «3. Checklist de Validación de API Query»- ✓ Routing: Explizite Definition von
APIPublisher,APIGroupundAPIVersionohne Schrägstriche/, um Kompilierungsfehler zu vermeiden. - ✓ Governance: Spalten wurden an der Quelle unter Verwendung einer sauberen Snake_Case-Notation ordnungsgemäß umbenannt, um die Modellierung zu erleichtern.
- ✓ Optimierung: Einbeziehung der
SystemId(UUID), um als eindeutiger Primärschlüssel im Zielspeicher zu dienen.

