使用数据应用模板搭配 Fabric 语义模型连接器，构建分析型 Fabric 应用。 该模板提供可视化、格式化、数据网格和浏览器验证模式。 该连接器通过 Fabric Apps 客户端提供对语义模型的类型化委托访问。
开箱即用，使用模板创建的应用包括：
- Fabric 身份验证。
- 更高质量的 DAX（数据分析表达式）生成指南
- 为分析应用设计的企业级可视化组件。
- 数据网格、主题、格式和浏览器验证模式。
注释
目前，Rayfin CLI 是使用数据应用模板创建应用的官方支持方式。
为何使用数据应用模板？
没有这些内置功能，编码代理必须在每个会话中从零开始解决认证、DAX生成和可视化设计。 这可能导致：
- 更多的失败和破碎或空洞的画面。
- 图表行为不一致。
- 开发和运行期间的不必要 DAX 查询。
该模板提供了可复用的模式，提升可靠性，产生更连贯且符合报告最佳实践的可视化，并减少查询开销。 该连接器标准化语义模型配置和运行时访问。
先决条件
- Node.js 20 或更高版本。
- 访问Fabric。
- 具有参与者、成员或管理员权限的Fabric工作区。
- 已在你的租户中启用的 Fabric 应用工作负载。 参见“创建你的第一个 Fabric 应用”。
- 语义模型执行查询 REST API 租户设置已启用。
- 在托管于 Fabric 或 Power BI 容量上的语义模型上构建和读取权限。
- 语义模型的工作区ID和项目ID。
创建应用
从数据应用模板创建项目：
npm create @microsoft/rayfin@latest -- "<app-name>" --template dataapp --workspace <workspace-name>
用你的应用和 Fabric 工作区的名称替换 <app-name> 和 <workspace-name>。 然后打开新的项目文件夹：
cd <app-name>
添加语义模型连接器
如果你不知道语义模型的项目ID，可以在工作区中列出语义模型：
npx rayfin connector search --workspace-id <workspace-id> --type fabric-semanticmodel --json
将语义模型作为连接器添加：
npx rayfin connector add --type fabric-semanticmodel --workspace-id <workspace-id> --item-id <semantic-model-item-id> --name salesModel --operations executeQuery
命令：
- 将连接器
rayfin/rayfin.yml添加到salesModel。 - 在
rayfin/connectors/salesModel/下创建其架构。 - 输出适用于连接器软件包的版本匹配的
npm install命令。
运行 CLI 输出的原样安装命令。
生成的配置类似于以下示例：
connectors:
- name: salesModel
type: fabric-semanticmodel
config:
workspaceId: "<workspace-id>"
itemId: "<semantic-model-item-id>"
auth:
type: delegated
version: "1"
operations:
- name: executeQuery
保留生成的 version 值。
将模板连接到语义模型
该模板包含可与连接器重复使用的分析组件和代理说明。 将其数据访问层配置为创建 ConnectorsRayfinClient 并注册语义模型运行时：
Important
使用连接器客户端进行语义模型查询。 如果支架包含另一个语义模型客户端，则替换对其的调用，而不是维护两个数据访问路径。
import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
import {
connectorConfig,
type SalesModelSchema,
} from '../../rayfin/connectors/salesModel/schema.js';
type AppConnectorsSchema = {
salesModel: SalesModelSchema;
};
export const client = new ConnectorsRayfinClient<
Record<string, never>,
Record<string, never>,
AppConnectorsSchema
>(
{
baseUrl: '<app-api-url>',
publishableKey: '<publishable-key>',
authStorage: true,
connectors: {
salesModel: connectorConfig,
},
},
{
salesModel: fabricSemanticModel(),
}
);
使用你 Fabric Apps 项目中的 API URL 和可发布密钥。 保持模板现有的 Fabric 登录流程。
通过连接器提交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 。 在将列和行传递给可视化之前，先检查返回状态。
有关更多连接器配置和安全指导，请参见“将 Fabric 应用连接到 Fabric 数据”。
用编码代理构建应用
该脚手架包含供编程代理使用的指令和技能。 在你偏好的代理中打开项目，描述受众、问题、互动和应用的可视化内容。
例如，您可以：
- 在 Visual Studio Code 中打开该项目，然后打开 GitHub 的 Copilot 对话助手 面板。
- 在项目中打开一个终端，然后运行
copilot。
请以此提示作为起点：
Build an analytical Fabric app that uses the existing salesModel connector.
Before editing:
1. Read the repository instructions and skills.
2. Inspect rayfin/connectors/salesModel/schema.ts and the template's data-access,
visualization, data grid, formatting, and validation patterns.
3. Query the semantic model metadata before writing DAX. Don't guess table,
measure, or column names.
Requirements:
- Use ConnectorsRayfinClient and fabricSemanticModel() for semantic model access.
- Call client.connectors.salesModel.executeQuery() for DAX queries.
- Keep the existing Fabric sign-in flow. Don't add credentials, access tokens,
another authentication flow, or direct calls to the Execute Queries REST API.
- Reuse query results where practical, and bound large result sets.
- Apply semantic model format strings consistently to cards, charts, tooltips,
and data grids.
- Include loading, empty, and error states.
- Use the template's browser-validation workflow at desktop and mobile sizes.
Give me a short implementation plan, make the changes, run the existing build,
and report the results.
使用模板功能
数据应用模板包含可重复使用的分析应用模式。
Fabric 应用是标准的网页应用，所以你可以实现这些模式之外的功能。 模板中没有包含的功能可能需要更多的定制工程和验证。
视觉效果
该模板包含交叉高亮和预配置的基元：
- 柱状图，包括垂直、水平、分组和堆叠布局。
- 折线图，带有可选标记。
- 区域图。
- 散点图。
- 派和甜甜圈图表。
- 热力图。
- 气泡图。
- 瀑布图。
- 用于KPI调用的单一值卡片。
- 分层和复合视觉效果，如带数据标签的条形图和双轴折线图。
使用连接语义模型中存在的字段和度量。 不要用模拟数据替换失败的连接器查询。
你可以让你的编码代理生成其他视觉效果。 没有模板原语的可视化可能需要更多的迭代和验证。
数据网格功能
该模板包含一个具有以下预配置功能的数据网格：
- 列头部源自语义模型元数据。
- 通过格式字符串为每列应用数字和日期格式设置。
- 排序。
- 可滚动的行，并支持溢出处理。
- 支持浅色和深色主题。
- 自定义单元格渲染器：
- 用于数值的数据条。
- 布尔指示器。
- 可点击的网址。
- 带有灯箱覆盖层的图片单元。
- 包含多个字段的单元格，例如在同一列中显示名称和角色。
你可以添加其他数据网格功能，但可能需要更多定制工程。
主题
给你的编码代理提供品牌或造型需求，比如色彩搭配、角落样式或字体。 该模板将共享样式集中在一个中心位置，以便所做的更改能够同步到卡片、按钮、图表、数据网格和工具提示。
集中式样式避免了颜色不匹配、字体不一致以及各组件单独样式时可能出现的布局差异。
格式字符串
为每个结果列仅定义一次格式。 该模板可以在图表轴、工具提示、数据标签、卡片和数据网格单元格间重用语义模型格式字符串。
例如，单个格式定义会使 1500.5 始终显示为 $1,500.50，并使 0.25 始终显示为 25%，无论这些值出现在何处。
浏览器验证
发布应用前，使用附带的Playwright浏览器验证流程，在真实浏览器中打开并检查：
- 画面渲染正常。
- 图表不会被截断或压缩。
- 文字是可读的。
- 数据网格处理溢出。
- 加载状态、空状态和错误状态都是可用的。
- 筛选、交叉高亮和数据格式设置均按预期工作。
- 浏览器控制台没有出现任何意外错误。
该工作流程能在用户看到之前发现布局和渲染问题。 浏览器验证确认了前端行为。 分别与同时访问 Fabric 应用和语义模型的用户测试已部署的连接器。
部署并验证应用
部署应用和连接器配置：
npx rayfin up
从Fabric门户打开已部署的应用。 登录，运行每次用户交互，并与语义模型对比重要结果。
如果查询失败：
- 确认
rayfin.yml中的工作区和语义模型项 ID。 - 确认“语义模型执行查询”REST API 租户设置已启用。
- 确认用户对语义模型拥有构建和读取权限。
- 验证 DAX 是否引用了现有的表、列和度量值。
- 检查连接器结果的错误类别和提示。
- 检查浏览器控制台是否有客户端错误。