Fabric 对接说明
面向对象：客户 Azure 管理员、平台管理员、实施顾问 说明范围：Microsoft Fabric 作为 Analytics 数据源 的对接逻辑与配置要点 定位说明：本文仅覆盖"数据源对接"场景，不涉及向量库方案，也不展开 MCP 预配置能力
适用范围与版本边界
支持什么：
- 平台连接客户 Microsoft Fabric 的 SQL Endpoint / Warehouse，用作 Analytics 数据源：浏览表/视图、同步元数据、预览数据、供分析报表使用。
- 认证方式以 SSO（Entra ID OAuth，基于服务主体 Service Principal） 为默认与推荐方式；同时保留传统 用户名密码认证 作为兼容选项。
- SSO 支持两种令牌管理模式：
- Zero-Trust（默认）：仅保存短期 access token，不持久化 refresh token，令牌过期后需重新走一次授权。
- Token-Refresh：持久化完整 MSAL 令牌缓存（含 refresh token），支持静默刷新，减少人工重新授权频率。
不支持什么：
- 本文不涉及 Fabric 作为知识库向量存储的方案（如有该类需求需参考单独的向量库相关文档）。
- 不展开 Fabric 相关的 MCP（Model Context Protocol）预配置能力，这属于另一独立能力范畴。
- Fabric 数据源不使用端口号配置（Fabric SQL Endpoint 走 HTTPS 层协议，无需额外端口）。
- 平台不负责 Fabric 工作区（Workspace）、Warehouse/Lakehouse 的创建与权限分配，需由管理员完成。
前置条件清单
| 类别 | 前置条件 |
|---|---|
| 权限 | Entra ID 具备注册应用（服务主体）权限；该服务主体需在 Fabric 管理中心被授予对目标 Workspace/Warehouse 的访问权限（如 Viewer/Contributor，视 Fabric 权限模型而定，由 Fabric 管理员配置）。 |
| 账号 | Client ID / Client Secret / Tenant ID（服务主体三要素）；SSO 模式下无需额外用户名密码。 |
| 网络 | 平台服务器需能访问 Fabric SQL Endpoint（如 <workspace>.fabric.microsoft.com 或 <warehouse>-<id>.datawarehouse.fabric.microsoft.com）与 Entra ID 登录端点。 |
| 资源准备 | 目标 Warehouse/Lakehouse 名称（对应 database 字段）；确认平台部署环境已正确配置 FABRIC_REDIRECT_URI 等 OAuth 回调环境变量。 |
| ⚠️ 需确认 | 服务主体在 Fabric 侧的具体权限范围（是否覆盖目标 Warehouse 的读取权限）；是否需要使用 Token-Refresh 模式以减少重复授权。 |
Azure 侧配置要点
- 注册服务主体：在 Azure Portal → Entra ID → 应用注册 中创建应用，记录 Client ID、Tenant ID。
- 创建 Client Secret：在应用"证书和密码"中创建密钥，妥善保存密钥值。
- Fabric 侧授权：在 Fabric 管理中心（或目标 Workspace 的访问权限设置）中，将该服务主体添加为 Workspace 成员，并授予其访问目标 Warehouse/Lakehouse 所需的权限。
- 确认 SQL Endpoint 地址：在 Fabric Workspace 中查看 Warehouse/Lakehouse 的 SQL Endpoint 连接字符串，形 如
<workspace>.fabric.microsoft.com或<warehouse>-<id>.datawarehouse.fabric.microsoft.com。 - 确认租户是否允许服务主体访问 Fabric：部分租户可能默认关闭服务主体对 Fabric API 的访问，需要管理员在 Fabric 租户设置中开启"服务主体可以使用 Fabric API"相关选项。
平台侧录入要点
| 字段名 | 必填 | 说明 |
|---|---|---|
| 主机地址（Host） | ✅ | Fabric SQL Endpoint / Warehouse 服务器地址，例如 <workspace>.fabric.microsoft.com |
| 数据库名称（Database Name） | ✅ | 目标 Warehouse 或 Lakehouse 的名称 |
| 认证类型（Auth Type） | ✅ | 选择 sso（推荐）用于 OAuth 服务主体认证，或 password（兼容旧模式）用于用户名密码 |
| 客户端 ID（Client ID） | SSO 下必填 | Entra 服务主体的 Client ID（应用程序 ID） |
| 租户 ID（Tenant ID） | SSO 下必填 | Azure AD 租户 ID（Directory ID） |
| 客户端密钥/密码 | ✅ | SSO 模式下填入 Client Secret；密码模式下填入用户密码，平台均 RSA 加密存储 |
| 令牌模式（Mode） | 可选 | zero_trust（默认，令牌过期需重新授权）或 token_refresh（支持自动刷新，推荐长期使用） |
| 用户名 | 密码模式下必填 | SSO 模式下无需填写 |
| 架构（Schema） | 可选 | 数据库架构名称，留空时使用默认架构 |
| 端口 | 不使用 | Fabric 不需要配置端口号 |
录入与授权流程：
- 在左侧填写连接信息（主机地址、数据库名称、Client ID、Tenant ID）。
- 在右侧填写身份验证信息（客户端密钥、认证类型、令牌模式）。
- 点击"发起授权"（Authenticate 按钮），系统跳转至 Microsoft 登录页。
- 客户 Azure 管理员完成登录与授权同意，Microsoft 回调完成令牌交换，数据源状态更新为"已授权"。
- 授权成功后，点击"测试连接"验证可用性。
具体操作指南
进入数据源创建页面
- 在Data界面中，找到数据源入口
- 点击"创建数据源"或"新建数据源"按钮
- 在弹出的数据源类型选择对话框中，选择 Fabric
填写基本连接信息
在左侧表单中填写以下必填项：
Host（主机地址）*
- 输入 Fabric 服务的 SQL Endpoint 地址
- 示例：
<workspace>.fabric.microsoft.com或<warehouse>-<id>.datawarehouse.fabric.microsoft.com
Database Name（数据库名称）*
- 输入 Warehouse 名称
- 确保该 Warehouse 在 Fabric 实例中已存在
Client ID（客户端 ID）*
- 输入 Azure AD 应用程序（服务主体）的 Client ID
- 可在 Azure Portal 的应用注册中找到此信息
Schema（架构）
- （可选）输入数据库架构名称
- 如不指定，将使用默认架构
填写身份验证信息
在右侧表单中填写以下必填项：
Client Secret（客户端密钥）*
- 输入 Azure AD 应用程序的客户端密钥
- 注意：此密钥具有时效性，需确保未过期
- 重要：请妥善保管此密钥，不要泄露
Tenant ID（租户 ID）*
- 输入 Azure AD 租户 ID（Directory ID）
- 可在 Azure Portal 的 Azure Active Directory 概述中找到
Auth Type（认证类型）*
- 选择
sso（推荐）用于 OAuth 基于服务主体的认证 - 可选
password作为兼容旧模式（不推荐）
Mode（令牌模式）
zero_trust（默认）：不持久化 refresh token，access token 过期后需重新授权token_refresh：持久化完整 MSAL 缓存，支持静默刷新，减少重新授权频率
Auto Refresh Token（自动刷新令牌）
- 启用此选项可以自动刷新访问令牌
- 推荐开启，以确保长时间运行的查询不会因令牌过期而失败
验证连接
- 确认所有必填字段（标记为 * 的字段）都已正确填写
- 点击页面底部的 "Authenticate"（认证）按钮
- 系统将自动跳转至 Microsoft 账号登录页面
- 使用具有 Fabric 权限的账号完成登录并授权
- 登录成功后，数据源状态更新为"已授权"，即可成功连接 Fabric 数据源
测试与验证
完成授权后，按以下步骤验证连接可用性：
- 点击"测试连接"，系统会发现并列出可见的表和视图
- 对至少一张关键表执行"同步表结构"，验证字段信息
- 对该表执行"数据预览"，确认能正常取到数据
- 若使用 Token-Refresh 模式，建议在一段时间后重新发起查询，验证静默刷新是否生效
常见问题与排查路径
| 问题分类 | 现象 | 可能原因 | 排查建议 |
|---|---|---|---|
| 认证失败/令牌过期 | 提示"无法获取 Fabric 访问令牌，请通过 OAuth 重新授权数据源" | Zero-Trust 模式下 access token 已过期；Token-Refresh 模式下 refresh token 失效或静默刷新失败 | 重新执行一次 OAuth 授权流程；如频繁出现，建议切换为 Token-Refresh 模式 |
| 未完成认证 | 提示"数据源尚未成功通过认证，请先完成认证流程" | 尚未走过 OAuth 授权，或授权状态被重置 | 管理员完成一次授权登录 |
| SSO 参数缺失 | 发起授权时报"未配置 SSO 认证"相关错误 | auth_type 未设置为 sso，或 client_id/tenant_id 未填写 | 检查并补全 others.auth_type=sso 及 client_id/tenant_id，client_secret 存入 password 字段 |
| 端点/连接超时 | 测试连接长时间无响应或超时 | SQL Endpoint 地址错误；网络策略限制；Fabric Workspace/Warehouse 未处于可用状态 | 核对 SQL Endpoint 地址；检查网络出口策略；确认 Warehouse/Lakehouse 状态正常 |
| 权限不足 | 测试连接成功但表/视图列表为空，或查询报权限错误 | 服务主体未被授予该 Workspace/Warehouse 的访问权限 | 请 Fabric 管理员在 Workspace 权限设置中添加该服务主体并授予相应角色 |
| Microsoft 侧认证错误（AADSTS 系列） | 授权回调报 error=AADSTSxxxxxx | Client ID/Secret 错误、租户策略限制、服务主体被禁用等 | 根据具体 AADSTS 错误码到 Azure Portal 核实应用状态、租户策略（如条件访问策略是否拦截了服务主体登录） |
| 通用连接失败 | 报"数据源连接失败" | 网络超时、Fabric 服务临时不可用、驱动异常 | 稍后重试；检查 Fabric 服务状态页；必要时联系网络/安全团队排查 |