네이티브 API 생성 (Query)
AL에서 고성능 RESTful/OData V4 엔드포인트 게시를 위한 메타데이터 개발 및 구조화 가이드.
최적화된 데이터 아키텍처(ELT)를 구축하기 위해, 우리는 AL 언어로 자체 API를 개발하고 Query 객체를 사용합니다.
명시적 경로와 컨트롤러를 프로그래밍하는 기존 API와 달리, AL에서는 선언적 구조를 정의하면 Business Central 엔진이 이를 자동으로 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';}-
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와 같은 도구의 내장된 Business Central 커넥터가 "고급 API" 폴더 내에서 시각적으로 API를 찾을 수 있습니다.
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) { } } }아키텍처적 이점 (Column Renaming)
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의 명시적 정의, 컴파일 실패를 방지하기 위한 슬래시 기호(/) 없음. - ✓ 거버넌스: 스네이크_케이스(clean) 표기법을 사용하여 원본에서 적절하게 컬럼 이름을 재정의하여 모델링을 용이하게 합니다.
- ✓ 최적화: 저장소 대상에서 유일한 기본 키로 작동하는
SystemId(UUID) 포함.

