mcpField
F
fabric-onelake-2025

fabric-onelake-2025

github.com/josiahsiegel数据与数据库59158 次安装19 周前更新
代码仓库

关于 fabric-onelake-2025

介绍 Azure Data Factory 与 Microsoft Fabric Lakehouse、Warehouse 和 OneLake 集成的参考技能，面向构建数据管道的数据工程师，涵盖连接器活动、身份验证、集成模式和故障排查。

主要功能

  1. 01Lakehouse 与 Warehouse 连接器
  2. 02复制、查找和元数据活动
  3. 03托管标识身份验证指南
  4. 04OneLake 快捷方式与增量加载模式
  5. 05权限配置与故障排查

适用场景

  1. 01向 Fabric Lakehouse 复制数据
  2. 02加载并查询 Fabric Warehouse
  3. 03创建调用 Fabric 管道的数据工作流

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill fabric-onelake-2025

安装后在 Claude Code 中输入/fabric-onelake-2025确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
lakehouse-examples.md
onelake-patterns.md
warehouse-examples.md

详细介绍

Microsoft Fabric 与 Azure Data Factory 集成（2025）

概述

Microsoft Fabric 是一个统一的 SaaS 分析平台，整合了 Power BI、Azure Synapse Analytics 和 Azure Data Factory 的功能。ADF 为 Fabric Lakehouse 和 Fabric Warehouse 提供原生连接器，可在 ADF 与 Fabric 工作区之间无缝移动数据。

Microsoft Fabric Lakehouse 连接器

Fabric Lakehouse 连接器支持对 Microsoft Fabric Lakehouse 中的表和文件执行读取和写入操作。

支持的活动
活动支持
复制活动（源和接收器）是
查找活动是
获取元数据活动是
删除活动是
快速参考
  • 链接服务类型： Lakehouse
  • 身份验证： 托管标识（首选）或服务主体
  • 必需的 ID： workspaceId 和 artifactId
  • 接收器类型： LakehouseTableSink（表）、LakehouseFileSink（文件）
  • 源类型： LakehouseTableSource
  • 表操作选项： append 或 overwrite

查找工作区和项目 ID：

  1. 在浏览器中导航到 Fabric 工作区
  2. 从 URL 中复制工作区 ID：https://app.powerbi.com/groups/<workspaceId>/...
  3. 打开 Lakehouse 设置以查找项目 ID
  4. 或使用 Fabric REST API 枚举工作区项目

完整的链接服务、数据集和复制活动 JSON 示例，请参阅 references/lakehouse-examples.md。

Microsoft Fabric Warehouse 连接器

Fabric Warehouse 连接器在 Fabric 生态系统中提供基于 T-SQL 的数据仓库功能。

支持的活动
活动支持
复制活动（源和接收器）是
查找活动是
获取元数据活动是
脚本活动是
存储过程活动是
快速参考
  • 链接服务类型： Warehouse
  • 身份验证： 系统分配的托管标识（推荐）、用户分配的 MI 或服务主体
  • 必需的属性： endpoint、warehouse
  • 接收器类型： WarehouseSink
  • 写入行为： insert 或 upsert
  • 表选项： autoCreate（表不存在时创建）

完整的链接服务、复制活动、存储过程和脚本活动 JSON 示例，请参阅 references/warehouse-examples.md。

OneLake 集成模式

ADF 支持与 OneLake 集成的三种模式：

模式说明主要优势
ADLS Gen2 快捷方式通过 OneLake 快捷方式引用 ADLS 数据（零复制）无需重复数据
增量加载基于水印将数据增量复制到 Lakehouse高效更新
跨平台调用使用 InvokePipeline 活动调用 Fabric 管道混合编排

当数据已存在于 ADLS Gen2 中时，OneLake 快捷方式是首选方案——它无需移动数据即可即时实现零复制访问。只有在需要数据转换或格式转换时，才使用 ADF 复制活动。

三种模式的完整管道 JSON 示例，请参阅 references/onelake-patterns.md。

权限配置

Fabric 中的 Azure Data Factory 托管标识权限

对于 Fabric Lakehouse：

  1. 打开 Fabric 工作区
  2. 转到“工作区设置” ->“管理访问权限”
  3. 将 ADF 托管标识添加为参与者角色
  4. 或分配工作区管理员以获得完整访问权限

对于 Fabric Warehouse：

  1. 导航到 Warehouse SQL 终结点
  2. 执行 SQL 以创建用户：
CREATE USER [your-adf-name] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [your-adf-name];
ALTER ROLE db_datawriter ADD MEMBER [your-adf-name];
服务主体权限

应用注册设置：

  1. 在 Microsoft Entra ID 中注册应用
  2. 创建客户端机密（存储在 Key Vault 中）
  3. 将应用添加到 Fabric 工作区，并分配参与者角色
  4. 对于 Warehouse，按上述说明创建 SQL 用户

最佳实践（2025）

  1. 使用托管标识 —— 对于单个 ADF，使用系统分配的托管标识；对于多个 ADF，使用用户分配的托管标识。尽可能避免使用服务主体密钥。将所有机密存储在 Key Vault 中。

  2. 为大型加载启用暂存 —— 对于数据量超过 1 GB、复杂转换或加载到 Fabric Warehouse 的情况，请使用带压缩的暂存。

  3. 充分利用 OneLake 快捷方式 —— 使用 ADLS Gen2 -> OneLake Shortcut -> Direct Access，而不是 ADLS Gen2 -> Copy Activity -> Lakehouse。无需移动数据，即可立即使用，并降低成本。

  4. 监控 Fabric 容量单位（CU） —— 跟踪每次管道运行的 CU 消耗量、峰值用量和节流情况。通过增量加载、非高峰时段调度和适当设置并行度来优化。

  5. 使用表选项 AutoCreate —— 在 WarehouseSink 上设置 tableOption: "autoCreate"，以自动管理架构并加快开发。

  6. 实施错误处理 —— 为复制活动配置重试策略，并添加基于 WebActivity 的失败日志记录，设置 dependencyConditions: ["Failed"]。

常见问题和解决方案

问题错误消息解决方案
权限被拒绝"User does not have permission to access Fabric workspace"将 ADF 托管标识添加为 Contributor；对于 Warehouse，创建 SQL 用户；等待 5 分钟以使更改生效
找不到终结点"Unable to connect to endpoint"验证 workspaceId/artifactId；检查工作区 URL；确保 Lakehouse/Warehouse 未暂停
架构不匹配"Column types do not match"使用 tableOption: "autoCreate"，或在转换器中显式设置列映射
性能下降复制性能缓慢启用暂存，将 parallelCopies 提高到 4-8，将 DIUs 提高到 8-32，并检查 CU 节流情况

资源

渐进式披露参考

  • Lakehouse 示例：references/lakehouse-examples.md - 完整的链接服务、数据集、复制活动和查找活动 JSON 示例
  • Warehouse 示例：references/warehouse-examples.md - 完整的链接服务、复制活动、存储过程和脚本活动 JSON 示例
  • OneLake 模式：references/onelake-patterns.md - 用于快捷方式、增量加载和跨平台 Invoke Pipeline 的管道模式

评论

支持 Markdown