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やconnector searchコマンドで見つけることができます。

Fabricアイテムを見つける

connector searchを使ってワークスペース内の特定のタイプのアイテムをリストアップします。以下の例は倉庫の一覧です:

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

<workspace-id>を Fabric ワークスペース 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

コマンド:

connectors 内のトップレベルの rayfin/rayfin.yml セクションにコネクターを追加します。
rayfin/connectors/<connector-name>/の下でコネクタファイルを作成します。
必要なコネクタパッケージに対してバージョンマッチされた npm install コマンドを出力します。

CLIで出力された正確なインストールコマンドを実行してください。これによりコネクタパッケージがRayfinのCLIバージョンに合わせて調整されます。

Note

スキーマの発見は最善の努力です。発見が完了しなくてもコネクタを追加できます。 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、ウェアハウス、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();

列を明示的に選択し、返される行の数を制限します。

セマンティックモデルの場合、 executeQuery を含む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を意味論モデルのテーブルに置き換えてください。結果を使う前に返品状況を確認してください。

セキュアコネクターアクセス

以下の操作方法を組み合わせて使う:

コネクターの操作はアプリが必要とするアクションに合わせて rayfin.yml 限定しましょう。
どのサインインユーザーが各操作を実行できるかを制御するために、コネクタエンティティに宣言 @role を追加します。
ユーザーがエンティティの一部のみにアクセスする必要がある場合、行ポリシーやフィールドの包含・除外ルールを追加してください。
委任認証を有効にして、コネクターリクエストがサインインしたユーザーのアクセス権を使えるようにしてください。

クライアント側のTypeScriptタイプは開発の安全性を向上させますが、承認の境界ではありません。コネクタ構成およびエンティティの役割でアクセスを強制します。

コネクタをデプロイする

アプリとコネクタの設定を展開する:

npx rayfin up

Fabricアプリと接続されたアイテムの両方で期待される権限を持つユーザーで、デプロイ済みアプリをテストしてください。

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-09-29