Создание собственных API (запрос)
Руководство по разработке и структурированию метаданных для публикации высокопроизводительных RESTful/OData V4-Endpoints на языке AL.
Чтобы построить нашу оптимизированную архитектуру данных (ELT), мы разработали свои собственные API на языке AL, используя объект Query.
В отличие от традиционных API, где мы программируем явные маршруты и контроллеры, в AL мы определяем декларативную структуру, которую движок Business Central автоматически exposes как RESTful-ендпоинт (OData V4).
1. Структура и метаданные заголовка
Sección titulada «1. Estructura y Metadatos de Cabecera»Любой объект query типа API должен начинаться с очень строгого заголовка, который определяет его маршрутизацию и категоризацию.
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';}Анализ критических параметров
Sección titulada «Análisis de los Parámetros Críticos»-
QueryType = API;: Эта строка преобразует SQL-запрос в веб-сервис HTTP, доступный извне. -
Маршрутизация (строгий шаблон Microsoft): Окончательный URL, который мы будем использовать, всегда следует этому неизменяемому шаблону:
.../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}Примечание DevSecOps: Microsoft запрещает использование косых черт
/для попытки создания логических "подпапок". Поэтому, если мы хотим иерархию, мы используем конвенции именования с подчеркиваниями (api_portelcore_1). -
EntityNameиEntitySetName: Определяют, как называются объекты в результирующем JSON.EntitySetName(множественное число) будет окончательным именем таблицы в URL OData. -
QueryCategory: Присвоив это значение, мы позволяем родному соединителю Business Central в таких инструментах, как Excel, Power Automate или Power BI, найти наш API графически внутри папки "Advanced APIs".
2. Тело запроса (elements)
Sección titulada «2. El Cuerpo de la Consulta (elements)»Раздел elements запроса эквивалентен нашей клаузе SELECT и FROM SQL. Вместо объявления общих столбцов мы "проектируем" только те, которые приносят аналитическую ценность.
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) { } } }Архитектурное преимущество (переименование столбцов)
Sección titulada «Ventaja Arquitectónica (Column Renaming)»Как видно в коде, в левой части (column(MiNombre; "Nombre Original")) мы можем переименовать столбцы.
Это позволяет нам применять принципы управления данными с самого начала. Базы данных Navision имеют имена со пробелами, точками и странными обозначениями (Shortcut Dimension 1 Code). Переименовывая их как Cod_Dimension_1, мы экономим шаги преобразования в Power Query и передаем команде бизнес-интеллекта гораздо более чистую аналитическую модель.
3. Контрольный список проверки API-запроса
Sección titulada «3. Checklist de Validación de API Query»- ✓ Маршрутизация: Явное определение
APIPublisher,APIGroupиAPIVersionбез косых черт/для предотвращения ошибок компиляции. - ✓ Управление: Столбцы правильно переименованы в источнике с использованием чистой нотации Snake_Case для облегчения моделирования.
- ✓ Оптимизация: Включение
SystemId(UUID) для служения в качестве уникального первичного ключа в целевом хранилище.

