在 Fabric 應用程式中使用函式

函式是 TypeScript 函式，會在你的 Fabric 應用程式內的伺服器上執行。 使用不能在瀏覽器中執行的邏輯函式，例如處理秘密、存取特權資料，以及以應用程式身份呼叫下游服務。

每個函式都會以名稱註冊，並以可呼叫的 HTTP 端點形式公開。 你的 React 前端會透過已型別的 Rayfin 客戶端呼叫函式，因此你不需要實作請求、路由或標記處理。

何時使用函數

使用 Rayfin 函數來：

• 使用應用程式權杖呼叫外部 API。 範例包括 Azure AI Foundry、Azure DevOps、Fabric、Azure 儲存體 和 Azure Key Vault。
• 透過伺服器強制執行的列級安全，讀取或寫入應用程式的資料庫。
• 將 API 金鑰、模型部署名稱及其他秘密隱藏在用戶端程式碼之外。
• 在靠近資料的位置執行編排，例如扇出式呼叫、彙總或 AI 提示詞。

先決條件

在開始之前，請安裝或建立以下資源：

• Node.js 20 或更新版本，以及 npm。
• 一個使用 Rayfin CLI 建立的 Fabric 應用程式支架。
• Azure Functions Core Tools，是本機函式主機用於偵錯的工具。

Install Azure Functions Core Tools version 4：

npm install --global azure-functions-core-tools@4

建立一個有功能的應用程式

架構應用程式並初始化其函式專案：

npm create @microsoft/rayfin@latest

cd my-app

npx rayfin functions init

此 rayfin functions init 指令會將函數專案、TypeScript 設定及起始函式檔案加入現有應用程式。

用 GitHub Copilot 建置應用程式

此專案樣板包含了使用 GitHub Copilot 處理此專案所需的指示與技能。 在 Visual Studio Code 中開啟專案，並在 GitHub Copilot Chat 描述你想建立的應用程式。

例如，請使用以下提示詞來建立 AI 提取要求審核助理：

Build an app that helps business analysts track sales performance across
regions. Show key metrics, let analysts ask questions about trends, and
use Functions to securely retrieve data from our sales API with application
authentication.

GitHub Copilot 可以產生並更新所需的檔案與元件。 你也可以請代理執行應用程式、在本地除錯功能，然後部署應用程式。

了解專案的架構

初始化指令的函式更新 rayfin/rayfin.yml 並產生 rayfin/functions。 一個具有函式的典型應用程式具有以下結構：

my-app/
├── rayfin/
│   ├── rayfin.yml
│   ├── data/
│   │   ├── TripPlan.ts
│   │   └── schema.ts
│   └── functions/
│       ├── package.json
│       ├── tsconfig.json
│       └── src/
│           ├── function_app.ts
│           └── types.ts
└── src/
    └── services/

這些檔案的用途如下：

啟用函式時， rayfin/rayfin.yml 包含函數服務：

services:
  functions:
    enabled: true
    auth:
      type: application
    buildCommand: npm run build

應用程式驗證

已啟用的功能需要在 rayfin/rayfin.yml 中進行明確的應用程式驗證：

services:
  functions:
    enabled: true
    auth:
      type: application
    buildCommand: npm run build

新函數 支架 集合 auth.type: application。

禁用函式可以省略 auth。 但是，如果您提供 auth，則必須包含：

auth:
  type: application

完整的 npx rayfin up 流程和一般的 npx rayfin dev 流程會先驗證這項設定，再將專案設定套用至 Fabric 或 Docker 後端。

執行完整的 npx rayfin up，將 YAML 驗證模式套用至現有的遠端應用程式。

部署函式所使用的認證路徑

部署函式使用兩條獨立的認證路徑：

對於目前的 Fabric 應用程式，應用程式身份是 BaaS 項目的擁有者。

因此，外部連線使用的是物品擁有者的權限，而非呼叫該功能的應用程式使用者的權限。 授予應用程式身份，賦予每個由函式程式碼呼叫的外部資源和 API 所需的權限。

宣告受眾或部署函式並不會賦予應用程式對外部資源的身份權限。

應用程式登入與授權呼叫功能，與應用程式身份對外部資源的存取是分開的。

Rayfin 資料庫存取始終使用 Rayfin 令牌，並保留呼叫者的身份與資料庫權限。 設定 services.functions.auth.type: application 不會將 Rayfin 資料庫的存取切換到應用程式身份。

關於受眾宣告、資源標記、權限及本地開發行為，請參見 「連結函式與外部資源」。

在本機執行應用程式

從應用程式的根目錄登入：

cd my-app
npx rayfin login

啟動前端和本機函式主機：

npm run dev

在函數啟用專案中， npm run dev 映射到 rayfin dev。 此指令套用結構，啟動本地函式主機，並啟動 Vite 開發伺服器。 打開終端機列印的本地網址，並在開發和除錯應用程式時保持終端機運作。

若只啟動 host 函式，例如當你獨立執行前端時，請使用以下指令：

cd my-app
npx rayfin dev 

部署到 Fabric

部署應用程式的資料、靜態網站與功能：

npx rayfin up --workspace <workspace-name>

請將 <WORKSPACE> 替換為目標 Fabric 工作區的名稱。

為現有應用程式新增函式

從現有 Fabric 應用程式的根節點，啟用該功能並初始化函式專案一次：

npx rayfin functions init

初始化後，加入函數實作到 rayfin/functions/src/function_app.ts。

Limitations

• 函式所有權：只有使用者資料函數項目的擁有者才能修改並發佈函式程式碼。
• 發佈冷卻時間：發佈後至少等待兩分鐘再重新發佈。 此冷卻時間適用於從 Functions 的瀏覽器內入口網站、User Data Functions Visual Studio Code 擴充功能、Git 匯入作業或部署管線進行發佈。
• 部署套件大小：Functions 的 ZIP 檔案不得超過 30 MB。
• 請求有效載荷大小：使用者資料功能服務記錄所有請求參數合計最大 4 MB。 這個限制預期會適用於 Rayfin 函數，但尚未被驗證。
• 執行逾時：一個函式最多可執行 240 秒。
• 呼叫日誌保留：歷史呼叫日誌預設保留 30 天。
• 應用程式身份：應用程式身份目前是 BaaS 項目的擁有者。

關於區域可用性需求及更多使用者資料功能限制細節，請參見 Fabric 使用者資料功能的服務細節與限制。

相關內容

• 了解 Fabric Apps 專案結構
• Fabric 應用程式的認證
• 將功能與外部資源連結
• 管理函式的祕密
• 將 Fabric 應用程式部署至 Fabric
• Rayfin CLI 參考資料