使用 GitHub Copilot 建立語意模型應用程式

使用此配方，建立一個與 GitHub Copilot Agent 模式連結語意模型的分析應用程式。 Copilot 為資料應用程式範本搭建支架，新增 Fabric 語意模型連接器，建立 DAX 查詢與視覺化，並驗證應用程式。

資料應用程式範本提供 Fabric 認證、DAX 產生指引、視覺化元件及瀏覽器驗證。 該連接器透過 Fabric Apps 用戶端提供委派語意模型存取。 欲了解更多資訊，請參閱 建立與語意模型連結的應用程式。

在本教學課程中，您會：

• 準備 GitHub Copilot 以支援代理驅動開發。
• 詢問 Copilot 幫忙搭建資料應用程式範本。
• 將應用程式連接到語意模型。
• 打造一個互動式銷售績效探索器。
• 檢視並驗證所產生的變更。
• 將應用程式部署到 Fabric。
• 確認部署後開啟應用程式。

先決條件

• Node.js 20 或更新版本。
• Visual Studio Code。
• GitHub Copilot 在 Visual Studio Code 中使用，並支援代理模式。
• 一個可以存取 GitHub Copilot 的 GitHub 帳號。
• 可存取 Fabric 的 Microsoft 帳戶。
• 一個 Fabric 工作區，你擁有貢獻者、成員或管理員權限。
• Fabric Apps 工作負載已啟用給你的租戶。
• 「語意模型執行查詢 REST API」租用戶設定已啟用。
• 在託管於 Fabric 或 Power BI 容量的語意模型上建立與讀取權限。
• 語意模型的工作區 ID 與項目 ID。

備註

Copilot 在執行終端指令前會先徵求批准。 當 Rayfin CLI 要求時，你也必須完成互動式瀏覽器登入。

開啟 GitHub Copilot Agent 模式

1. 打開 Visual Studio 程式碼。
2. 打開你想讓 Copilot 建立專案的父資料夾。
3. 開放 聊天室。
4. 選取 Agent 模式。
5. 確認客服人員有權存取終端機和工作區。

不要打開包含你不想讓 Copilot 檢查或修改的無關檔案的資料夾。

建立資料應用程式骨架

將以下提示複製到 Copilot Chat：

Set up a new Fabric data app for me, end to end.

Create the project in a folder named sales-insights. Before changing code, read any
copilot-instructions.md files and agent guidance included in the scaffolded project.

Do the work yourself instead of only printing instructions:
1. Run `npm create @microsoft/rayfin@latest -- "sales-insights" --template dataapp --workspace <workspace-name>`.
2. In the scaffolded project, run `npx rayfin connector add --type fabric-semanticmodel --workspace-id <workspace-id> --item-id <semantic-model-item-id> --name salesModel --operations executeQuery`.
3. Run the version-matched npm install command printed by the connector command.
4. Open and inspect the scaffolded project. Explain the data app template's DAX query,
   visualization, data grid, theme, and browser-validation patterns.
5. Configure the template to use ConnectorsRayfinClient, the generated salesModel
   schema, and the fabricSemanticModel() runtime. Don't retain or add a direct
   Execute Queries REST API client.
6. If authentication is required, run `npx rayfin login` and pause while I complete
   sign-in.
7. Run the existing build and report any errors.
8. Summarize the scaffolded app and wait for my semantic model requirements.

Ask before making a destructive change or using a force option.

將 <workspace-id>、<semantic-model-item-id> 和 <workspace-name> 取代為您 Fabric 工作區和語意模型的值。 在 Copilot 執行指令時批准指令，並在提示時完成 Rayfin 登入流程。

請 詢問 Copilot 幫你打造應用程式

描述應用程式的受眾、問題、互動與視覺化。 salesModel連接埠已經識別語意模型。

請參考以下提示作為銷售績效探索器的起始配方。 調整業務需求以符合模型中可用的欄位。

Use the existing salesModel connector to build a sales performance explorer for
sales managers.

Requirements:
- Inspect the generated connector schema and semantic model metadata before editing.
  Use actual table, measure, and column names instead of guessing them.
- Show KPI callouts for the model's revenue, order volume, and margin measures when
  those measures are available.
- Add a time-series chart for sales performance, a bar chart that compares a useful
  business category, and a detailed data grid.
- Add date and category filters, and use the template's cross-highlighting behavior.
- Use the template's DAX generation patterns and visual primitives. Minimize the
  number of DAX queries and don't duplicate queries for the same data.
- Submit DAX with client.connectors.salesModel.executeQuery(), check the returned
  status, and handle success and error results.
- Apply the semantic model's format strings consistently to cards, charts, tooltips,
  and the data grid.
- Include loading, empty, and error states.
- Don't add mock data, embed credentials, or implement a separate authentication flow.
- Preserve the template's Fabric authentication and the semantic model connector.
- Don't add dependencies unless they're necessary.

