将 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 工作区 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

命令：

• 将连接器添加到 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();

明确选择列并限制返回行数。

对于语义模型，提交一个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 参考手册