Ir al contenido

Creación de APIs Nativas (Query)

Guía de desarrollo y estructuración de metadatos para la publicación de endpoints RESTful/OData V4 de alto rendimiento en AL.

0lectures

Para construir nuestra arquitectura de datos optimizada (ELT), nosotros desarrollamos nuestras propias APIs en lenguaje AL utilizando el objeto Query.

A diferència de les APIs tradicionals on programem rutes i controladors explícits, en AL definim una estructura declarativa que el motor de Business Central exposa automàticament com un endpoint RESTful (OData V4).

Todo objeto query de tipo API debe comenzar con una cabecera muy estricta que define su enrutamiento y categorización.

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;: Esta línea es la que convierte la consulta SQL en un Web Service HTTP accesible desde el exterior.

  • Enrutament (El Patró Restricte de Microsoft): La URL final que consumirem sempre segueix aquest patró immutable: .../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}

    Nota DevSecOps: Microsoft prohibe l'ús de barres diagonal / per intentar crear “subcarpetes” lògiques. Per això, si volem jerarquia, fem servir convencions de noms amb guions baixos (api_portelcore_1).

  • EntityName y EntitySetName: Definen cómo se nombran los objetos en el JSON resultante. EntitySetName (plural) será el nombre final de la tabla en la URL OData.

  • QueryCategory: Al asignar este valor, permitimos que el conector nativo de Business Central en herramientas como Excel, Power Automate o Power BI localice nuestra API de forma gráfica dentro de la carpeta “Advanced APIs”.

La sección elements de la consulta equivale a nuestra cláusula SELECT y FROM de SQL. En lugar de declarar columnas genéricas, nosotros “proyectamos” únicamente las que aportan valor analítico.

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

Avantatge Arquitectònic (Column Renaming)

Sección titulada «Ventaja Arquitectónica (Column Renaming)»

Como se aprecia en el código, en el lado izquierdo (column(MiNombre; "Nombre Original")) nosotros podemos rebautizar las columnas.

Això ens permet aplicar principis de Gobern de Dades des de l'origen. Les bases de dades de Navision tenen noms amb espais, punts i notacions estranyes (Shortcut Dimension 1 Code). En reescriure-les com Cod_Dimension_1, estalviem passos de transformació en Power Query i entreguem un model analític molt més net a l'equip de Business Intelligence.

  • ✓ Enrutamiento: Definición explícita de APIPublisher, APIGroup y APIVersion sin barras diagonales / para evitar fallos de compilación.
  • ✓ Gobierno: Columnas adecuadamente renombradas en origen usando notación Snake_Case limpia para facilitar el modelado.
  • ✓ Optimització: Inclusió del SystemId (UUID) per servir com a clau primària unívoca en l'emmagatzematge de destí.