什麼是 Fabric Apps?

Fabric Apps 以 Rayfin SDK 為基礎,讓開發者能透過統一的開發流程,在 Fabric 上建立資料驅動型應用程式。 開發者在 TypeScript 中定義資料模型,Fabric Apps 自動產生 API、處理認證、提供主機服務,並與 Fabric 服務整合。 Fabric Apps 支援用於資料模型、用戶端程式碼及應用邏輯的 TypeScript。 想了解更多,請參閱 Rayfin SDK 總覽。

關鍵功能

Fabric Apps 提供以下功能:

  • 從資料模型到 API – 用 @text()、@uuid()、@entity() 及其他裝飾器裝飾 TypeScript 類別。 Fabric Apps 會自動產生資料庫架構與 GraphQL 端點。
  • 伺服器端函式 ——在伺服器上執行 TypeScript 邏輯,並透過已型別的用戶端從前端呼叫。 存取應用程式資料、處理祕密資料,並呼叫外部 API。 請參閱「在 Fabric 應用程式中使用函數」。
  • 使用連接器引入您自己的資料——新增對現有湖屋、倉庫、Fabric 中的 SQL 資料庫或語意模型的類型化存取。 支援的操作取決於連接器。 請參閱「將 Fabric 應用程式連接至 Fabric 資料」。
  • 檔案儲存 - 定義具類型的資料夾,使用認證政策控制存取,並在 Fabric 中上傳、下載、列出及刪除檔案。 請參閱 儲存與管理檔案。
  • 型別安全客戶端 ——客戶端 SDK 會在查詢與變異到達後端前驗證查詢與變異,並在開發過程中捕捉錯誤。
  • 內建認證 – 包含會話管理、權杖處理及認證流程。 為已部署的應用程式設定 Fabric SSO,或在本地開發時使用電子郵件與密碼。
  • 靜態託管 ——將你的前端應用程式與後端 API 一同建置與提供服務。 要求 Fabric 項目存取權,或允許匿名存取託管資產。
  • 開發工作流程 - 先建立支架專案,使用 GitHub Copilot 或其他程式設計代理開發,並使用 Rayfin CLI 部署到 Fabric。 在開發期間使用 Fabric 支援的服務,或為支援的本地服務使用 Docker。 檔案儲存在開發與部署中均使用 Fabric 儲存。

支援的區域

有關區域可用性,請參閱 Fabric 區域可用性。

先決條件

授權與工作空間

工作區需求視您應用程式所採用的授權選項而定:

  • 對於由容量支援的應用程式,請將 Fabric 容量或作用中的 Fabric 試用容量指派給工作區。 應用程式服務會消耗該容量中的容量單位。
  • 若要獲得 Power BI Pro 使用體驗,請使用 Pro 工作區。 您不需要指派 Fabric 容量。 Power BI Pro 的限制適用。

有關授權需求,請參閱「為 Fabric Apps 選擇授權選項」。 若要使用任一選項建立應用程式,請依照「 從入口網站建立應用程式」的操作操作。

租戶管理員設定

Fabric 租戶管理員必須先啟用 Fabric Apps 工作負載,使用者才能建立項目。

  1. 登入 Fabric 管理入口網站。
  2. 進入 租戶設定。
  3. 在 Fabric 應用程式下,將設定切換為「啟用」。
  4. 選擇是為整個組織啟用,還是針對特定安全群組啟用。
  5. 選擇 「申請」。

變化可能需要幾分鐘才能傳播。

運作原理

Fabric 應用程式結合了前端主機與受管後端服務。 您的前端使用 Rayfin 用戶端來存取資料 API、呼叫函式、管理檔案及查詢已連接的資料。 Fabric 負責主機託管、網路與擴展。 已部署的應用程式使用 Fabric SSO(Microsoft Entra ID 單一登入)進行使用者驗證;部署後則無法使用其他登入提供者。

顯示 Fabric 應用程式管理服務與元件的截圖。

