什么是 Fabric Apps?

Fabric Apps 基于 Rayfin SDK 构建,使开发者能够通过统一的开发流程在 Fabric 上创建数据驱动应用。 开发人员在 TypeScript 中定义数据模型,Fabric应用自动生成 API、处理身份验证、提供托管并与Fabric服务集成。 Fabric应用支持用于数据模型、客户端代码和应用程序逻辑的 TypeScript。 在 Rayfin SDK 概述中了解详细信息。

主要功能

Fabric应用提供这些功能:

  • 数据模型到 API——使用 @text()、@uuid()、@entity() 和其他装饰器来装饰 TypeScript 类。 Fabric 应用会自动生成数据库架构和 GraphQL 端点。
  • Fabric 数据连接器——添加对湖屋、仓库、Fabric 中的 SQL 数据库或语义模型的类型访问。
  • 文件存储——定义类型文件夹,使用认证策略控制访问,并在 Fabric 中上传、下载、列出和删除文件。 参见 存储和管理文件。
  • 类型安全客户端 ——客户端 SDK 在查询和变更到达后端前进行验证,并在开发过程中发现错误。
  • 内置认证 ——包含会话管理、令牌处理和认证流程。 为已部署的应用程序配置 Fabric SSO,或在本地开发期间使用电子邮件和密码。
  • 静态托管 ——将你的前端应用与后端API一同构建和提供。 要求具有对 Fabric 项目的访问权限,或允许匿名访问托管资产。
  • 本地开发——用 Docker 本地运行全栈以实现快速迭代,准备好后部署到 Fabric。 搭建项目、使用GitHub Copilot进行开发,并使用 Rayfin CLI 部署到Fabric。

支持的区域

Fabric应用尚未在所有区域提供。 有关详细信息,请参阅Fabric应用支持的区域。

先决条件

许可证与工作空间

工作区要求取决于您应用的许可选项:

  • 对于容量支持应用,请为工作区分配 Fabric 容量或活动中的 Fabric 试用容量。 应用服务会消耗该容量中的容量单位。
  • 为了获得 Power BI Pro 体验,请使用 Pro 工作区。 您无需分配 Fabric 容量。 适用 Power BI Pro 的限制。

有关许可要求,请参阅“为 Fabric 应用选择许可选项”。 要使用任一选项创建应用,请点击 “从门户创建应用”。

租户管理员设置

Fabric租户管理员必须先启用Fabric应用工作负荷,然后用户才能创建项。

  1. 登录到 Fabric 管理门户。
  2. 导航到 租户设置。
  3. 在 Fabric 应用下,将设置切换为“启用”。
  4. 选择是针对整个组织还是特定安全组启用。
  5. 选择应用。

更改可能需要几分钟才能传播。

工作原理

Fabric应用在Fabric中作为托管服务运行,其中包含定义后端的服务套件,例如应用托管、数据库、GraphQL API 和身份验证。 Fabric 负责托管、网络和扩展。 身份验证以独占方式使用 Fabric SSO(Microsoft Entra ID单一登录),部署后没有其他身份验证提供程序可用。

显示Fabric应用托管服务和组件的截图。

使用 rayfin up 部署应用程序时,Fabric基于 rayfin.yml 配置创建子服务。 这些子服务在 Fabric 门户的 Fabric 应用下显示为子项。

子服务 它提供的内容 门户功能
Fabric中的SQL数据库 一种托管式 SQL 数据库,其架构通过 TypeScript 数据模型装饰器进行应用。 查看数据库,使用查询编辑器运行查询,复制连接字符串。 数据库在门户中为只读——架构变更必须通过您的代码经由 rayfin up 进行。
身份验证 使用 Microsoft Entra ID (SSO) 的 Fabric 代理身份验证 用户通过其现有Fabric标识登录。 在 SQL 数据库中查看经过身份验证的用户。
静态内容 你构建的前端资源(HTML、CSS、JS),通过 Fabric Apps 托管 URL 提供。 配置受保护访问或允许匿名访问资产。 查看托管 URL。 资源会在每次部署时更新。

应用后端 URL

每个Fabric应用都有一个终结点,提供对所有服务的访问:

https://<your-app>-app.rayfin.windows.net/

端点包括以下服务路径:

路径 Service
/api/graphql 数据 API(GraphQL)— 由 RayfinClient 用于读取和写入操作
/auth 身份验证服务

对于文件操作,可以使用 存储客户端SDK。

Fabric门户中的管理

部署后,可以直接在Fabric门户中管理Fabric应用。

