使用資料應用程式範本搭配 Fabric 語意模型連接器，建立分析型 Fabric 應用程式。 該範本提供視覺化、格式化、資料網格及瀏覽器驗證模式。 此連接器可透過 Fabric Apps 用戶端，以具型別的委派存取方式存取語意模型。
開箱即用該範本製作的應用程式包括：
- Fabric 認證。
- 高品質 DAX（資料分析表達式）生成指引。
- 為分析應用設計的企業級視覺化元件。
- 資料網格、主題、格式與瀏覽器驗證模式。
備註
目前，Rayfin CLI 是使用資料應用範本建立應用程式的支援方式。
為什麼要使用資料應用程式範本？
若沒有這些內建功能，編碼代理必須在每個工作階段從零開始解決認證、DAX 產生與視覺化設計。 這可能導致：
- 更多失敗和畫面破碎或空洞。
- 圖表行為不一致。
- 開發與執行時出現不必要的 DAX 查詢。
該範本提供可重複使用的模式，提升可靠性，產生更連貫且符合報告最佳實務的視覺化，並降低查詢負擔。 該連接器標準化語意模型配置與執行時存取。
先決條件
- Node.js 20 或更新版本。
- Fabric 存取權限。
- 一個 Fabric 工作區，你擁有貢獻者、成員或管理員權限。
- 你的租戶已啟用 Fabric Apps 工作負載。 請參閱「建立你的第一個 Fabric 應用程式」。
- 「語意模型執行查詢 REST API」租用戶設定已啟用。
- 在託管於 Fabric 或 Power BI 容量的語意模型上建立與讀取權限。
- 語意模型的工作區 ID 與項目 ID。
建立應用程式
從資料應用程式範本建立專案：
npm create @microsoft/rayfin@latest -- "<app-name>" --template dataapp --workspace <workspace-name>
請將 <workspace-name> 和 <app-name> 替換為你的應用程式和 Fabric 工作區的名稱。 接著開啟新的專案資料夾：
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
命令：
- 將
salesModel連接器加入至rayfin/rayfin.yml。 - 在
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
使用 connector 用戶端來查詢語意模型。 若鷹架包含另一個語意模型用戶端，則取代對該客戶端的呼叫，而非維持兩條資料存取路徑。
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 。 在將欄位和列傳送到視覺化前，請先檢查回傳狀態。
欲了解更多連接器設定與安全指引，請參閱「Connect Fabric Apps to Fabric data」。
用程式代理來建立應用程式
此框架包含供程式碼代理使用的指示與技能。 在你偏好的代理中開啟專案，描述受眾、問題、互動以及應用程式的視覺化。
例如，您可以：
- 在 Visual Studio Code 中開啟專案，然後開啟 GitHub 的 Copilot Chat 窗格。
- 在專案中開啟終端機，然後執行
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 Apps 是標準的網頁應用程式，所以你可以實作這些模式之外的功能。 模板中未包含的功能可能需要更多客製化工程與驗證。
視覺效果
此範本包含交叉醒目提示及預先設定的基元如下：
- 條狀圖，包括垂直、水平、分組及堆疊配置。
- 折線圖，附有可選的標記。
- 區域圖。
- 散點圖。
- 派和甜甜圈圖表。
- 熱力圖。
- 氣泡圖。
- 瀑布圖。
- 用於 KPI 重點提示的單值卡片。
- 分層與複合視覺化，如帶資料標籤的條狀圖和雙軸折線圖。
使用連通語意模型中存在的欄位與度量。 不要用模擬資料替換失敗的連接器查詢。
你可以請你的程式代理產生其他視覺化。 沒有範本的視覺化原件可能需要更多迭代和驗證。
資料網格功能
範本包含具備以下預設功能的資料網格：
- 欄位標頭源自語意模型元資料。
- 透過格式字串將數字與日期格式套用至各欄。
- 排序中。
- 可捲動的列，並支援溢出處理。
- 光明與暗色主題支援。
- 適用於以下項目的自訂儲存格渲染器：
- 數字欄位。
- 布林指標。
- 可點擊的網址。
- 帶有燈箱疊加效果的影像單元。
- 多欄位的儲存格，例如在同一欄中顯示名稱和角色。
你可以加入其他資料網格功能，但可能需要更多客製化工程。
主題設計
為你的程式設計代理設定品牌或樣式需求，例如配色方案、邊角樣式或字體。 該範本將共用樣式集中在同一個中央位置，因此對樣式所做的變更都會套用到卡片、按鈕、圖表、資料格線和工具提示。
集中式樣式避免顏色不匹配、字體不一致及各元件獨立樣式時可能產生的版面差異。
格式化字串
每個結果欄的格式只需定義一次。 該範本可在圖表軸、工具提示、資料標籤、卡片及資料格格間重用語意模型格式字串。
例如，單一格式定義會讓 1500.5 一律顯示為 $1,500.50，並讓 0.25 一律顯示為 25%，無論這些值出現在哪裡。
瀏覽器驗證
在發佈應用程式前，請使用附帶的 Playwright 瀏覽器驗證流程，在真實瀏覽器中開啟並檢查：
- 畫面顯示正常。
- 圖表不會被截斷或壓縮。
- 文字是可讀的。
- 資料網格負責處理溢位。
- 載入、空和錯誤狀態都是可用的。
- 篩選、交叉高亮和資料格式都如預期般運作。
- 瀏覽器主控台沒有出現任何意外錯誤。
此工作流程能在使用者發現前發現版面與渲染問題。 瀏覽器驗證會確認前端行為。 請與同時使用 Fabric 應用程式與語意模型的使用者單獨測試已部署的連接器。
部署並驗證應用程式
部署應用程式與連接器配置：
npx rayfin up
從 Fabric 入口開啟已部署的應用程式。 登入後執行每次使用者互動，並與語意模型比較重要結果。
如果查詢失敗：
- 在
rayfin.yml中確認工作區和語意模型項目的識別碼。 - 確認「語義模型執行查詢」REST API 租戶設定是否啟用。
- 確認使用者對語意模型擁有建置與讀取權限。
- 確認 DAX 是否參考現有的資料表、欄位和度量。
- 檢查接頭結果的錯誤類別和訊息。
- 請檢查瀏覽器主控台是否有客戶端錯誤。