의미 체계 모델에 연결된 앱 만들기

데이터 앱 템플릿과 Fabric 의미 모델 커넥터를 사용하여 분석적 Fabric 앱을 구축하세요. 템플릿은 시각화, 서식, 데이터 그리드, 브라우저 검증 패턴을 제공합니다. 커넥터는 Fabric Apps 클라이언트를 통해 타입이 지정되고 위임된 의미 모델에 접근할 수 있도록 제공합니다.

템플릿을 사용하여 만든 앱은 다음과 같습니다.

Fabric 인증.
더 높은 품질의 DAX(데이터 분석 표현식) 생성 지침.
분석 애플리케이션을 위해 설계된 기업용 시각 구성 요소.
데이터 그리드, 테마, 서식, 브라우저 검증 패턴.

비고

현재 Rayfin CLI가 데이터 앱 템플릿을 사용하여 앱을 생성하는 지원되는 방법입니다.

데이터 앱 템플릿을 사용하는 이유는 무엇인가요?

이러한 내장 기능이 없으면, 코딩 에이전트는 매 세션마다 인증, DAX 생성, 시각화 설계를 처음부터 해결해야 합니다. 이로 인해 다음과 같은 결과가 발생할 수 있습니다:

더 많은 실패와 깨졌거나 비어 있는 시각적 요소.
차트 동작이 일관되지 않습니다.
개발 및 실행 중에 불필요한 DAX 쿼리가 발생합니다.

템플릿은 신뢰성을 높이고, 보고 모범 사례에 부합하는 더 일관된 시각적 자료를 제공하며, 쿼리 오버헤드를 줄이기 위해 재사용 가능한 패턴을 제공합니다. 커넥터는 의미 모델 구성과 런타임 접근을 표준화합니다.

사전 요구 사항

Node.js 20 이상.
Fabric에 대한 액세스.
참가자, 구성원 또는 관리자 권한이 있는 Fabric 작업 영역입니다.
테넌트에서 사용하도록 설정된 Fabric Apps 워크로드입니다. 첫 번째 Fabric 앱 만들기를 참조하세요.
의미 체계 모델 실행 쿼리 REST API 테넌트 설정이 활성화되었습니다.
Fabric 또는 Power BI 용량에 호스팅된 의미 모델에 권한을 구축하고 읽습니다.
시맨틱 모델의 작업 공간 ID와 항목 ID.

앱 만들기

데이터 앱 템플릿에서 프로젝트 만들기:

npm create @microsoft/rayfin@latest -- "<app-name>" --template dataapp --workspace <workspace-name>

<app-name> 및 <workspace-name>를 앱 및 Fabric 작업 공간의 이름으로 바꾸세요. 그 다음 새 프로젝트 폴더를 엽니다:

cd <app-name>

의미 모델 커넥터를 추가하세요

의미 모델 항목 ID를 모른다면, 작업 공간에 의미 모델을 나열하세요:

npx rayfin connector search --workspace-id <workspace-id> --type fabric-semanticmodel --json

의미론 모델을 커넥터로 추가하세요:

npx rayfin connector add --type fabric-semanticmodel --workspace-id <workspace-id> --item-id <semantic-model-item-id> --name salesModel --operations executeQuery

명령:

커넥터rayfin/rayfin.yml를 salesModel 에 추가합니다.
rayfin/connectors/salesModel/ 하위에 스키마를 생성합니다.
커넥터 패키지에 대해 버전 일치 npm install 명령을 출력합니다.

CLI에서 출력한 정확한 설치 명령을 실행하세요.

생성된 구성은 다음과 같은 예시와 유사합니다:

connectors:
  - name: salesModel
    type: fabric-semanticmodel
    config:
      workspaceId: "<workspace-id>"
      itemId: "<semantic-model-item-id>"
    auth:
      type: delegated
    version: "1"
    operations:
      - name: executeQuery

생성된 version 값을 유지하세요.

템플릿을 의미 모델에 연결합니다

템플릿에는 분석 구성 요소와 에이전트 가이드가 포함되어 있어 커넥터와 함께 재사용할 수 있습니다. 데이터 액세스 계층을 구성하여 ConnectorsRayfinClient를 생성하고 시맨틱 모델 런타임을 등록하도록 합니다:

