Ir al contenido

Erstellung nativer APIs (Query)

Leitfaden zur Entwicklung und Metadatenstrukturierung für die Bereitstellung hochperformanter RESTful/OData V4-Endpunkte in AL.

0Lesungen

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.

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

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

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.

  • ✓ Routing: Explizite Definition von APIPublisher, APIGroup und APIVersion ohne 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.