Ir al contenido

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.

0vues

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

  • EntityName et EntitySetName : 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 »။

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) { }
}
}

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.

  • ✓ Routage : Définition explicite de APIPublisher, APIGroup et APIVersion sans 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.