企业官网建设流程全解析

DataHub 集成 Microsoft Fabric OneLake：fabric-onelake 元数据摄取连接器实战指南

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub

导读：本文围绕 DataHub 仓库中的fabric-onelake摄取模块展开，系统讲解如何将 Microsoft Fabric OneLake 的工作区（Workspace）、湖仓（Lakehouse）、数据仓库（Warehouse）、Schema 容器、表与视图元数据，以及基于queryinsights的查询用量统计同步进 DataHub。读完本文，你将掌握该连接器的认证与权限配置、recipe 参数全解、SQL Analytics Endpoint 驱动部署、视图血缘与用量统计的启用条件，以及 30 天留存与权限不足等关键限制的规避方法。

fabric-onelake是 DataHub 元数据摄取框架（metadata-ingestion）中面向生产环境的 OneLake 源模块。它的入口实现位于 source.py，配置模型定义于 config.py。下文所有配置项、默认值与校验规则均以这两个文件及仓库中的官方文档（fabric-onelake_pre.md、fabric-onelake_post.md、fabric-onelake_recipe.yml）为准。

模块能力总览

该连接器将 Fabric 中的对象映射为 DataHub 元数据模型中的实体，核心能力包括：

• 摄取Workspace、Lakehouse、Warehouse、Schema 四类容器（Container）实体；
• 摄取表（Table）数据集，并带正确的子类型；
• 摄取视图（View）数据集，视图定义取自 SQL Analytics Endpoint；
• 从视图定义中解析出视图到上游表的血缘（lineage）；
• 从queryinsights.exec_requests_history提取查询用量统计与操作（operation）aspects；
• 自动探测并区分 schemas-enabled 与 schemas-disabled 湖仓，选择对应 API 与 token audience；
• 提供面向 workspaces、lakehouses、warehouses、tables、views 的正则模式过滤；
• 支持有状态摄取（stateful ingestion），可清理 DataHub 中已不存在的陈旧实体；
• 支持Service Principal、Managed Identity、Azure CLI、DefaultAzureCredential四种 Azure 认证方式。

从源码结构看，该模块由client.py（Fabric REST 与 OneLake API 客户端）、schema_client.py（SQL Analytics Endpoint 模式提取）、usage.py（用量统计）、models.py（数据模型）与config.py（配置校验）协同实现。

认证与前置条件

四种认证方式

连接器通过credential块选择认证方式，对应实现为AzureCredentialConfig（见 azure_auth.py）：

连接器内部通过FabricAuthHelper（common/auth.py）将 AzureTokenCredential转换为 Bearer Token，并针对不同操作使用两套不同的 token audience：

• Fabric REST API（https://api.fabric.microsoft.com）：使用 Power BI API scopehttps://analysis.windows.net/powerbi/api/.default，用于列举 workspaces、lakehouses、warehouses 及基础表元数据；
• OneLake Delta Table APIs（https://onelake.table.fabric.microsoft.com）：使用 Storage audiencehttps://storage.azure.com/.default，用于 schemas-enabled 湖仓中的 schema 与表访问；
• SQL Analytics Endpoint 连接则使用数据库 scopehttps://database.windows.net/.default。

Token 采用带过期时间（提前 300 秒刷新）的缓存机制，同 scope 复用缓存，无需为每次 API 调用重新获取。

必需权限

连接器对 Fabric 工作区及其内容只需只读访问。被认证的身份（服务主体、托管身份或用户）必须具备：

工作区级权限：

• Workspace.Read.All或Workspace.ReadWrite.All（Microsoft Entra 委托范围）；
• 目标工作区中的Viewer 及以上角色。

API 权限（Entra）：

• Workspace.Read.All（委托）——列举与读取工作区元数据所需；
• 或Workspace.ReadWrite.All（委托）。

OneLake 数据访问权限（schemas-enabled 湖仓）：

• 若湖仓开启了 OneLake 安全设置，需在湖仓项的 security settings 中授予Read / ReadWrite权限；
• 该权限独立于工作区角色，需在 Fabric 门户的湖仓安全设置中单独管理。

文档与源码均强调：连接器会自动探测湖仓是否启用了 schema 并切换对应 API 端点与 token audience，无需额外配置。

为 Service Principal 授权