Important

의미 모델 쿼리에는 커넥터 클라이언트를 사용하세요. 스캐폴드에 또 다른 의미 모델 클라이언트가 포함되어 있다면, 두 개의 데이터 접근 경로를 유지하는 대신 호출을 대체하세요.

import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
import {
  connectorConfig,
  type SalesModelSchema,
} from '../../rayfin/connectors/salesModel/schema.js';

type AppConnectorsSchema = {
  salesModel: SalesModelSchema;
};

export const client = new ConnectorsRayfinClient<
  Record<string, never>,
  Record<string, never>,
  AppConnectorsSchema
>(
  {
    baseUrl: '<app-api-url>',
    publishableKey: '<publishable-key>',
    authStorage: true,
    connectors: {
      salesModel: connectorConfig,
    },
  },
  {
    salesModel: fabricSemanticModel(),
  }
);

Fabric Apps 프로젝트에서 제공하는 API URL과 게시 가능한 키를 사용하세요. 템플릿의 기존 Fabric 로그인 흐름을 유지하세요.

커넥터를 통해 DAX를 제출하세요:

const result = await client.connectors.salesModel.executeQuery({
  query: 'EVALUATE TOPN(10, Sales)',
});

if (result.status === 'success') {
  console.log(result.table.columns, result.table.rows);
} else {
  console.error(result.error.category, result.error.message);
}

의미 모델 내에서 테이블로 대체하세요 Sales . 열과 행을 시각 자료에 전달하기 전에 반환된 상태를 확인하세요.

커넥터 구성 및 보안 지침에 대한 자세한 내용은 'Connect Fabric Apps to Fabric data'를 참조하세요.

코딩 에이전트로 앱을 만들어 보세요

이 비계에는 코딩 에이전트를 위한 지침과 기술이 포함되어 있습니다. 원하는 에이전트에서 프로젝트를 열고, 앱의 대상, 질문, 상호작용, 시각화 등을 설명하세요.

예를 들어, 다음을 할 수 있습니다:

Visual Studio Code에서 프로젝트를 열고, GitHub Copilot Chat 창을 열어보세요.
프로젝트에서 터미널을 연 다음 copilot를 실행하세요.

이 프롬프트를 출발점으로 사용하세요:

Build an analytical Fabric app that uses the existing salesModel connector.

Before editing:
1. Read the repository instructions and skills.
2. Inspect rayfin/connectors/salesModel/schema.ts and the template's data-access,
   visualization, data grid, formatting, and validation patterns.
3. Query the semantic model metadata before writing DAX. Don't guess table,
   measure, or column names.

Requirements:
- Use ConnectorsRayfinClient and fabricSemanticModel() for semantic model access.
- Call client.connectors.salesModel.executeQuery() for DAX queries.
- Keep the existing Fabric sign-in flow. Don't add credentials, access tokens,
  another authentication flow, or direct calls to the Execute Queries REST API.
- Reuse query results where practical, and bound large result sets.
- Apply semantic model format strings consistently to cards, charts, tooltips,
  and data grids.
- Include loading, empty, and error states.
- Use the template's browser-validation workflow at desktop and mobile sizes.

Give me a short implementation plan, make the changes, run the existing build,
and report the results.

템플릿 기능을 사용하세요

데이터 앱 템플릿에는 분석 애플리케이션을 위한 재사용 가능한 패턴이 포함되어 있습니다.

Fabric 앱은 표준 웹 애플리케이션이기 때문에 이러한 패턴 외에도 기능을 구현할 수 있습니다. 템플릿에 포함되지 않은 기능은 더 많은 맞춤형 엔지니어링과 검증이 필요할 수 있습니다.

시각적 요소

템플릿에는 교차 강조 및 다음과 같은 사전 구성 원시 요소가 포함되어 있습니다:

세로형, 가로형, 그룹형, 누적형 레이아웃을 포함한 막대 차트.
선택 가능한 마커가 있는 선표.
지역 지도.
산점도.
파이와 도넛 차트.
히트맵.
버블 차트.
폭포 차트.
KPI 호출용 단일 값 카드.
데이터 라벨이 있는 막대와 이중 축 선 차트 같은 레이어드 및 복합 시각 자료입니다.

