Ir al contenido

原生API创建(查询)

用于在AL中发布高性能RESTful/OData V4端点的开发和元数据结构指南。

0阅读

为了构建我们优化的数据架构(ELT),我们用 AL 语言开发了自有 API,使用的对象是 Query。

与传统API中我们编程显式路由和控制器不同,在AL中我们定义了一个声明式结构,该结构由Business Central引擎自动公开为RESTful(OData V4)端点。

每个 API 类型的 query 对象都必须以非常严格的标头开头,定义其路由和分类。

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;:这一行将 SQL 查询转换为可从外部访问的 HTTP Web 服务。

  • 路由(微软的严格模式):\n我们最终消费的 URL 始终遵循这一固定模式:\n.../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}

    DevSecOps 备注:Microsoft 禁止使用斜杠 / 来尝试创建逻辑上的“子文件夹”。因此,如果我们需要层级结构,可以使用带下划线的命名约定(api_portelcore_1)。

  • EntityName 和 EntitySetName:定义最终 JSON 中对象如何命名。EntitySetName(复数形式)将是 OData URL 中表的最终名称。

  • QueryCategory:通过设置此值,Excel、Power Automate 或 Power BI 等工具中的 Business Central 原生连接器即可在“Advanced APIs”文件夹中以图形方式找到我们的 API。

查询中的 elements 部分对应于 SQL 中的 SELECT 和 FROM 子句。我们不声明通用列,而只“投影”具有分析价值的列。

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

如代码所示,在左侧(column(MiNombre; "Nombre Original"))我们可以重命名列。

这使我们能够在源头应用数据治理原则。Navision 数据库的字段名包含空格、点和奇怪的符号(Shortcut Dimension 1 Code)。将它们重写为 Cod_Dimension_1 后,我们省去了 Power Query 中的转换步骤,并为商业智能团队提供更干净的分析模型。

  • ✓ 路由:显式定义 APIPublisher、APIGroup 和 APIVersion,不使用斜杠 /,以避免编译失败。
  • ✓ 治理:使用干净的< em >蛇形命名法</ em >在源头正确重命名列,以简化建模。
  • ✓ 优化:包含 SystemId(UUID),用作目标存储中的唯一主键。