1. 在 Microsoft Entra ID（Azure AD）中注册应用；
2. 授予 API 权限：Azure Portal → App registrations → 你的应用 → API permissions，添加Power BI Service → Delegated permissions →Workspace.Read.All，必要时点击Grant admin consent；
3. 分配工作区角色：Fabric 门户中进入每个工作区 →Workspace settings → Access，将服务主体添加为Viewer 及以上角色。

为 Managed Identity 授权

1. 在 Azure 资源（VM、AKS、App Service 等）上启用系统分配托管身份；
2. 将托管身份以Viewer 及以上角色加入目标 Fabric 工作区；
3. 连接器会自动使用托管身份完成认证。

SQL Analytics Endpoint 环境准备

视图提取、Schema 列级元数据提取与用量统计都依赖 SQL Analytics Endpoint，而这需要系统安装 ODBC 驱动。这是本模块最易踩坑的环境环节。

1. 安装 ODBC 驱动管理器

Ubuntu/Debian：

sudo apt-get update sudo apt-get install -y unixodbc unixodbc-dev

RHEL/CentOS/Fedora：

# RHEL/CentOS 7/8 sudo yum install -y unixODBC unixODBC-devel # Fedora / RHEL 9+ sudo dnf install -y unixODBC unixODBC-devel

macOS：

brew install unixodbc

2. 安装 Microsoft ODBC Driver 18 for SQL Server

Ubuntu 20.04/22.04：

curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list sudo apt-get update sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18

RHEL/CentOS 7/8：

sudo curl -o /etc/yum.repos.d/mssql-release.repo https://packages.microsoft.com/config/rhel/$(rpm -E %{rhel})/mssql-release.repo sudo ACCEPT_EULA=Y yum install -y msodbcsql18

RHEL 9 / Fedora：

sudo curl -o /etc/yum.repos.d/mssql-release.repo https://packages.microsoft.com/config/rhel/9/mssql-release.repo sudo ACCEPT_EULA=Y dnf install -y msodbcsql18

macOS：

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release brew update HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

3. 验证驱动安装

odbcinst -q -d

输出列表中应出现ODBC Driver 18 for SQL Server。

4. 权限与 Python 依赖

被认证的 Azure 身份必须具备查询 SQL Analytics Endpoint 的权限（与使用 SQL 工具访问该端点的权限一致）。随后安装带fabric-onelakeextra 的 DataHub 客户端：

pip install 'acryl-datahub[fabric-onelake]'

该 extra 会带入sqlalchemy与pyodbc依赖。若运行时报libodbc.so.2: cannot open shared object file，说明驱动管理器（第 1 步）未安装或未生效。

Recipe 配置全解

仓库提供了一份带完整注释的模板 fabric-onelake_recipe.yml，并可用官方命令运行摄取：

datahub ingest -c fabric-onelake_recipe.yml

基础 Recipe（Service Principal）

source: type: fabric-onelake config: # Authentication (using service principal) credential: authentication_method: service_principal client_id: ${AZURE_CLIENT_ID} client_secret: ${AZURE_CLIENT_SECRET} tenant_id: ${AZURE_TENANT_ID} # Optional: Platform instance (use as tenant identifier) # platform_instance: "contoso-tenant" # Optional: Environment # env: PROD # Optional: Filter workspaces by name pattern # workspace_pattern: # allow: # - "prod-.*" # deny: # - ".*-test" # Optional: Filter lakehouses by name pattern # lakehouse_pattern: # allow: # - ".*" # deny: [] # Optional: Filter warehouses by name pattern # warehouse_pattern: # allow: # - ".*" # deny: [] # Optional: Filter tables by name pattern # table_pattern: # allow: # - ".*" # deny: [] sink: type: datahub-rest config: server: "http://localhost:8080"

高级 Recipe（含过滤与功能开关）

