什么是Fabric应用（预览版）？

Fabric应用（预览版）通过组合数据模型、生成的 API、身份验证和托管在一个开发工作流中，帮助你在Microsoft Fabric上生成数据驱动应用程序。 在 TypeScript 中定义数据模型，Fabric应用使用这些模型生成应用所需的后端部分。 Fabric Apps 支持 TypeScript 作为数据模型、客户端代码和应用程序逻辑的语言。

Important

此功能目前为预览版。

主要功能

Fabric应用提供这些功能：

  • API 的数据模型 – 使用@entity()、@text()@uuid()和其他修饰器修饰 TypeScript 类。 Fabric 应用会自动生成数据库架构和 GraphQL 端点。
  • 类型安全客户端 – 客户端 SDK 在到达后端之前验证查询和突变，并在开发过程中捕获错误。
  • 内置身份验证 - 包括会话管理、令牌处理和身份验证流。 为已部署的应用程序配置 Fabric SSO，或在本地开发期间使用电子邮件和密码。
  • 静态托管 – 使用单个部署命令与后端 API 一起生成和提供前端应用程序。
  • Local 开发 – 使用 Docker 在本地运行完整堆栈，以便快速迭代，然后在准备好生产时部署到Microsoft Fabric。 搭建项目、使用GitHub Copilot进行开发，并使用 Rayfin CLI 部署到Fabric。

先决条件

Fabric 容量

工作区必须已分配 Fabric 容量。 创建新工作区时，选择要与之关联的Fabric容量。 Fabric 应用服务消耗所分配容量中的容量单位。

租户管理员设置

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

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

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

工作原理

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

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

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

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

应用后端 URL

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

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

终结点公开每个服务的路径：

路径 Service
/api/graphql 数据 API（GraphQL）— 由 RayfinClient 用于读取和写入操作
/auth 身份验证服务
/storage 文件存储

Fabric门户中的管理

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

查看项属性

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

  • 应用后端 URL - 此终结点用于应用程序使用的所有后端服务。
  • 应用 URL — 托管静态内容的公共 URL。 访问应用需要Fabric SSO。

管理子项

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

  • Fabric 中的 SQL 数据库 — 打开 Fabric SQL 数据库项，以查看对象资源管理器。 您可以对您的数据执行读取查询。 架构更改应始终在文件夹下 rayfin/data 的代码中进行。 如果架构直接在 SQL 数据库中发生更改，并且可能会中断应用，则会发生架构冲突。

项目权限

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

许可 它允许的内容
运行和交互 （默认值） 打开并使用已部署的应用程序。 默认情况下，所有工作区成员都会收到此级别。
编辑 （写入） 修改Fabric应用 — 使用 rayfin up 部署代码、应用架构更改、更新设置和管理子服务。
重新共享 向其他用户授予对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 修饰器定义数据模型：

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() user_id!: string;
}

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

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

何时使用Fabric应用

Fabric Apps 非常适合以下场景：

  • 快速原型制作 - 使用预配置的基础结构在几分钟内从想法转到实时 URL。
  • 内部工具和仪表板 - 生成经过身份验证的管理员界面，而无需编写后端样板。
  • 数据浏览和可视化 – 通过 GraphQL 查询Fabric数据并将其显示在自定义前端中。
  • AI 和代理应用程序 – 为需要持久状态的 AI 代理提供结构化后端服务。

Fabric应用可能不适合：

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

安全责任

Fabric 提供： Fabric 单点登录（Microsoft Entra ID）、通过 @role 修饰器实现的行级安全性、HTTPS、PKCE，以及工作区级和项级权限。

你负责：

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

后续步骤

  • Last updated on