adf-master

Azure Data Factory 主知识库

已弃用功能

Apache Airflow 工作流编排管理器 - 已弃用

状态： 自 2025 年初起已弃用。仅现有客户可用。 退役日期： 尚未公布，但不允许进行新的部署。 影响： 新客户无法在 Azure Data Factory 中预配 Apache Airflow。

弃用详情：

• Apache Airflow 工作流编排管理器已弃用，尚未设定退役日期
• 仅现有部署可以继续使用此功能
• 无法在 ADF 中创建新的 Airflow 集成

迁移路径：

• 推荐： 迁移到原生支持 Airflow 的 Fabric Data Factory
• 替代方案： 使用独立的 Apache Airflow 部署（Azure Container Instances、AKS 或基于 VM 的部署）
• 替代方案： 将编排逻辑迁移到采用控制流活动的原生 ADF 管道

弃用原因：

• Microsoft 的重点已转向 Fabric Data Factory，将其打造为统一的数据集成平台
• Fabric 提供了更先进的编排功能，可取代 Airflow 集成
• ADF 中独立 Airflow 功能的采用率有限，且维护负担较重

所需操作：

• 如果在 ADF 中使用 Airflow：迁移到 Fabric Data Factory、独立 Airflow 或原生 ADF 模式
• 对于新项目：请勿在 ADF 中使用 Airflow
• 关注 Microsoft 公告，了解官方退役时间表

参考：

• Microsoft 路线图：https://www.directionsonmicrosoft.com/roadmaps/ref/azure-data-factory-roadmap/

功能更新（2025-2026）

Microsoft Fabric 集成（正式发布）

在 Fabric 中挂载 ADF：

• 无需重建，即可将现有 ADF 管道引入 Fabric 工作区
• 自 2025 年 6 月起正式发布
• 无缝集成支持 ADF 与 Fabric 混合工作流

跨工作区管道编排：

• 新的 Invoke Pipeline 活动支持跨平台调用
• 可在 Fabric、Azure Data Factory 和 Synapse 之间调用管道
• 支持托管 VNet，实现安全的跨工作区通信

变量库：

• 用于 CI/CD 自动化的环境特定变量
• 在工作区提升期间自动替换值
• 无需为每个环境单独维护参数文件

连接器增强：

• ServiceNow V2（V1 结束支持）
• 增强的 PostgreSQL 和 Snowflake 连接器
• 原生 OneLake 连接，实现零复制集成

CI/CD 的 Node.js 20.x 要求

重要： 截至 2025 年，npm 包 @microsoft/azure-data-factory-utilities 要求使用 Node.js 20.x

重大变更：

• 较旧的 Node.js 版本（14.x、16.x、18.x）可能导致包不兼容错误
• 更新 CI/CD 管道，使用 Node.js 20.x 或兼容版本

GitHub Actions：

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'

Azure DevOps：

- task: UseNode@1
  inputs:
    version: '20.x'

官方文档来源

Microsoft Learn 主要资源

主要文档中心：

• URL：https://learn.microsoft.com/en-us/azure/data-factory/
• 最后更新：2025 年 2 月
• 涵盖内容：完整的 ADF 文档，包括教程、概念、操作指南和参考资料
• 主要主题：管道、数据集、触发器、链接服务、数据流、集成运行时、监视

Azure Data Factory 简介：

• URL：https://learn.microsoft.com/en-us/azure/data-factory/introduction
• 概述：用于复杂混合 ETL、ELT 和数据集成项目的托管云服务
• 主要功能：90 多个内置连接器、无服务器架构、无代码 UI、统一监视

Context7 库文档

库 ID： /websites/learn_microsoft_en-us_azure_data-factory

• 信任评分：7.5
• 代码片段：10,839
• 主题：CI/CD、ARM 模板、管道模式、数据流、监视、故障排除

访问方式：

Use Context7 MCP tool to fetch latest documentation:
mcp__context7__get-library-docs:
  - context7CompatibleLibraryID: /websites/learn_microsoft_en-us_azure_data-factory
  - topic: "CI/CD continuous integration deployment pipelines ARM templates"
  - tokens: 8000

CI/CD 部署

详细的 CI/CD 内容，包括 ARM 模板生成、PrePostDeploymentScript.ps1 模式（部署前后停止/启动触发器，以及清理已删除的资源），以及完整的 GitHub Actions 和 Azure DevOps 管道 YAML，均位于 references/cicd-deployment.md。为 ADF 实例配置持续部署或排查部署管道问题时，请加载该参考文档。

故障排除资源

官方故障排除指南

URL： https://learn.microsoft.com/en-us/azure/data-factory/ci-cd-github-troubleshoot-guide 最后更新： 2025 年 1 月

涵盖的常见问题：

1. 模板参数验证错误
2. 无法更改 Integration Runtime 类型
3. ARM 模板大小超过 4MB 限制
4. Git 连接问题
5. 身份验证失败
6. 部署错误

诊断日志

启用诊断设置：

Azure Portal → Data Factory → Diagnostic settings → Add diagnostic setting
Send to: Log Analytics workspace

Logs to Enable:
- PipelineRuns
- TriggerRuns
- ActivityRuns
- SandboxPipelineRuns
- SandboxActivityRuns

用于故障排除的 Kusto 查询：

// Failed pipeline runs in last 24 hours
ADFPipelineRun
| where Status == "Failed"
| where TimeGenerated > ago(24h)
| project TimeGenerated, PipelineName, RunId, Status, ErrorMessage, Parameters
| order by TimeGenerated desc

// Failed CI/CD deployments
ADFActivityRun
| where ActivityType == "ExecutePipeline"
| where Status == "Failed"
| where TimeGenerated > ago(7d)
| project TimeGenerated, PipelineName, ActivityName, ErrorCode, ErrorMessage
| order by TimeGenerated desc

