Fabric 앱을 Fabric 데이터에 연결하기

커넥터는 Fabric 앱이 다른 Fabric 항목의 데이터에 형식이 지정된 액세스를 제공하도록 합니다. 별도의 데이터 서비스를 구성하지 않고도 레이크하우스, 웨어하우스, Fabric의 SQL 데이터베이스, 또는 의미 모델을 조회할 수 있는 커넥터를 사용할 수 있습니다.

지원되는 커넥터

Fabric 아이템과 앱에 필요한 연산에 따라 커넥터를 선택하세요:

직물 항목	커넥터 유형	지원되는 작업
Lakehouse SQL 분석 엔드포인트	fabric-sqlanalytics	read
warehouse	fabric-warehouse	read, create, update 및 delete
Fabric 내의 SQL 데이터베이스	fabric-sqldatabase	read, create, update 및 delete
의미 체계 모델	fabric-semanticmodel	executeQuery

Fabric 커넥터에서 웨어하우스 및 SQL 데이터베이스를 운영할 때는 앱에 필요한 작업만 구성하세요. 레이크하우스 커넥터는 읽기 전용입니다.

사전 요구 사항

• npm create @microsoft/rayfin@latest 사용하여 만들거나 npx rayfin init 사용하여 초기화된 Fabric Apps 프로젝트입니다.
• 연결하려는 아이템이 포함된 Fabric 작업 공간입니다.
• 작업 공간과 소스 항목에 접근할 수 있는 권한.
• 작업 공간 ID와 아이템 ID는 Fabric URL이나 커넥터 검색 명령어를 사용해 찾을 수 있습니다.

Fabric 아이템을 찾아보세요

작업 공간 내 특정 유형의 항목을 나열하는 데 사용 connector search 하세요. 다음 예시는 창고를 나열합니다:

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

<workspace-id>를 패브릭 작업 영역 ID로 바꾸세요. 다른 지원 항목을 찾으려면 --type 값을 변경하세요. 이름 필터도 추가할 수 있습니다:

npx rayfin connector search "sales" --workspace-id <workspace-id> --type fabric-warehouse --json

검색 결과에서 아이템 ID를 복사하세요.

커넥터 추가

Fabric Apps 프로젝트의 루트에서 실행하세요connector add. 다음 예시는 읽기 전용 창고 커넥터 inventory를 추가합니다:

npx rayfin connector add --type fabric-warehouse --workspace-id <workspace-id> --item-id <warehouse-item-id> --name inventory --operations read

다른 Fabric 항목에 대해서는 해당 커넥터 유형과 연산을 사용하세요:

# Lakehouse SQL analytics endpoint
npx rayfin connector add --type fabric-sqlanalytics --workspace-id <workspace-id> --item-id <lakehouse-item-id> --name analytics --operations read

# SQL database in Fabric
npx rayfin connector add --type fabric-sqldatabase --workspace-id <workspace-id> --item-id <sql-database-item-id> --name operational --operations read

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

명령:

• 커넥터를 최상위 섹션 connectorsrayfin/rayfin.yml에 추가합니다.
• rayfin/connectors/<connector-name>/ 아래에 커넥터 파일을 생성합니다.
• 필요한 커넥터 패키지에 대해 버전 매칭 npm install 명령을 출력합니다.

CLI에서 출력한 정확한 설치 명령을 실행하세요. 이렇게 하면 커넥터 패키지가 Rayfin CLI 버전과 정렬되도록 유지됩니다.

메모

스키마 발견은 최선의 노력입니다. 탐색이 완료되지 않아도 커넥터를 추가할 수 있습니다. CLI에 발견 경고가 표시되면, 생성된 metadata.json 파일에서 엔티티를 정의하기 전에 이를 해결하세요.

생성된 구성은 위임된 인증을 사용합니다. 웨어하우스 및 의미 모델 구성은 다음과 같은 예시와 유사합니다:

connectors:
  - name: inventory
    type: fabric-warehouse
    config:
      workspaceId: "<workspace-id>"
      itemId: "<warehouse-item-id>"
    auth:
      type: delegated
    operations:
      - name: read

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

CLI가 생성하는 의미 모델 version 값을 유지하세요.

엔티티 커넥터 구성

Lakehouse, warehouse, SQL 데이터베이스 커넥터는 선택된 소스 테이블을 타입이 부여된 엔티티로 노출합니다. 생성된 metadata.json 파일을 사용해 앱에 필요한 테이블과 열만 정의하세요.

