使用这个方法创建一个分析应用，连接到一个带有 GitHub Copilot 智能体 模式的语义模型。 Copilot 为数据应用模板搭建支架，添加 Fabric 语义模型连接器，创建 DAX 查询和可视化，并验证应用。
数据应用模板提供 Fabric 认证、DAX 生成指导、可视化组件和浏览器验证。 该连接器通过 Fabric Apps 客户端提供委派语义模型访问。 有关详细信息，请参阅 创建连接到语义模型的应用。
在本教程中，你将了解：
- 为代理驱动开发做好 GitHub Copilot 的准备
- 询问 Copilot 帮忙搭建数据应用模板。
- 将应用连接到语义模型。
- 构建一个互动式销售绩效探索器。
- 审查并验证生成的更改。
- 将应用部署到Fabric。
- 验证部署后打开应用。
先决条件
- Node.js 20 或更高版本。
- Visual Studio Code。
- Visual Studio Code 中的 GitHub Copilot，可使用代理模式。
- 有权使用 GitHub Copilot 的 GitHub 账户。
- 可访问 Fabric 的 Microsoft 帐户。
- 具有参与者、成员或管理员权限的Fabric工作区。
- Fabric Apps 工作负载已为你的租户启用。
- 语义模型执行查询 REST API 租户设置已启用。
- 在托管于 Fabric 或 Power BI 容量上的语义模型上构建和读取权限。
- 语义模型的工作区ID和项目ID。
注释
Copilot在运行终端命令前会先征求批准。 当 Rayfin CLI 提示时，你还必须在浏览器中完成交互式登录。
打开 GitHub Copilot 代理模式
- 打开Visual Studio代码。
- 打开你想让 Copilot 创建项目的父文件夹。
- 打开 聊天。
- 选择 智能体 模式。
- 确认客服是否能访问终端和工作区。
不要打开包含你不想让 Copilot 检查或修改的无关文件的文件夹。
搭建数据应用
将以下提示复制到 Copilot 对话助手：
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 的计划。 如果计划不符合您的要求，请在批准实施前通过聊天进行修正。
查看生成的更改
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 租户设置、你的 Build 和 Read 权限、生成的 DAX、连接器错误结果以及浏览器控制台。 不要用模拟数据替换失败的查询。
Copilot 建议--force
要求 Copilot 先显示可能具有破坏性的架构操作。 仅当你已了解并接受可能发生的数据丢失时，才接受 --force。
有关其他问题，请参见 “Fabric 应用故障排除”。