source: type: fabric-onelake config: credential: authentication_method: service_principal client_id: ${AZURE_CLIENT_ID} client_secret: ${AZURE_CLIENT_SECRET} tenant_id: ${AZURE_TENANT_ID} # Platform instance (represents tenant) platform_instance: "contoso-tenant" # Environment env: PROD # Filtering workspace_pattern: allow: - "prod-.*" - "shared-.*" deny: - ".*-test" - ".*-dev" lakehouse_pattern: allow: - ".*" deny: - ".*-backup" warehouse_pattern: allow: - ".*" deny: [] table_pattern: allow: - ".*" deny: - ".*_temp" - ".*_backup" view_pattern: allow: - ".*" deny: - ".*_internal" # Feature flags extract_lakehouses: true extract_warehouses: true extract_schemas: true # Set to false to skip schema containers extract_views: true # Requires sql_endpoint.enabled # API timeout (seconds) api_timeout: 30 # Stateful ingestion (optional) stateful_ingestion: enabled: true remove_stale_metadata: true sink: type: datahub-rest config: server: "http://localhost:8080"

Managed Identity 与 Azure CLI 示例

source: type: fabric-onelake config: credential: authentication_method: managed_identity # For user-assigned managed identity, specify client_id # client_id: ${MANAGED_IDENTITY_CLIENT_ID} platform_instance: "contoso-tenant" env: PROD sink: type: datahub-rest config: server: "http://localhost:8080"

source: type: fabric-onelake config: credential: authentication_method: cli # Run 'az login' first platform_instance: "contoso-tenant" env: DEV sink: type: datahub-rest config: server: "http://localhost:8080"

配置参数速查表

以下参数均来自 config.py 的FabricOneLakeSourceConfig，括号内为默认值：

SQL Analytics Endpoint 配置

Schema 提取默认开启，可通过如下配置调整：

source: type: fabric-onelake config: credential: authentication_method: service_principal client_id: ${AZURE_CLIENT_ID} client_secret: ${AZURE_CLIENT_SECRET} tenant_id: ${AZURE_TENANT_ID} # Schema extraction configuration extract_schema: enabled: true # Enable schema extraction (default: true) method: sql_analytics_endpoint # Currently only this method is supported # SQL Analytics Endpoint configuration sql_endpoint: enabled: true # Enable SQL endpoint connection (default: true) # odbc_driver: "ODBC Driver 18 for SQL Server" # Default: "ODBC Driver 18 for SQL Server" # encrypt: "yes" # Enable encryption (default: "yes") # trust_server_certificate: "no" # Trust server certificate (default: "no") query_timeout: 30 # Timeout for SQL queries in seconds (default: 30)

其中sql_endpoint的底层校验逻辑值得注意：

• odbc_driver：默认ODBC Driver 18 for SQL Server；
• encrypt：合法值为yes/no/mandatory/optional/strict。yes/mandatory启用加密（ODBC Driver 18+ 默认），strict仅用于 TDS 8.0 协议且始终校验服务器证书；
• trust_server_certificate：yes/no（默认no），仅在证书校验失败时才建议设为yes；encrypt=strict时该设置被忽略；
• query_timeout：SQL 查询超时秒数，默认 30，取值范围 1–300。

关键校验规则（config.py中validate_sql_endpoint_dependencies）：只要以下任一功能开启而sql_endpoint.enabled=false，配置校验会直接抛错拒绝：

• extract_views=True
• extract_schema启用且 method 为sql_analytics_endpoint
• usage.include_usage_statistics=True

因为这些功能都要通过 SQL Analytics Endpoint 查询（INFORMATION_SCHEMA.VIEWS、INFORMATION_SCHEMA.COLUMNS、queryinsights.exec_requests_history）。

Schema 提取原理

连接器从 SQL Analytics Endpoint 提取列级元数据（列名、数据类型、可空性、序号位置），覆盖 Lakehouse 与 Warehouse 中的表。其工作流程为：

1. 端点发现：对每个 Lakehouse/Warehouse 从 Fabric API 自动获取 SQL Analytics Endpoint URL，格式为<unique-identifier>.datawarehouse.fabric.microsoft.com，无法仅凭 workspace_id 拼接得到；若 API 取不到端点 URL，该对象的 Schema 提取会失败；
2. 认证：复用 REST API 的同一套 Azure 凭据，注入 Azure AD token；
3. 连接：通过 ODBC 使用发现的端点 URL 建立连接；
4. 查询：查询INFORMATION_SCHEMA.COLUMNS提取列元数据；
5. 类型映射：SQL Server 数据类型经 DataHub 标准类型映射系统自动转换为 DataHub 类型。

注意：与旧版 Power BI Premium 端点不同，Fabric SQL Analytics Endpoint不支持 fallback 连接串，端点必须从 API 获取。禁用 Schema 提取可写：