연결된 의미 모델에 존재하는 필드와 측정을 사용하세요. 실패한 커넥터 쿼리를 모의 데이터로 대체하지 마세요.

코딩 에이전트에게 다른 시각적 자료를 만들어 달라고 요청할 수도 있습니다. 템플릿 프리미티브 없이 시각화하면 더 많은 반복과 검증이 필요할 수 있습니다.

데이터 그리드 기능

템플릿에는 다음과 같은 사전 설정된 기능을 갖춘 데이터 그리드가 포함되어 있습니다:

의미 모델 메타데이터에서 파생된 열 헤더.
형식 문자열을 통해 열별로 번호와 날짜 서식이 적용되었습니다.
분류 중.
오버플로우 처리를 지원하는 스크롤 가능한 행.
라이트와 어둠 테마 지원.
사용자 지정 셀 렌더러:
- 숫자 값을 위한 데이터 바.
- 불리언 표시기.
- 클릭 가능한 URL.
- 라이트박스 오버레이가 있는 이미지 셀.
- 이름과 역할이 한 열에 있는 다중 필드 셀.

다른 데이터 그리드 기능을 추가할 수도 있지만, 더 많은 맞춤형 엔지니어링이 필요할 수 있습니다.

테마 지정

코딩 에이전트에게 색상 팔레트, 코너 스타일, 폰트 등 브랜드나 스타일링 요구사항을 알려주세요. 템플릿은 공유 스타일을 하나의 중앙 위치에서 관리하므로 변경 사항이 카드, 버튼, 차트, 데이터 그리드 및 툴팁에 반영됩니다.

중앙 집중식 스타일링은 각 구성 요소를 따로 스타일링할 때 발생할 수 있는 색상 불일치, 일관성 없는 글꼴, 레이아웃 차이를 방지합니다.

문자열 서식 지정

결과 열당 한 번씩 서식을 정의하세요. 템플릿은 차트 축, 툴팁, 데이터 라벨, 카드, 데이터 그리드 셀 전반에 걸쳐 의미 모델 형식 문자열을 재사용할 수 있습니다.

예를 들어, 단일 형식 정의를 사용하면 해당 값이 나타나는 모든 곳에서 1500.5은 $1,500.50로, 0.25는 25%로 표시됩니다.

브라우저 검증

앱을 게시하기 전에 포함된 Playwright 브라우저 검증 워크플로우를 사용해 실제 브라우저에서 실행하고 다음을 확인하세요:

비주얼은 올바르게 렌더링됩니다.
차트는 잘려 나가거나 압축되지 않습니다.
텍스트는 읽기 쉽습니다.
데이터 그리드는 오버플로우를 처리합니다.
로딩, 빈 상태, 오류 상태 모두 사용할 수 있습니다.
필터, 교차 강조, 데이터 서식은 예상대로 작동합니다.
브라우저 콘솔에는 예상치 못한 오류가 없습니다.

이 워크플로우는 사용자가 레이아웃과 렌더링 문제를 보기 전에 발견합니다. 브라우저 검증은 프론트엔드 동작을 확인해 줍니다. 배포된 커넥터는 Fabric 앱과 의미 모델 모두에 접근할 수 있는 사용자와 별도로 테스트하세요.

앱을 배포하고 검증하세요

앱 및 커넥터 구성을 배포하세요:

npx rayfin up

Fabric 포털에서 배포된 앱을 열어보세요. 로그인하여 각 사용자 상호작용을 실행하고, 의미 모델과 중요한 결과를 비교하세요.

쿼리가 실패하면:

rayfin.yml에서 작업 영역 및 시맨틱 모델 항목 ID를 확인하세요.
Semantic Model Execute Queries REST API 테넌트 설정이 활성화되어 있는지 확인하세요.
사용자가 의미 모델에 대해 빌드 및 읽기 권한을 가지고 있는지 확인하세요.
DAX가 기존 테이블, 열, 측정을 참조하는지 확인하세요.
커넥터 결과의 오류 카테고리와 메시지를 확인하세요.
브라우저 콘솔에서 클라이언트 측 오류가 있는지 확인해 보세요.

피드백

이 페이지가 도움이 되었나요?

2026-09-29 에 마지막으로 업데이트됨