Ir al contenido

Creazione di API Native (Query)

Guida allo sviluppo e alla strutturazione dei metadati per la pubblicazione di endpoint RESTful/OData V4 ad alte prestazioni in AL.

0letture

Per costruire la nostra architettura dati ottimizzata (ELT), sviluppiamo le nostre API nel linguaggio AL utilizzando l'oggetto Query.

A differenza delle API tradizionali in cui programmiamo rotte e controller espliciti, in AL definiamo una struttura dichiarativa che il motore di Business Central espone automaticamente come endpoint RESTful (OData V4).

Ogni oggetto query di tipo API deve iniziare con un header molto rigoroso che definisce il suo routing e la sua categorizzazione.

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;: Questa riga è quella che converte la query SQL in un Web Service HTTP accessibile dall'esterno.

  • Instradamento (Il Pattern Restrittivo di Microsoft): L'URL finale che consumeremo segue sempre questo pattern immutabile: .../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}

    Nota DevSecOps: Microsoft vieta l'uso di slash / per tentare di creare “sottocartelle” logiche. Pertanto, se desideriamo una gerarchia, utilizziamo convenzioni di denominazione con underscore (api_portelcore_1).

  • EntityName e EntitySetName: Definiscono come vengono nominati gli oggetti nel JSON risultante. EntitySetName (plurale) sarà il nome finale della tabella nell'URL OData.

  • QueryCategory: Assegnando questo valore, permettiamo al connettore nativo di Business Central in strumenti come Excel, Power Automate o Power BI di individuare la nostra API in modo grafico all'interno della cartella “Advanced APIs”.

La sezione elements della query equivale alle nostre clausole SELECT e FROM di SQL. Invece di dichiarare colonne generiche, noi “proiettiamo” solo quelle che apportano valore analitico.

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

Vantaggio Architetturale (Column Renaming)

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

Come si può vedere nel codice, sul lato sinistro (column(MiNombre; "Nombre Original")) possiamo rinominare le colonne.

Questo ci permette di applicare i principi di Data Governance fin dall'origine. I database di Navision hanno nomi con spazi, punti e notazioni insolite (Shortcut Dimension 1 Code). Riscrivendoli come Cod_Dimension_1, risparmiamo passaggi di trasformazione in Power Query e forniamo un modello analitico molto più pulito al team di Business Intelligence.

3. Checklist di Validazione dell'API Query

Sección titulada «3. Checklist de Validación de API Query»
  • ✓ Routing: Definizione esplicita di APIPublisher, APIGroup e APIVersion senza barre diagonali / per evitare errori di compilazione.
  • ✓ Governance: Colonne rinominate correttamente alla sorgente utilizzando una notazione Snake_Case pulita per facilitare la modellazione.
  • ✓ Ottimizzazione: Inclusione di SystemId (UUID) per fungere da chiave primaria univoca nell'archiviazione di destinazione.