source: type: fabric-onelake config: extract_schema: enabled: false

视图提取与血缘

视图在 Lakehouse 与 Warehouse 中被摄取为带View子类型的 DataHubDataset实体，每个视图数据集包含：

• 列级 Schema 元数据（与表共用INFORMATION_SCHEMA.COLUMNS查询结果，不额外增加查询）；
• 原始视图定义（CREATE VIEWSQL，取自INFORMATION_SCHEMA.VIEWS）；
• 由 SQL 解析聚合器（SqlParsingAggregator，在 source.py 中构造）从视图定义解析出的上游表血缘。

VIEW DEFINITION 权限（关键坑点）

读取视图定义需要 SQL Analytics Endpoint 上的VIEW DEFINITION权限。仅靠表摄取所用的工作区Viewer角色不够——Viewer 只授予db_datareader，会导致INFORMATION_SCHEMA.VIEWS.VIEW_DEFINITION返回NULL。该权限没有工作区级开关，只能二选一：

• 按湖仓/仓库授予VIEW DEFINITION（最小权限推荐，身份保持工作区 Viewer）：

GRANT VIEW DEFINITION ON DATABASE::<lakehouse_or_warehouse_name> TO [<service_principal_name>];

• 在工作区授予更高角色（Contributor、Member 或 Admin）。

若两者都不可行，可设置extract_views: false跳过视图摄取。以 Viewer 级别摄取视图时视图仍会出现，但血缘会缺失（定义为空）。

视图提取配置

source: type: fabric-onelake config: # View extraction is enabled by default. Set to false to skip views. extract_views: true # Filter views by name pattern. Format: 'schema.view' or just 'view' for default schema. view_pattern: allow: - ".*" deny: - ".*_internal" # View extraction requires the SQL Analytics Endpoint (enabled by default). sql_endpoint: enabled: true

视图提取流程：连接器查询INFORMATION_SCHEMA.VIEWS列出视图并捕获定义 → 按schema.view_name形式与view_pattern匹配过滤 → Schema 列复用表提取的同一查询结果 → 视图定义交给 SQL 解析聚合器推导视图 → 上游表血缘，视图 URN 与上游表 URN 在同一工作区与同一 item 内解析。

查询用量统计（Usage Statistics）

连接器通过 SQL Analytics Endpoint 读取每个 Lakehouse 与 Warehouse 的queryinsights.exec_requests_history视图来提取查询用量。每条捕获的查询由 SQL 解析聚合器解析后输出为：

• datasetUsageStatisticsaspects：查询次数、去重用户数、Top 用户、Top 字段，以及（启用时）Top SQL 查询，按配置的时间窗口分桶；
• operationaspects：逐查询的操作事件（insert、update、delete 等），在usage.include_operational_stats开启时输出；
• 当usage.include_queries开启时，还会为每条去重后的查询产出Query实体，使 SQL 成为 DataHub 中可检索的一等资产（Queries 标签页与独立 Query 页面）。

必需角色与数据特征

• Contributor 及以上角色：queryinsights的可见性按工作区隔离，摄取身份需要在每个目标工作区具备Contributor 或更高角色。Viewer 角色不够——queryinsights要求 Premium 容量工作区的 "contributor or higher" 权限，且完整查询文本（SQL 解析与列级用量所需）仅对 Admin、Member、Contributor 暴露；
• 30 天留存：Fabric 只保留queryinsights30 天，更早的历史无法回填，需据此设置usage.start_time；
• 延迟：新执行的查询最长约 15 分钟才会出现，高并发下延迟会增加；系统查询与用户上下文之外的查询不会出现。

用量统计配置

source: type: fabric-onelake config: # Usage extraction is enabled by default. Set to false to skip query usage. usage: include_usage_statistics: true # When true, the SQL filter excludes rows where status != 'Succeeded' # (canceled / failed queries are skipped at the source). skip_failed_queries: true # Optional: emit per-query operation aspects in addition to aggregated # datasetUsageStatistics. Defaults to true (inherited from BaseUsageConfig). include_operational_stats: true # Optional: include top SQL queries in the usage payload. include_top_n_queries: true top_n_queries: 10 # Optional: window the connector queries from queryinsights. Defaults to # the standard BaseUsageConfig "last bucket" window. Fabric retains # queryinsights for 30 days. bucket_duration: DAY # start_time: "2026-04-01T00:00:00Z" # end_time: "2026-05-01T00:00:00Z" # Usage extraction depends on the SQL Analytics Endpoint. extract_schema: enabled: true sql_endpoint: enabled: true