다음 예시는 선택된 웨어하우스에 정수 기본 키 OrderID 가 있고 텍스트 열customerEmail이 있는 테이블이 있다고 dbo.Order 가정합니다. 이 예시적인 이름과 타입을 생성한 메타데이터의 값으로 대체하세요.

Important

열 이름만으로는 기본 키를 추론하지 마세요. 소스 테이블에 키가 없으면 primaryKey를 생략하세요. 키리스 엔티티는 키별로 행을 처리하는 연산을 지원하지 않습니다.

법인을 생성하세요:

// rayfin/connectors/inventory/Order.ts
import { entity, int, text, role } from '@microsoft/rayfin-core';
import { Source } from '@microsoft/rayfin-connectors';

@role('authenticated', ['read'])
@entity()
export class Order extends Source({
  schema: 'dbo',
  table: 'Order',
  primaryKey: ['orderId'],
}) {
  @int({ column: 'OrderID' }) orderId!: number;
  @text() customerEmail!: string;
}

그 다음 커넥터 스키마에 엔티티를 등록합니다:

// rayfin/connectors/inventory/schema.ts
import type { GraphQLBackedConnector } from '@microsoft/rayfin-connector-fabric-graphql';
import type { ConnectorConfig } from '@microsoft/rayfin-connectors';
import { Order } from './Order.js';

export { Order } from './Order.js';

export const connectorConfig = {
  connector: 'fabric-warehouse',
  operations: ['read'],
  entities: { Order },
} as const satisfies ConnectorConfig;

export type InventorySchema = GraphQLBackedConnector<
  { Order: typeof Order },
  typeof connectorConfig
>;

커넥터 이름, 스키마 속성, 클라이언트 구성 이름은 일관되게 유지하세요.

커넥터 클라이언트 구성

ConnectorsRayfinClient에 커넥터 스키마를 추가합니다. 의미 모델 커넥터에도 fabricSemanticModel() 런타임이 필요합니다:

// src/lib/connectors.ts
import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';

import {
  connectorConfig as inventoryConfig,
  type InventorySchema,
} from '../../rayfin/connectors/inventory/schema.js';
import {
  connectorConfig as salesModelConfig,
  type SalesModelSchema,
} from '../../rayfin/connectors/salesModel/schema.js';

type AppConnectorsSchema = {
  inventory: InventorySchema;
  salesModel: SalesModelSchema;
};

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

Fabric Apps 프로젝트에서 제공하는 API URL과 게시 가능한 키를 사용하세요. 앱의 기존 로그인 흐름을 유지하세요. 클라이언트를 생성하는 것은 사용자가 로그인하지 않습니다.

연결 데이터 조회

사용자가 로그인한 후, 엔터티 커넥터의 이름과 엔티티를 통해 접근하세요:

const orders = await client.connectors.inventory.Order
  .select(['orderId', 'customerEmail'])
  .first(20)
  .execute();

열을 명시적으로 선택하고 반환 행 수를 제한하세요.

의미론 모델의 경우, DAX 쿼리를 제출하여 다음을 수행합니다 executeQuery:

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 . 결과를 사용하기 전에 반품 상태를 확인하세요.

보안 커넥터 접근

다음 컨트롤을 함께 사용하세요:

• 커넥터의 동작 rayfin.yml 을 앱이 필요로 하는 동작으로 제한하세요.
• 커넥터 엔티티에 선언을 추가 @role 하여 로그인한 사용자가 각 작업을 수행할 수 있음을 제어합니다.
• 사용자가 엔터티의 일부만 접근해야 할 경우 행 정책 또는 필드 포함 및 제외 규칙을 추가하세요.
• 위임 인증을 활성화하여 커넥터 요청이 로그인한 사용자의 접근 권한을 사용하도록 하세요.

클라이언트 측 TypeScript 타입은 개발 보안을 향상시키지만, 권한 부여 경계는 아닙니다. 커넥터 구성 및 엔터티 역할에서 접근 권한을 강제합니다.

커넥터 배포

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

npx rayfin up

배포된 앱을 Fabric 앱과 연결된 항목 모두에 대해 예상 권한을 가진 사용자와 테스트해 보세요.

관련 콘텐츠

• 의미론 모델에 연결된 앱을 만드세요
• 데이터 모델 정의
• 데이터 권한 정의
• Fabric 앱의 인증
• Fabric 앱을 Fabric에 배포
• Rayfin CLI 참조