Fabric管理员可以暂时阻止其他用户加载你的应用。 作为应用所有者,你仍然可以打开应用。 更多信息请参见“屏蔽与解除屏蔽”Fabric应用。

如果你拥有或使用被屏蔽的应用,请参见“App 被屏蔽时会发生什么”。

查看项属性

在门户中打开Fabric应用以查看:

  • 应用后端 URL —— 该端点用于应用所使用的所有后端服务。
  • 应用URL ——你静态内容托管的URL。 访问权限取决于 assetAccess 中的 rayfin.yml 设置。

管理子项

选择 Fabric 应用即可查看其子服务:

  • Fabric 中的 SQL 数据库——在 Fabric 中打开 SQL 数据库以查看对象浏览器。 您可以对您的数据执行读取查询。 在你配置的数据包中进行架构更改(packages/data 在默认的通用应用中,或 rayfin/data 在平面模板中),而不是直接在数据库中。 手动更改架构可能会引发冲突并导致应用无法正常运行。

项目权限

工作区角色不会取代项级权限。 若要与组织中的某人共享应用,他们需要 运行和交互 权限(读取和执行),以运行应用并调用后端 API。

许可 它允许的内容
运行并与其交互 (默认) 打开并使用已部署的应用程序。 默认情况下,所有工作区成员都会收到此级别。
编辑(写) 修改Fabric应用 — 使用 rayfin up 部署代码、应用架构更改、更新设置和管理子服务。
重新共享 向其他用户授予对Fabric应用的访问权限。 需要在该工作区中具有管理员角色。

详细了解 工作区角色。

有关共享工作流、相关项目权限和访问请求,请参阅共享 Fabric 应用。

使用 Rayfin CLI 进行开发

CLI 搭建新项目、启动本地基础结构、同步架构更改并部署到Fabric。 使用 npm create @microsoft/rayfin@latest 安装它。

按键命令:

命令 Purpose
npm create @microsoft/rayfin@latest 从模板创建新项目。
npx rayfin up 将项目部署到Fabric。
npx rayfin up db apply 应用数据库架构更改。

有关完整的命令参考,请参阅 CLI 参考。

数据模型修饰器

使用 TypeScript 修饰器定义数据模型:

默认的 blankapp 脚手架是通用应用工作空间。 数据是选择加入的:在将实体添加到packages/data/src/之前启用它,并将面向客户的合同保存在packages/shared/src/中。 扁平模板可以改用 rayfin/data/。 请参阅 “定义数据模型”。

import {
  entity,
  role,
  text,
  boolean,
  date,
  uuid,
} from '@microsoft/rayfin-core';

@entity()
@role('authenticated', '*', {
  policy: (claims, item) => claims.sub.eq(item.user_id),
})
export class Todo {
  @uuid() id!: string;
  @text({ min: 1, max: 100 }) title!: string;
  @boolean() isCompleted!: boolean;
  @date() createdAt!: Date;
  @date({ optional: true }) dueDate?: Date;
  @text({ max: 255 }) user_id!: string;
}

Fabric应用分析这些修饰器并生成:

  • 数据库表定义
  • GraphQL API 端点
  • 行级授权规则
  • 类型安全的客户端方法

何时使用Fabric应用

Fabric Apps 非常适合以下场景:

  • 快速原型制作 ——利用预配置基础设施,几分钟内从想法到上线 URL。
  • 内部工具和仪表盘 ——构建经过身份验证的管理界面,无需编写后端样板代码。
  • 数据探索与可视化——使用连接器查询支持的 Fabric 数据项,并在自定义前端显示结果。
  • 人工智能和代理应用 ——为需要持久状态的人工智能代理提供结构化后台服务。

Fabric应用可能不适合:

  • 需要复杂多步骤事务或存储过程的应用程序。
  • 需要 Fabric SSO 和电子邮件/密码之外的自定义身份验证提供程序的应用。

安全责任

Fabric 提供:Fabric 单点登录(Microsoft Entra ID)、通过@role装饰工具实现的行级安全、HTTPS、PKCE,以及工作区和项目级权限。

你负责:

  • 将机密、API 密钥和敏感数据保留在代码、前端资产和存储库之外。 无论托管权限配置如何,都不要把秘密存储在前端资产中。
  • 你的应用通过 Fabric SSO 控件公开的内容会控制登录,因为你的代码决定了已通过身份验证的用户可以看到什么以及执行哪些操作。
  • 仅授予参与者部署或管理应用所需的权限。
  • 应用收集、处理和存储的数据的法律和合规性责任。

后续步骤