ネイティブAPIの作成(クエリ)
ALでの高パフォーマンスなRESTful/OData V4エンドポイントの公開のためのメタデータ開発および構造化ガイド
最適化されたデータアーキテクチャ(ELT)を構築するために、我々はAL言語を使用して独自のAPIを開発し、Queryオブジェクトを活用しています。
従来のAPIとは異なり、ALでは明示的なルートやコントローラーをプログラムする代わりに、ビジネス中央エンジンが自動的にRESTfulエンドポイント(OData V4)として公開する宣言的な構造を定義します。
1. ヘッダー構造とメタデータ
Sección titulada «1. Estructura y Metadatos de Cabecera»すべての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」フォルダー内でグラフィカルに見つけることを許可します。
2. クエリの本文(elements)
Sección titulada «2. El Cuerpo de la Consulta (elements)»クエリの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)を含めることで、保存先での一意性を確保します。