Before editing, inspect the relevant files and give me a short implementation plan.
Ask me to clarify any model fields that are ambiguous. Then make the changes, run
the existing build, and use the template's browser validation workflow to check the
layout at desktop and mobile sizes. Explain any errors you fix.

在 Copilot 編輯專案前，先先審查他們的計畫。 如果計畫不符合您的需求，請在聊天中修正後再批准實施。

檢視已產生的變更

Copilot 完成後，請它檢視自己的工作：

Review the changes you made against every requirement in my previous prompt.

Check for:
- DAX queries that reference fields that aren't in the semantic model.
- Duplicate or unnecessary DAX queries.
- Hard-coded sample data, credentials, access tokens, or a second sign-in flow.
- Formatting that ignores the semantic model's format strings.
- Charts, filters, cross-highlighting, or data grid interactions that don't work.
- Missing loading, empty, or error states.
- TypeScript or build errors.

Fix confirmed issues, run the existing build and browser validation, and summarize
the final behavior.

檢查 Visual Studio Code 裡的原始碼控制差異。 特別注意：

• salesModel 連接器設定、產生的結構描述，以及 DAX 查詢。
• rayfin/rayfin.yml 中的服務設定。
• package.json 中的新相依性。
• 認證變更或繞過連接器的直接 REST 呼叫。
• 不得提交的祕密或憑證。

部署並驗證語意模型連結

請 Copilot 部署應用程式，並驗證其連線：

Deploy the app with `npx rayfin up`, then run `npx rayfin up status` and confirm
that the deployment is healthy. Give me the Fabric portal link from the command
output.

Don't add mock data if a semantic model query fails. Check the workspace and model
IDs in the connector configuration, the Semantic Model Execute Queries REST API
tenant setting, my Build and Read permissions, the DAX query, the connector error
result, and the browser console. Report the exact failure and the corrective action.

從 Fabric 入口開啟應用程式以測試即時語意模型查詢。

驗證應用程式

請 Copilot 執行專案現有的驗證：

Validate the app without adding new tools.

1. Run the existing build and type-check commands from package.json.
2. Run the template's browser validation at desktop and mobile sizes.
3. Check for clipped charts, unreadable labels, empty visuals, and console errors.
4. Tell me which semantic model queries and user interactions I must verify in the
    Fabric portal.
5. Fix confirmed build, type, or layout errors, and rerun the failed check.

在 Fabric 入口網站，確認你給 Copilot 的接受條件。 測試認證、篩選、交叉高亮、資料格式化、空狀態、錯誤處理，以及每個視覺效果的結果。

部署完成的應用程式

在你檢視變更並測試應用程式後，請 Copilot 部署它：

Deploy the reviewed app to Fabric.

1. Show me the current git diff and summarize what will be deployed.
2. Run `npx rayfin up`.
3. Run `npx rayfin up status`.
4. Confirm that the deployment is healthy.
5. Give me the hosted app URL and Fabric portal link from the command output.

Stop and explain the issue if deployment or verification fails.

當你繼續開發應用程式時，同樣 npx rayfin up 的指令會更新現有的部署。

繼續用 Copilot 迭代

後續修改時使用針對性的提示。 包含期望的行為、受影響的使用者、約束條件及驗證步驟。

Add a product detail view to the sales performance explorer.

Open the view when a user selects a product in the data grid. Use fields and measures
that exist in the semantic model, reuse existing query results where practical, and
preserve filters and formatting. Run the existing build and browser validation, then
list the interactions and DAX results I should verify in the Fabric portal.

請保持每個請求都足夠小以便審查。 在請 Copilot 進行大幅或可能造成破壞的變更之前，請先提交目前可正常運作的狀態。

排除 Copilot 工作流程的問題

Copilot 只印出指令

告訴 Copilot 自己執行指令並回報結果。 確認聊天處於 代理 模式且終端機存取已啟用。

一個指令正在等待登入

完成瀏覽器登入流程。 然後告訴 Copilot 登入完成，這樣才能繼續。

Copilot 編輯錯誤的資料夾

停止代理，打開 Visual Studio Code 裡的支架專案資料夾，然後從該工作區開始新的聊天。

部署成功，但語意模型查詢失敗

請 Copilot 檢查連接器的工作區和模型 ID、Semantic Model Execute Queries REST API 的租用戶設定、你的建置和讀取權限、產生的 DAX、連接器傳回的錯誤結果，以及瀏覽器主控台。 不要用模擬資料取代失敗的查詢。

Copilot 建議--force

要求 Copilot 先顯示可能破壞性的結構操作。 只有在你理解並核准可能的資料遺失時才接受 --force 。

其他問題請參見故障排除 Fabric 應用程式。

相關內容

• 用 Claude Code 建立 CSV 資料探索器
• 建立一個與語意模型連結的應用程式
• 將 Fabric 應用程式連接到 Fabric 資料
• 用 Rayfin CLI 建立一個 Fabric 應用程式
• 了解 Fabric Apps 專案結構
• 將 Fabric 應用程式部署至 Fabric