當您使用 Rayfin CLI 部署時,Fabric 會配置或更新在 rayfin.yml 中啟用的服務。 選擇您的應用程式所需的服務:

Service 它所提供的是什麼
資料和 GraphQL APIs 結構化應用程式資料,存放於 Fabric 中的 SQL 資料庫,並由您的 TypeScript 資料模型與授權規則產生結構與 API。
Functions 透過可呼叫的 HTTP 端點,提供伺服器端 TypeScript 邏輯,包含型別用戶端呼叫及對應用程式資料與外部服務的存取。
檔案記憶體 OneLake 支援的文件、影像與附件儲存空間,具備類型化資料夾與驗證存取規則。 儲存需要資料服務。
Authentication 針對已部署應用程式的 Fabric SSO,讓使用者使用既有的 Fabric 身份登入。
靜態託管 已建置的前端檔案可透過託管 URL 提供,並可對靜態內容提供受保護或匿名存取權。

Fabric 入口網站中的管理

部署完成後,你可以直接在 Fabric 入口網站管理你的 Fabric 應用程式。

Fabric 管理員可以暫時封鎖其他使用者載入你的應用程式。 作為應用程式擁有者,你仍然可以開啟該應用程式。 更多資訊請參閱封鎖與解除封鎖 Fabric 應用程式。

如果你擁有或使用被封鎖的應用程式,請參閱「 當應用程式被封鎖時會發生什麼事」。

項目權限

Workspace 角色不會凌駕於項目層級的權限。 要與組織內的某人分享應用程式,他們需要 執行與互動 權限(讀取與執行)來執行該應用程式並調用後端 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 scaffold 是 Universal App 工作空間。 資料需選擇加入:在新增實體到 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;
}

您也可以連接現有資料,而非將所有資料儲存在應用程式的資料庫中。 連接器透過 SQL 分析端點提供對湖屋的讀取權限,支援對 Fabric 中倉庫或 SQL 資料庫的讀寫操作,以及針對語意模型進行查詢。 連接器存取需要適當的來源權限;它不會授予對底層資料的存取權限。 請參閱「將 Fabric 應用程式連接至 Fabric 資料」。

對於這些連接器以外的資料與服務,請使用函式呼叫外部 API 及支援的 Azure 和 Fabric 資源。 外部連線使用應用程式身份的權限,而透過函式存取應用程式資料庫則保留呼叫者的權限。 將憑證與資源權杖保留在伺服器上。 請參見「將函數連接到外部資源」。

何時使用 Fabric 應用程式

Fabric Apps 最適合:

  • 快速原型製作 ——利用預先設定的基礎設施,從構想到已上線的 URL 只需幾分鐘。
  • 內部工具與儀表板 ——建立需驗證身分的管理介面,無需撰寫後端樣板程式碼。
  • 資料探索與視覺化 – 使用連接器查詢支援的 Fabric 資料項目,並在自訂前端顯示結果。
  • AI 與代理應用 – 為需要持久狀態的 AI 代理提供結構化後端服務。

Fabric 應用程式可能不適合:

  • 需要複雜多步驟交易或儲存程序的應用。
  • 部署後需要 Fabric SSO 以外登入提供者的應用程式。

安全職責

Fabric 提供:Fabric 單點登入(Microsoft Entra ID)、透過@role裝飾工具的列級安全、HTTPS、PKCE,以及工作區和項目層級的權限。

你負責:

  • 將秘密、API 金鑰和敏感資料排除在程式碼、前端資產和資料庫之外。 不管主機存取權如何設定,都不要把秘密存進前端資產。
  • 你的應用程式透過 Fabric SSO 暴露的內容會控制登入,因為你的程式碼控制了經過認證的使用者看到和做什麼。
  • 只授予貢獻者部署或管理應用程式所需的權限。
  • 你的應用程式所收集、處理及儲存之資料的法律與合規責任。

下一步