尧图网站建设 
DataHub 集成 Microsoft Fabric OneLakefabric-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提取查询用量统计与操作operationaspects自动探测并区分 schemas-enabled 与 schemas-disabled 湖仓选择对应 API 与 token audience提供面向 workspaces、lakehouses、warehouses、tables、views 的正则模式过滤支持有状态摄取stateful ingestion可清理 DataHub 中已不存在的陈旧实体支持Service Principal、Managed Identity、Azure CLI、DefaultAzureCredential四种 Azure 认证方式。从源码结构看该模块由client.pyFabric REST 与 OneLake API 客户端、schema_client.pySQL Analytics Endpoint 模式提取、usage.py用量统计、models.py数据模型与config.py配置校验协同实现。认证与前置条件四种认证方式连接器通过credential块选择认证方式对应实现为AzureCredentialConfig见 azure_auth.py方式适用场景配置值Service Principal生产环境authentication_method: service_principal需client_id/client_secret/tenant_idManaged IdentityAzure 托管部署VM、AKS、App Service 等authentication_method: managed_identity可选client_id用户分配Azure CLI本地开发authentication_method: cli需先执行az loginDefaultAzureCredential灵活环境authentication_method: default连接器内部通过FabricAuthHelpercommon/auth.py将 AzureTokenCredential转换为 Bearer Token并针对不同操作使用两套不同的 token audienceFabric REST APIhttps://api.fabric.microsoft.com使用 Power BI API scopehttps://analysis.windows.net/powerbi/api/.default用于列举 workspaces、lakehouses、warehouses 及基础表元数据OneLake Delta Table APIshttps://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.AllMicrosoft Entra 委托范围目标工作区中的Viewer 及以上角色。API 权限EntraWorkspace.Read.All委托——列举与读取工作区元数据所需或Workspace.ReadWrite.All委托。OneLake 数据访问权限schemas-enabled 湖仓若湖仓开启了 OneLake 安全设置需在湖仓项的 security settings 中授予Read / ReadWrite权限该权限独立于工作区角色需在 Fabric 门户的湖仓安全设置中单独管理。文档与源码均强调连接器会自动探测湖仓是否启用了 schema 并切换对应 API 端点与 token audience无需额外配置。为 Service Principal 授权在 Microsoft Entra IDAzure AD中注册应用授予 API 权限Azure Portal → App registrations → 你的应用 → API permissions添加Power BI Service → Delegated permissions →Workspace.Read.All必要时点击Grant admin consent分配工作区角色Fabric 门户中进入每个工作区 →Workspace settings → Access将服务主体添加为Viewer 及以上角色。为 Managed Identity 授权在 Azure 资源VM、AKS、App Service 等上启用系统分配托管身份将托管身份以Viewer 及以上角色加入目标 Fabric 工作区连接器会自动使用托管身份完成认证。SQL Analytics Endpoint 环境准备视图提取、Schema 列级元数据提取与用量统计都依赖 SQL Analytics Endpoint而这需要系统安装 ODBC 驱动。这是本模块最易踩坑的环境环节。1. 安装 ODBC 驱动管理器Ubuntu/Debiansudo apt-get update sudo apt-get install -y unixodbc unixodbc-devRHEL/CentOS/Fedora# RHEL/CentOS 7/8 sudo yum install -y unixODBC unixODBC-devel # Fedora / RHEL 9 sudo dnf install -y unixODBC unixODBC-develmacOSbrew install unixodbc2. 安装 Microsoft ODBC Driver 18 for SQL ServerUbuntu 20.04/22.04curl 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_EULAY apt-get install -y msodbcsql18RHEL/CentOS 7/8sudo curl -o /etc/yum.repos.d/mssql-release.repo https://packages.microsoft.com/config/rhel/$(rpm -E %{rhel})/mssql-release.repo sudo ACCEPT_EULAY yum install -y msodbcsql18RHEL 9 / Fedorasudo curl -o /etc/yum.repos.d/mssql-release.repo https://packages.microsoft.com/config/rhel/9/mssql-release.repo sudo ACCEPT_EULAY dnf install -y msodbcsql18macOSbrew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release brew update HOMEBREW_ACCEPT_EULAY brew install msodbcsql18 mssql-tools183. 验证驱动安装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基础 RecipeService Principalsource: 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:8080Managed 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:8080source: 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括号内为默认值参数类型 / 默认值说明credentialAzureCredentialConfigAzure 认证配置支持四种认证方式workspace_patternAllowDenyPattern全部允许按名称正则过滤工作区lakehouse_patternAllowDenyPattern全部允许过滤湖仓应用于通过 workspace_pattern 的工作区warehouse_patternAllowDenyPattern全部允许过滤数据仓库schema_patternAllowDenyPattern全部允许过滤 schema被拒绝的 schema 及其全部表/视图会被跳过table_patternAllowDenyPattern全部允许过滤表格式schema.table或tableview_patternAllowDenyPattern全部允许过滤视图格式schema.view或viewextract_lakehousesbooltrue是否提取湖仓及其表extract_warehousesbooltrue是否提取仓库及其表extract_viewsbooltrue是否提取视图及定义依赖 sql_endpointextract_schemasbooltrue是否提取 schema 容器为 false 时表直接挂在湖仓/仓库容器下api_timeoutint301–300REST API 调用超时秒extract_schemaExtractSchemaConfigenabledtrue, methodsql_analytics_endpointSchema 提取配置目前仅支持sql_analytics_endpoint一种方法sql_endpointSqlEndpointConfigenabledtrueSQL Analytics Endpoint 连接配置stateful_ingestion默认关闭有状态摄取与陈旧实体清理usageFabricUsageConfig默认开启查询用量统计配置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 Serverencrypt合法值为yes/no/mandatory/optional/strict。yes/mandatory启用加密ODBC Driver 18 默认strict仅用于 TDS 8.0 协议且始终校验服务器证书trust_server_certificateyes/no默认no仅在证书校验失败时才建议设为yesencryptstrict时该设置被忽略query_timeoutSQL 查询超时秒数默认 30取值范围 1–300。关键校验规则config.py中validate_sql_endpoint_dependencies只要以下任一功能开启而sql_endpoint.enabledfalse配置校验会直接抛错拒绝extract_viewsTrueextract_schema启用且 method 为sql_analytics_endpointusage.include_usage_statisticsTrue因为这些功能都要通过 SQL Analytics Endpoint 查询INFORMATION_SCHEMA.VIEWS、INFORMATION_SCHEMA.COLUMNS、queryinsights.exec_requests_history。Schema 提取原理连接器从 SQL Analytics Endpoint 提取列级元数据列名、数据类型、可空性、序号位置覆盖 Lakehouse 与 Warehouse 中的表。其工作流程为端点发现对每个 Lakehouse/Warehouse 从 Fabric API 自动获取 SQL Analytics Endpoint URL格式为unique-identifier.datawarehouse.fabric.microsoft.com无法仅凭 workspace_id 拼接得到若 API 取不到端点 URL该对象的 Schema 提取会失败认证复用 REST API 的同一套 Azure 凭据注入 Azure AD token连接通过 ODBC 使用发现的端点 URL 建立连接查询查询INFORMATION_SCHEMA.COLUMNS提取列元数据类型映射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最小权限推荐身份保持工作区 ViewerGRANT 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: trueusage块支持所有标准BaseUsageConfig字段bucket_duration、start_time、end_time、top_n_queries、format_sql_queries、include_top_n_queries、include_operational_stats、user_email_pattern等。此外FabricUsageConfigconfig.py新增了三个 Fabric 专属字段字段默认值说明include_usage_statisticstrue用量提取总开关为 false 时不产出任何datasetUsageStatistics/operationaspectsskip_failed_queriestrue为 true 时 SQL 过滤掉status ! Succeeded的行取消/失败的查询在源头跳过include_queriestrue为每条去重查询产出Query实体需include_usage_statisticsTrue启用有状态摄取时用量时间窗口仅在一次成功运行后才做 checkpoint因此部分成功或失败运行不会静默跳过下一个窗口——这一行为由RedundantUsageRunSkipHandlersource.py实现避免重复计算同一窗口。Schemas-Enabled 与 Schemas-Disabled 湖仓连接器自动处理两类湖仓无需配置变更Schemas-Enabled 湖仓先通过 OneLake Delta Table APIs 列举 schema再列举每个 schema 内的表需要 Storage audience tokenhttps://storage.azure.com/.defaultSchemas-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.enabledfalse或某湖仓/仓库的端点不可达该 item 中的视图不会被摄取用量统计 30 天留存Fabricqueryinsights仅保留 30 天查询历史无论usage.start_time如何配置更早的用量都无法回填用量统计依赖 SQL 端点sql_endpoint.enabledfalse时配置校验会拒绝usage.include_usage_statisticstrue若某湖仓/仓库端点不可达该 item 的用量会被跳过而不导致运行失败。排查顺序摄取失败时先验证凭据、权限、连通性与范围过滤再检查摄取日志中的源特定错误并相应调整配置。常见症状与对策包括libodbc.so.2: cannot open shared object file安装 unixODBC、视图血缘缺失授予VIEW DEFINITION或提升工作区角色、用量统计为空确认 Contributor 及以上角色且窗口落在 30 天留存内。参考文档本模块的官方文档与示例位于仓库内fabric-onelake_pre.md概览、认证、权限、ODBC 环境、视图与用量前置说明fabric-onelake_post.mdrecipe 示例、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DataHub 集成 Microsoft Fabric OneLake：fabric-onelake 元数据摄取连接器实战指南
DataHub 集成 Microsoft Fabric OneLakefabric-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提取查询用量统计与操作operationaspects自动探测并区分 schemas-enabled 与 schemas-disabled 湖仓选择对应 API 与 token audience提供面向 workspaces、lakehouses、warehouses、tables、views 的正则模式过滤支持有状态摄取stateful ingestion可清理 DataHub 中已不存在的陈旧实体支持Service Principal、Managed Identity、Azure CLI、DefaultAzureCredential四种 Azure 认证方式。从源码结构看该模块由client.pyFabric REST 与 OneLake API 客户端、schema_client.pySQL Analytics Endpoint 模式提取、usage.py用量统计、models.py数据模型与config.py配置校验协同实现。认证与前置条件四种认证方式连接器通过credential块选择认证方式对应实现为AzureCredentialConfig见 azure_auth.py方式适用场景配置值Service Principal生产环境authentication_method: service_principal需client_id/client_secret/tenant_idManaged IdentityAzure 托管部署VM、AKS、App Service 等authentication_method: managed_identity可选client_id用户分配Azure CLI本地开发authentication_method: cli需先执行az loginDefaultAzureCredential灵活环境authentication_method: default连接器内部通过FabricAuthHelpercommon/auth.py将 AzureTokenCredential转换为 Bearer Token并针对不同操作使用两套不同的 token audienceFabric REST APIhttps://api.fabric.microsoft.com使用 Power BI API scopehttps://analysis.windows.net/powerbi/api/.default用于列举 workspaces、lakehouses、warehouses 及基础表元数据OneLake Delta Table APIshttps://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.AllMicrosoft Entra 委托范围目标工作区中的Viewer 及以上角色。API 权限EntraWorkspace.Read.All委托——列举与读取工作区元数据所需或Workspace.ReadWrite.All委托。OneLake 数据访问权限schemas-enabled 湖仓若湖仓开启了 OneLake 安全设置需在湖仓项的 security settings 中授予Read / ReadWrite权限该权限独立于工作区角色需在 Fabric 门户的湖仓安全设置中单独管理。文档与源码均强调连接器会自动探测湖仓是否启用了 schema 并切换对应 API 端点与 token audience无需额外配置。为 Service Principal 授权在 Microsoft Entra IDAzure AD中注册应用授予 API 权限Azure Portal → App registrations → 你的应用 → API permissions添加Power BI Service → Delegated permissions →Workspace.Read.All必要时点击Grant admin consent分配工作区角色Fabric 门户中进入每个工作区 →Workspace settings → Access将服务主体添加为Viewer 及以上角色。为 Managed Identity 授权在 Azure 资源VM、AKS、App Service 等上启用系统分配托管身份将托管身份以Viewer 及以上角色加入目标 Fabric 工作区连接器会自动使用托管身份完成认证。SQL Analytics Endpoint 环境准备视图提取、Schema 列级元数据提取与用量统计都依赖 SQL Analytics Endpoint而这需要系统安装 ODBC 驱动。这是本模块最易踩坑的环境环节。1. 安装 ODBC 驱动管理器Ubuntu/Debiansudo apt-get update sudo apt-get install -y unixodbc unixodbc-devRHEL/CentOS/Fedora# RHEL/CentOS 7/8 sudo yum install -y unixODBC unixODBC-devel # Fedora / RHEL 9 sudo dnf install -y unixODBC unixODBC-develmacOSbrew install unixodbc2. 安装 Microsoft ODBC Driver 18 for SQL ServerUbuntu 20.04/22.04curl 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_EULAY apt-get install -y msodbcsql18RHEL/CentOS 7/8sudo curl -o /etc/yum.repos.d/mssql-release.repo https://packages.microsoft.com/config/rhel/$(rpm -E %{rhel})/mssql-release.repo sudo ACCEPT_EULAY yum install -y msodbcsql18RHEL 9 / Fedorasudo curl -o /etc/yum.repos.d/mssql-release.repo https://packages.microsoft.com/config/rhel/9/mssql-release.repo sudo ACCEPT_EULAY dnf install -y msodbcsql18macOSbrew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release brew update HOMEBREW_ACCEPT_EULAY brew install msodbcsql18 mssql-tools183. 验证驱动安装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基础 RecipeService Principalsource: 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:8080Managed 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:8080source: 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括号内为默认值参数类型 / 默认值说明credentialAzureCredentialConfigAzure 认证配置支持四种认证方式workspace_patternAllowDenyPattern全部允许按名称正则过滤工作区lakehouse_patternAllowDenyPattern全部允许过滤湖仓应用于通过 workspace_pattern 的工作区warehouse_patternAllowDenyPattern全部允许过滤数据仓库schema_patternAllowDenyPattern全部允许过滤 schema被拒绝的 schema 及其全部表/视图会被跳过table_patternAllowDenyPattern全部允许过滤表格式schema.table或tableview_patternAllowDenyPattern全部允许过滤视图格式schema.view或viewextract_lakehousesbooltrue是否提取湖仓及其表extract_warehousesbooltrue是否提取仓库及其表extract_viewsbooltrue是否提取视图及定义依赖 sql_endpointextract_schemasbooltrue是否提取 schema 容器为 false 时表直接挂在湖仓/仓库容器下api_timeoutint301–300REST API 调用超时秒extract_schemaExtractSchemaConfigenabledtrue, methodsql_analytics_endpointSchema 提取配置目前仅支持sql_analytics_endpoint一种方法sql_endpointSqlEndpointConfigenabledtrueSQL Analytics Endpoint 连接配置stateful_ingestion默认关闭有状态摄取与陈旧实体清理usageFabricUsageConfig默认开启查询用量统计配置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 Serverencrypt合法值为yes/no/mandatory/optional/strict。yes/mandatory启用加密ODBC Driver 18 默认strict仅用于 TDS 8.0 协议且始终校验服务器证书trust_server_certificateyes/no默认no仅在证书校验失败时才建议设为yesencryptstrict时该设置被忽略query_timeoutSQL 查询超时秒数默认 30取值范围 1–300。关键校验规则config.py中validate_sql_endpoint_dependencies只要以下任一功能开启而sql_endpoint.enabledfalse配置校验会直接抛错拒绝extract_viewsTrueextract_schema启用且 method 为sql_analytics_endpointusage.include_usage_statisticsTrue因为这些功能都要通过 SQL Analytics Endpoint 查询INFORMATION_SCHEMA.VIEWS、INFORMATION_SCHEMA.COLUMNS、queryinsights.exec_requests_history。Schema 提取原理连接器从 SQL Analytics Endpoint 提取列级元数据列名、数据类型、可空性、序号位置覆盖 Lakehouse 与 Warehouse 中的表。其工作流程为端点发现对每个 Lakehouse/Warehouse 从 Fabric API 自动获取 SQL Analytics Endpoint URL格式为unique-identifier.datawarehouse.fabric.microsoft.com无法仅凭 workspace_id 拼接得到若 API 取不到端点 URL该对象的 Schema 提取会失败认证复用 REST API 的同一套 Azure 凭据注入 Azure AD token连接通过 ODBC 使用发现的端点 URL 建立连接查询查询INFORMATION_SCHEMA.COLUMNS提取列元数据类型映射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最小权限推荐身份保持工作区 ViewerGRANT 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: trueusage块支持所有标准BaseUsageConfig字段bucket_duration、start_time、end_time、top_n_queries、format_sql_queries、include_top_n_queries、include_operational_stats、user_email_pattern等。此外FabricUsageConfigconfig.py新增了三个 Fabric 专属字段字段默认值说明include_usage_statisticstrue用量提取总开关为 false 时不产出任何datasetUsageStatistics/operationaspectsskip_failed_queriestrue为 true 时 SQL 过滤掉status ! Succeeded的行取消/失败的查询在源头跳过include_queriestrue为每条去重查询产出Query实体需include_usage_statisticsTrue启用有状态摄取时用量时间窗口仅在一次成功运行后才做 checkpoint因此部分成功或失败运行不会静默跳过下一个窗口——这一行为由RedundantUsageRunSkipHandlersource.py实现避免重复计算同一窗口。Schemas-Enabled 与 Schemas-Disabled 湖仓连接器自动处理两类湖仓无需配置变更Schemas-Enabled 湖仓先通过 OneLake Delta Table APIs 列举 schema再列举每个 schema 内的表需要 Storage audience tokenhttps://storage.azure.com/.defaultSchemas-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.enabledfalse或某湖仓/仓库的端点不可达该 item 中的视图不会被摄取用量统计 30 天留存Fabricqueryinsights仅保留 30 天查询历史无论usage.start_time如何配置更早的用量都无法回填用量统计依赖 SQL 端点sql_endpoint.enabledfalse时配置校验会拒绝usage.include_usage_statisticstrue若某湖仓/仓库端点不可达该 item 的用量会被跳过而不导致运行失败。排查顺序摄取失败时先验证凭据、权限、连通性与范围过滤再检查摄取日志中的源特定错误并相应调整配置。常见症状与对策包括libodbc.so.2: cannot open shared object file安装 unixODBC、视图血缘缺失授予VIEW DEFINITION或提升工作区角色、用量统计为空确认 Contributor 及以上角色且窗口落在 30 天留存内。参考文档本模块的官方文档与示例位于仓库内fabric-onelake_pre.md概览、认证、权限、ODBC 环境、视图与用量前置说明fabric-onelake_post.mdrecipe 示例、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考