Création d'API natives (Query)
Guide de développement et de structuration des métadonnées pour la publication de points de terminaison RESTful/OData V4 haute performance en AL.
Pour construire notre architecture de données optimisée (ELT), nous développons nos propres API en langage AL en utilisant l'objet Query.
Contrairement aux APIs traditionnelles où nous programmons des routes et des contrôleurs explicites, en AL nous définissons une structure déclarative que le moteur de Business Central expose automatiquement comme un endpoint RESTful (OData V4).
1. Structure et Métadonnées d'En-tête
Sección titulada «1. Estructura y Metadatos de Cabecera»Tout objet query de type API doit commencer par un en-tête très strict qui définit son routage et sa catégorisation.
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 des Paramètres Critiques
Sección titulada «Análisis de los Parámetros Críticos»-
QueryType = API;: Cette ligne est celle qui convertit la requête SQL en un service web HTTP accessible de l'extérieur. -
Routage (le modèle restreint de Microsoft) : L'URL finale que nous consommerons suit toujours ce modèle immuable :
.../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}Note DevSecOps : Microsoft interdit l'utilisation de barres obliques
/pour tenter de créer des « sous-dossiers » logiques. C'est pourquoi, si nous voulons une hiérarchie, nous utilisons des conventions de nommage avec des tirets bas (api_portelcore_1). -
EntityNameetEntitySetName: Définissent la manière dont les objets sont nommés dans le JSON résultant.EntitySetName(au pluriel) sera le nom final de la table dans l'URL OData. -
QueryCategory: En assignant cette valeur, nous permettons au connecteur natif de Business Central dans des outils tels qu'Excel, Power Automate ou Power BI de localiser notre API de manière graphique dans le dossier « Advanced APIs »။
2. Le corps de la requête (elements)
Sección titulada «2. El Cuerpo de la Consulta (elements)»La section elements de la requête équivaut à nos clauses SELECT et FROM SQL. Au lieu de déclarer des colonnes génériques, nous « projetons » uniquement celles qui apportent une valeur analytique.
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) { } } }Avantage Architectural (Column Renaming)
Sección titulada «Ventaja Arquitectónica (Column Renaming)»Comme on peut le voir dans le code, du côté gauche (column(MiNombre; "Nombre Original")), nous pouvons renommer les colonnes.
Cela nous permet d'appliquer des principes de Gouvernance des données dès la source. Les bases de données Navision ont des noms avec des espaces, des points et des notations étranges (Shortcut Dimension 1 Code). En les réécrivant comme Cod_Dimension_1, nous économisons des étapes de transformation dans Power Query et fournissons un modèle analytique beaucoup plus propre à l'équipe de Business Intelligence.
3. Checklist de Validation d'API Query
Sección titulada «3. Checklist de Validación de API Query»- ✓ Routage : Définition explicite de
APIPublisher,APIGroupetAPIVersionsans barres obliques/pour éviter les erreurs de compilation. - ✓ Gouvernance : Colonnes correctement renommées à la source en utilisant une notation Snake_Case propre pour faciliter la modélisation.
- ✓ Optimisation : Inclusion du
SystemId(UUID) pour servir de clé primaire unique dans le stockage de destination.