usage块支持所有标准BaseUsageConfig字段（bucket_duration、start_time、end_time、top_n_queries、format_sql_queries、include_top_n_queries、include_operational_stats、user_email_pattern等）。此外FabricUsageConfig（config.py）新增了三个 Fabric 专属字段：

启用有状态摄取时，用量时间窗口仅在一次成功运行后才做 checkpoint，因此部分成功或失败运行不会静默跳过下一个窗口——这一行为由RedundantUsageRunSkipHandler（source.py）实现，避免重复计算同一窗口。

Schemas-Enabled 与 Schemas-Disabled 湖仓

连接器自动处理两类湖仓，无需配置变更：

• Schemas-Enabled 湖仓：先通过 OneLake Delta Table APIs 列举 schema，再列举每个 schema 内的表，需要 Storage audience token（https://storage.azure.com/.default）；
• Schemas-Disabled 湖仓：使用标准 Fabric REST API 的/tables端点列出全部表；没有显式 schema 的表在 DataHub 中自动归入dboschema，使用 Power BI API scope token。

重要约定：DataHub 中所有表的 URN 都包含 schema，即使对 schemas-disabled 湖仓也是如此——无显式 schema 的表统一归一化为dbo。这一点与源码 constants.py 中定义的FABRIC_SQL_DEFAULT_SCHEMA = "dbo"一致，保证所有 Fabric 实体的 URN 结构一致。另外，_norm方法（source.py）在启用convert_urns_to_lowercase时会将 URN 与字段路径中的标识符转小写，以匹配 SQL 解析器（sqlglot）产出的视图血缘大小写，显示名称则保留原样。

有状态摄取与陈旧实体清理

stateful_ingestion: enabled: true remove_stale_metadata: true

启用后连接器会：

• 追踪所有已摄取的 workspaces、lakehouses、warehouses、schemas 与 tables；
• 移除 DataHub 中在 Fabric 已不存在的实体；
• 在多次摄取运行间维护状态。

限制与故障排查

以下限制在 fabric-onelake_post.md 中明确列出，部署前务必评估：

• 元数据同步延迟：SQL Analytics Endpoint 反映 Schema 变更可能存在延迟，新列或 Schema 修改可能需要几分钟到几小时才可见；
• 表缺失：某些表在 SQL 端点中不可见，原因包括不支持的数据类型、权限问题，以及超大型数据库中表数量上限；
• 优雅降级：某张表的 Schema 提取失败时，该表仍会被摄取（只是没有列元数据），不会导致整个摄取失败；
• 视图依赖 SQL 端点：视图仅通过 SQL Analytics Endpoint 发现。若sql_endpoint.enabled=false或某湖仓/仓库的端点不可达，该 item 中的视图不会被摄取；
• 用量统计 30 天留存：Fabricqueryinsights仅保留 30 天查询历史，无论usage.start_time如何配置，更早的用量都无法回填；
• 用量统计依赖 SQL 端点：sql_endpoint.enabled=false时配置校验会拒绝usage.include_usage_statistics=true；若某湖仓/仓库端点不可达，该 item 的用量会被跳过而不导致运行失败。

排查顺序：摄取失败时，先验证凭据、权限、连通性与范围过滤，再检查摄取日志中的源特定错误并相应调整配置。常见症状与对策包括：libodbc.so.2: cannot open shared object file（安装 unixODBC）、视图血缘缺失（授予VIEW DEFINITION或提升工作区角色）、用量统计为空（确认 Contributor 及以上角色且窗口落在 30 天留存内）。

参考文档

本模块的官方文档与示例位于仓库内：

• fabric-onelake_pre.md：概览、认证、权限、ODBC 环境、视图与用量前置说明；
• fabric-onelake_post.md：recipe 示例、Schema/视图/用量配置、限制与排查；
• fabric-onelake_recipe.yml：带完整注释的可运行模板；
• 源码：config.py、source.py、common/auth.py、constants.py。

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub