將 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> 替換為您的 Fabric 工作區識別碼。若要搜尋其他支援項目，請更改 --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

命令：

將連接器加入 rayfin/rayfin.yml 中的頂層 connectors 區段。
在 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、倉庫及 SQL 資料庫連接器會以型別實體形式揭露選定的來源資料表。使用產生 metadata.json 的檔案只定義應用程式所需的表格和欄位。

以下範例假設所選倉庫包含一個 dbo.Order 名為 OrderID 的整數主鍵和名為 customerEmail的文字欄位的資料表。將這些說明性名稱和類型替換成你產生的元資料中的數值。

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 應用程式和已連接項目所需權限的使用者，測試已部署的應用程式。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-29