Ir al contenido

ネイティブAPIの作成(クエリ)

ALでの高パフォーマンスなRESTful/OData V4エンドポイントの公開のためのメタデータ開発および構造化ガイド

0閲覧数

最適化されたデータアーキテクチャ(ELT)を構築するために、我々はAL言語を使用して独自のAPIを開発し、Queryオブジェクトを活用しています。

従来のAPIとは異なり、ALでは明示的なルートやコントローラーをプログラムする代わりに、ビジネス中央エンジンが自動的にRESTfulエンドポイント(OData V4)として公開する宣言的な構造を定義します。

すべての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';
}
  • QueryType = API;: この行がSQLクエリを外部からアクセス可能なHTTPウェブサービスに変換します。

  • ルーティング(Microsoftの制限付きパターン): 使用する最終的なURLは常にこの不変のパターンに従います: .../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}

    DevSecOpsノート: マイクロソフトは論理的な「サブフォルダー」を作成しようとするためにスラッシュ(/)の使用を禁止しています。そのため、階層が必要な場合は下線を含む命名規則を使用します(api_portelcore_1)。

  • EntityName および EntitySetName: 結果のJSONでオブジェクトがどのように名前付けされるかを定義します。EntitySetName(複数形)はODataのURLでの最終的なテーブル名になります。

  • QueryCategory: この値を割り当てることで、Excel、Power Automate、Power BIなどのツールにあるビジネス中央のネイティブコネクタが、このAPIを「Advanced APIs」フォルダー内でグラフィカルに見つけることを許可します。

クエリの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) { }
}
}

アーキテクチャの利点(列名の変更)

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)を含めることで、保存先での一意性を確保します。