fabric-samples教你用GraphQL API连接Fabric数据:从C/Python客户端到React应用的全栈示例

原创2026-11-12 14:20:301,891 阅读

fabric-samples教你用GraphQL API连接Fabric数据:从C#/Python客户端到React应用的全栈示例

fabric-samples 是 Microsoft Fabric 教程配套的官方示例仓库。本文带你使用其中的 API for GraphQL 示例,快速掌握如何通过 Fabric 的 GraphQL API 连接和查询数据——覆盖 C#、Python 控制台客户端,React 前端应用,以及让 AI 助手直接查询数据的 MCP Server,从接口调用到前端可视化,全栈路径一次讲清。

先获取仓库(如尚未获取):git clone https://gitcode.com/gh_mirrors/fab/fabric-samples

所有示例统一位于 docs-samples/data-engineering/GraphQL/ 目录下:

示例 目录 适合场景
C# 控制台客户端 C# .NET 后端服务调用 Fabric 数据
Python 异步客户端 Python 脚本、数据工程任务
React + MSAL React 浏览器端登录 + 查询展示
React + Apollo + TypeScript React-Apollo-TS 类型安全的工程化项目
React + Node 服务器(Contoso) React-App-Contoso 前后端分离的图表展示
MCP GraphQL Server MCP 让 AI 用自然语言查数据
性能测试 Notebook benchmarking 压测你的 GraphQL 端点

一、跑通示例前的 3 个准备

无论用哪个客户端,都需要先在 Fabric 中准备好数据接口:

  1. 创建 SQL 数据库:在 Fabric 工作区选择 New item → SQL database,可勾选 Sample data 快速生成 AdventureWorks 示例表;
  2. 创建 GraphQL API:在 SQL 数据库工具栏点击 New API for GraphQL,选中要暴露的表(如 SalesLT 系列),几秒即可完成;
  3. 注册 Entra 应用:在 Entra 应用注册中拿到 Application (client) ID 和 Tenant ID,并在 Fabric 租户设置中为应用授权访问(Server-to-App 场景还需启用 Service Principal)。

准备好后,在 GraphQL API 主页点击 Copy endpoint 复制端点,例如形如 https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphqlapis/{apiId}/graphql,这就是所有示例要填入的地址。

二、C# 与 Python 客户端:最简后端调用方式

两个控制台示例结构几乎一致,共约 100 行代码,适合第一次理解"认证 + 查询"的完整链路:

两者都查询 addresses 表中的城市列表,核心 GraphQL 查询长这样:

query {
  addresses {
    items {
      City
    }
  }
}

上手步骤:把示例中的 CLIENT_ID、TENANT_ID 和 GRAPHQL_URI 换成自己的值,安装依赖(C# 用 NuGet 的 GraphQL.Client 系列包,Python 用 pip install msal gql aiohttp),运行即可看到查询结果。

三、React 前端接入:三种渐进式方案

1. React + MSAL:浏览器里直接登录查询

React 示例用 Vite + MSAL.js 实现:用户点击登录获取令牌后,点一下按钮即可拉取 Fabric 数据。关键配置集中在 authConfig.js,只需填入 clientId、tenantId 和 graphqlEndpoint 三个值。

启动方式(见 README):

npm install
npm run dev

示例查询的是 2024 年美国节假日数据,登录后点击 Query Fabric API for GraphQL Data 按钮即可看到结果。

2. React + Apollo + TypeScript:类型安全工程化

React-Apollo-TS 示例引入 Apollo Client 和 GraphQL Codegen:

  • Apollo 客户端在 Client.ts 中配置,自动附带 Authorization 请求头与内存缓存;
  • 查询/变更定义在 queries.graphql,例如查询客户 GET_CUSTOMERS 支持分页(after/first)与过滤(filter/orderBy)参数;
  • schema.graphql 配合 codegen.yml 可为查询生成完整的 TypeScript 类型提示。

如果你的 schema 不同,替换 schema.graphql 并更新 App.tsx 中的查询即可。

3. React + Node 服务器(Contoso):前后端分离

React-App-Contoso 展示了更贴近生产结构的方案:Node/Express 服务器(Server/index.js)统一获取令牌并转发 GraphQL 查询,前端 React 应用通过组件渲染柱状图、饼图和表格。

运行顺序:根目录 npm install 后先 npm start 启动服务器,再进入 client 目录 npm install && npm start,浏览器打开 http://localhost:3000。

四、MCP Server:让 AI 助手用自然语言查 Fabric 数据

MCP 示例 是一个 Model Context Protocol(MCP)服务器,把 Fabric GraphQL API 暴露为 MCP 工具(introspect-schema 读取 schema、query-graphql 执行查询),可在 VSCode Copilot、Cursor 等 AI 客户端中直接对话取数:

VSCode 中通过 MCP Server 调用 Microsoft Fabric GraphQL API 按邮编查询客户数据的截图

如截图所示:AI 先运行 introspect-schema 拿到完整 schema 概览,再用自然语言"查询邮编 90226 的客户",自动翻译成 query-graphql 调用并返回客户明细。

部署只需三步(详见 FabricGraphQL_MCP.js 同目录文档):

  1. npm install 安装依赖;
  2. 参照 env.template 创建 .env,填入 Fabric 端点、Tenant ID、Client ID 和 Client Secret;
  3. node FabricGraphQL_MCP.js 启动,默认监听 localhost:3000。

五、附录:GraphQL 端点性能压测

graphql_performance_test_notebook.ipynb 是一个性能测试 Notebook:填入端点、查询和变量后运行,会持续 1 小时采集每次请求的总耗时、API 开销与数据源执行耗时,并输出到 CSV 结果文件,适合评估生产环境的端点表现。

六、常见踩坑提示 ⚠️

  • Introspection 默认关闭:MCP 依赖 schema 内省,需由工作区管理员在 Fabric 门户中为你的 GraphQL API 开启 introspection;
  • 认证范围(scope):交互式登录使用 https://analysis.windows.net/powerbi/api/.default,而 Service Principal 服务端调用使用 https://api.fabric.microsoft.com/.default,两者别混用;
  • 权限不足:确认登录账号同时拥有 GraphQL API 及其关联数据源的访问权限,否则查询会返回授权错误;
  • MCP 工具不被识别:重启 AI 客户端并重新添加 MCP Server 配置即可。

小结

fabric-samples 的 GraphQL 示例按"后端脚本 → 前端应用 → AI 集成"提供了完整的进阶路径:先用 C# 或 Python 打通认证与查询,再用 React 示例 把数据变成界面,最后通过 MCP Server 让 AI 助手直接对话取数。跟着仓库里的 README 逐步替换配置值,就能快速把 Fabric 数据接入自己的技术栈 🚀

登录后查看全文
fabric-samples