將 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 的檔案中定義實體。

在 CLI 1.36.2 中,SQL 連接器類型(fabric-sqlanalytics、fabric-warehouse 和 fabric-sqldatabase)預設使用 應用程式 認證。 系統會以應用程式身分存取來源,目前為應用程式項目擁有者。 你可以明確選擇委派驗證,改用每位已登入的呼叫端的來源權限。 語義模型僅支援委派驗證。

預設的倉庫與語意模型配置如下:

connectors:
  - name: inventory
    type: fabric-warehouse
    config:
      workspaceId: "<workspace-id>"
      itemId: "<warehouse-item-id>"
    auth:
      type: application
    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 值。

選擇來源識別

Mode 來源權限 何時使用它
application 授予應用程式身份對來源項目的存取權及所需的 SQL 權限。 應用程式使用者仍然需要應用程式存取權限和實體權限。 SQL 連接器,讓應用程式控制對共享來源資料的存取。
delegated 每個呼叫者都需要存取原始項目並取得所請求操作的權限。 語意模型查詢需要呼叫者適用的模型權限,包括 Build。 每位使用者的來源授權,或任何語意模型連接器。

在 CLI 1.36.2 中,若要委派 SQL 存取,部署前先在 auth.type: delegated 中的該連接器上設定 rayfin/rayfin.yml。 其 connector add --help 會公開 --auth 的 CLI 版本可在建立時選取:

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

CLI 1.36.2 中沒有這個 --auth 旗標;請在該版本使用 YAML 設定。 若連接器類型支援該模式,則在支援該旗標時,僅接受 application 或 delegated。 不要為語意模型設定應用程式認證。

更改模式不會授予來源權限。 開發者登入與結構描述探索使用開發者的存取權限,並不能證明已部署的執行階段身分可存取來源。 現有的宣告不會自動遷移到新的預設狀態;請明確保留 auth.type。 重新加入連接器後,部署前請檢視已產生的模式。

當您發佈應用程式時,請檢視哪些相關項目需要每位使用者存取權限。 請參閱「分享 Fabric 應用程式」以了解分享工作流程及移除直接存取的影響。

設定實體連接器

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

測試已部署的應用程式,並與預期的應用程式使用者及執行階段來源身分一起測試。 對於應用程式認證,請驗證應用程式身份的來源權限;對於委託認證,則需驗證每位呼叫者的來源權限。