Ir al contenido

Создание собственных API (запрос)

Руководство по разработке и структурированию метаданных для публикации высокопроизводительных RESTful/OData V4-Endpoints на языке AL.

0просмотры

Чтобы построить нашу оптимизированную архитектуру данных (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".

Раздел 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) для служения в качестве уникального первичного ключа в целевом хранилище.