// Performance analysis
ADFActivityRun
| where TimeGenerated > ago(7d)
| extend DurationMinutes = datetime_diff('minute', End, Start)
| summarize AvgDuration = avg(DurationMinutes) by ActivityType, ActivityName
| where AvgDuration > 10
| order by AvgDuration desc

常见错误模式

错误：“Template parameters are not valid”

• 原因：已删除的触发器仍在参数中被引用
• 解决方案：重新生成 ARM 模板，或使用 PrePostDeploymentScript 清理

错误：“Updating property type is not supported”

• 原因：尝试更改 Integration Runtime 类型
• 解决方案：删除并重新创建 IR（不支持原位更新）

错误：“Operation timed out”

• 原因：网络连接问题、数据量过大或计算资源不足
• 解决方案：延长超时时间、优化查询、增加 DIU

错误：“Authentication failed”

• 原因：服务主体已过期、缺少权限或凭据错误
• 解决方案：验证凭据、检查角色分配，并在凭据过期时续期

最佳实践

存储库结构

推荐的文件夹布局：

repository-root/
├── adf-resources/          # ADF JSON files (if using npm approach)
│   ├── dataset/
│   ├── pipeline/
│   ├── trigger/
│   ├── linkedService/
│   └── integrationRuntime/
├── .github/
│   └── workflows/          # GitHub Actions workflows
│       ├── adf-build.yml
│       └── adf-deploy.yml
├── azure-pipelines/        # Azure DevOps pipelines
│   ├── build.yml
│   └── release.yml
├── parameters/             # Environment-specific parameters
│   ├── ARMTemplateParametersForFactory.dev.json
│   ├── ARMTemplateParametersForFactory.test.json
│   └── ARMTemplateParametersForFactory.prod.json
├── package.json            # npm configuration
└── README.md

Git 配置

仅在开发环境的 ADF 上配置 Git：

• 开发环境：集成 Git 以进行源代码管理
• 测试环境：仅通过 CI/CD 部署（不使用 Git）
• 生产环境：仅通过 CI/CD 部署（不使用 Git）

**理由：**防止在更高环境中意外进行手动更改

多环境策略

Environment Flow:
Dev (Git) → Build → Test → Approval → Production
            ↓
        ARM Templates

参数管理：

• 每个环境使用单独的参数文件
• 在 Azure Key Vault 中存储密钥
• 在参数文件中引用 Key Vault
• 切勿将密钥提交到源代码管理中

监控和警报

为以下情况设置警报：

• 构建管道失败
• 部署失败
• 管道运行失败
• 性能下降
• 成本异常

推荐工具：

• Azure Monitor（指标和警报）
• Log Analytics（Kusto 查询）
• Application Insights（用于自定义日志记录）
• Azure Advisor（优化建议）

其他资源

GitHub 存储库

Azure Data Factory 官方示例：

• URL： https://github.com/Azure/Azure-DataFactory
• 路径：SamplesV2/ContinuousIntegrationAndDelivery/
• 内容：PrePostDeploymentScript.Ver2.ps1、示例管道和文档

社区示例：

• 在 GitHub 上搜索“azure-data-factory-cicd”，查找实际示例
• 许多组织会发布其 CI/CD 模式供参考

社区支持

Microsoft Q&A：

• URL： https://learn.microsoft.com/en-us/answers/tags/130/azure-data-factory
• 社区活跃，Microsoft 员工会参与答复

Stack Overflow：

• 标签：azure-data-factory
• 拥有大量已解决问题的知识库

Azure 状态：

• URL： https://status.azure.com
• 查看服务中断和事件

何时获取最新信息

需要查阅最新文档的情形：

1. npm 包版本更新
2. 新的 ADF 功能或活动
3. ARM 模板架构变更
4. PrePostDeploymentScript 更新
5. 新的 GitHub Actions 或 Azure DevOps 任务
6. 破坏性变更或弃用

如何获取：

• 使用 WebFetch 查阅 Microsoft Learn 文章
• 在 npm 上检查最新的包版本
• 使用 Context7 全面了解相关主题
• 查看 Azure Data Factory GitHub，了解脚本更新

对于所有 Azure Data Factory 问题，请从此知识库开始查找。在做出生产环境决策时，务必通过最新的官方文档核实关键信息。

渐进式披露参考资料

如需详细的 JSON 架构和完整参考资料，请参阅：

• 活动类型：references/activity-types.md - 所有活动类型（Copy、ForEach、IfCondition、Switch、Until、Lookup、ExecutePipeline、WebActivity、DatabricksJob、SetVariable、AppendVariable、Wait、Fail、GetMetadata）的完整 JSON 架构
• 表达式函数：references/expression-functions.md - ADF 所有表达式函数（字符串、集合、逻辑、转换、数学、日期/时间、管道/活动引用）的完整参考
• 链接服务：references/linked-services.md - 所有连接器类型（Blob Storage、ADLS Gen2、Azure SQL、Synapse、Fabric Lakehouse/Warehouse、Databricks、Key Vault、REST、SFTP、Snowflake、PostgreSQL）的完整 JSON 配置
• 触发器：references/triggers.md - 计划触发器、滚动窗口触发器和事件触发器的完整 JSON 架构
• 数据集：references/datasets.md - 所有数据集类型及参数化模式的完整 JSON 架构

如需了解机器学习和分析模式，请参阅专用技能：

• 机器学习与分析：adf-master:adf-ml-analytics - Azure ML 管道、批处理终结点、Azure AI Services、Databricks ML/MLflow、SQL 到存储的归档，以及使用 Data Flows 进行特征工程