adf-validation-rules

Azure Data Factory 验证规则和限制

🚨 严重：活动嵌套限制

Azure Data Factory 对控制流活动有严格的嵌套规则。违反这些规则会导致管道运行失败或无法创建管道。

支持嵌套活动的控制流活动

以下四种控制流活动支持嵌套活动：

• ForEach：遍历集合并在循环中执行活动
• If Condition：根据真假值评估结果进行分支
• Until：实现带超时选项的 do-until 循环
• Switch：执行与 case 条件匹配的活动

✅ 允许的嵌套组合

父活动	可包含	备注
ForEach	If Condition	✅ 允许
ForEach	Switch	✅ 允许
Until	If Condition	✅ 允许
Until	Switch	✅ 允许

❌ 禁止的嵌套组合

父活动	不能包含	原因
If Condition	ForEach	❌ 不支持——请使用 Execute Pipeline 作为变通方案
If Condition	Switch	❌ 不支持——请使用 Execute Pipeline 作为变通方案
If Condition	Until	❌ 不支持——请使用 Execute Pipeline 作为变通方案
If Condition	另一个 If	❌ If 中不能嵌套 If
Switch	ForEach	❌ 不支持——请使用 Execute Pipeline 作为变通方案
Switch	If Condition	❌ 不支持——请使用 Execute Pipeline 作为变通方案
Switch	Until	❌ 不支持——请使用 Execute Pipeline 作为变通方案
Switch	另一个 Switch	❌ Switch 中不能嵌套 Switch
ForEach	另一个 ForEach	❌ 仅支持单层——请使用 Execute Pipeline 作为变通方案
Until	另一个 Until	❌ 仅支持单层——请使用 Execute Pipeline 作为变通方案
ForEach	Until	❌ 仅支持单层——请使用 Execute Pipeline 作为变通方案
Until	ForEach	❌ 仅支持单层——请使用 Execute Pipeline 作为变通方案

🚫 特殊活动限制

验证活动：

• ❌ 不能放在任何嵌套活动中
• ❌ 不能在 ForEach、If、Switch 或 Until 活动中使用
• ✅ 只能放在管道根级别

🔧 变通方案：Execute Pipeline 模式

对于禁止的嵌套组合，唯一受支持的变通方案：

不要直接嵌套，而应使用 Execute Pipeline Activity 调用子管道：

{
  "name": "ParentPipeline_WithIfCondition",
  "activities": [
    {
      "name": "IfCondition_Parent",
      "type": "IfCondition",
      "typeProperties": {
        "expression": "@equals(pipeline().parameters.ProcessData, 'true')",
        "ifTrueActivities": [
          {
            "name": "ExecuteChildPipeline_WithForEach",
            "type": "ExecutePipeline",
            "typeProperties": {
              "pipeline": {
                "referenceName": "ChildPipeline_ForEachLoop",
                "type": "PipelineReference"
              },
              "parameters": {
                "ItemList": "@pipeline().parameters.Items"
              }
            }
          }
        ]
      }
    }
  ]
}

子管道结构：

{
  "name": "ChildPipeline_ForEachLoop",
  "parameters": {
    "ItemList": {"type": "array"}
  },
  "activities": [
    {
      "name": "ForEach_InChildPipeline",
      "type": "ForEach",
      "typeProperties": {
        "items": "@pipeline().parameters.ItemList",
        "activities": [
          // Your ForEach logic here
        ]
      }
    }
  ]
}

此方法有效的原因：

• 每个管道都可以有一层嵌套
• Execute Pipeline 会创建新的管道上下文
• 子管道拥有独立的嵌套层级额度
• 通过管道链式调用，可实现无限嵌套深度

🔢 活动和资源限制

管道限制

资源	限制	备注
每个管道的活动数	80	包括容器中的内部活动
每个管道的参数数	50	-
ForEach 并发迭代数	50（最大值）	通过 batchCount 属性设置
ForEach 项目数	100,000	-
Lookup 活动行数	5,000	返回的最大行数
Lookup 活动大小	4 MB	返回数据的最大大小
Web 活动超时	1 hour	Web 活动的默认超时时间
Copy 活动超时	7 days	最大执行时间

ForEach 活动配置

{
  "name": "ForEachActivity",
  "type": "ForEach",
  "typeProperties": {
    "items": "@pipeline().parameters.ItemList",
    "isSequential": false,  // false = parallel execution
    "batchCount": 50,       // Max 50 concurrent iterations
    "activities": [
      // Nested activities
    ]
  }
}

重要注意事项：

• isSequential: true → 一次执行一项（速度较慢，但结果可预测）
• isSequential: false → 并行执行最多 batchCount 项
• 无论设置如何，batchCount 最大值均为 50
• 并行 ForEach 中不能使用 Set Variable 活动（变量作用域为管道级别）

Set Variable 活动限制

❌ 不能在 isSequential: false 的 ForEach 中使用 Set Variable

• 原因：变量的作用域是管道级，而非 ForEach 级
• 多个并行迭代会导致竞态条件
• ✅ 替代方案：使用数组类型的 Append Variable，或采用顺序执行

📊 链接服务验证（Azure Blob、Azure SQL）

ADF 链接服务（Azure Blob Storage 和 Azure SQL Database）的详细验证规则和模板——包括身份验证类型（密钥、SAS、托管标识、AAD）、网络配置和连接字符串模式——位于 references/linked-services.md。编写或验证链接服务 JSON 时，请加载该参考文件。

🔍 数据流限制

一般限制

• 列名长度：最多 128 个字符
• 行大小：最多 1 MB（某些接收器（如 SQL）限制更低）
• 字符串列大小：因接收器而异（SQL：varchar 为 8000，nvarchar 为 4000）

特定转换限制

转换	限制
Lookup	缓存大小受集群内存限制
Join	大型联接可能导致内存错误
Pivot	最多 10,000 个唯一值
Window	大型数据集需要分区

性能注意事项

• 分区：转换大型数据集前，始终先进行分区
• 广播：对小型维度表使用广播提示
• 接收器优化：启用表选项“Recreate”而非“Truncate”，以获得更佳性能

🛡️ 创建管道的验证清单

创建管道前

• 验证活动嵌套符合允许的组合
• 检查 ForEach 活动中不包含其他 ForEach/Until
• 验证 If/Switch 活动中不包含 ForEach/Until/If/Switch
• 确保 Validation 活动仅位于管道根级别
• 确认每个管道的活动总数 < 80
• 验证并行 ForEach 中没有 Set Variable 活动

链接服务验证

• Blob Storage：使用托管标识/服务主体时，已设置 accountKind
• SQL Database：身份验证方法符合安全要求
• 所有服务：机密存储在 Key Vault 中，而非硬编码
• 所有服务：已为集成运行时 IP 配置防火墙规则
• 网络：使用 VNet 集成时，已配置专用终结点

活动配置验证

• ForEach：并行执行时，batchCount ≤ 50
• Lookup：查询返回 < 5000 行且数据量 < 4 MB
• Copy：已适当配置 DIU（Azure IR 为 2-256）
• Copy：已为大型数据移动启用暂存
• 所有活动：超时值适合预期执行时间
• 所有活动：已为瞬时故障配置重试逻辑

数据流验证

• 列名 ≤ 128 个字符
• 源查询返回的每行数据不超过 1 MB
• 已为大型数据集配置分区
• 接收器具有适当的架构和数据类型映射
• 已配置暂存链接服务，以获得最佳性能

🔍 自动验证脚本

重要：在提交或部署 ADF 管道前，务必运行自动验证！

adf-master 插件包含全面的 PowerShell 验证脚本，用于检查上述所有规则和限制。

使用验证脚本

位置： ${CLAUDE_PLUGIN_ROOT}/scripts/validate-adf-pipelines.ps1

基本用法：

# From the root of your ADF repository
pwsh -File validate-adf-pipelines.ps1

使用自定义路径：

pwsh -File validate-adf-pipelines.ps1 `
    -PipelinePath "path/to/pipeline" `
    -DatasetPath "path/to/dataset"

使用严格模式（额外警告）：

pwsh -File validate-adf-pipelines.ps1 -Strict

脚本验证的内容

自动化验证脚本会检查 Microsoft 官方 @microsoft/azure-data-factory-utilities 包不会验证的问题：

1. 活动嵌套违规：

   • ForEach → ForEach、Until、Validation
   • Until → Until、ForEach、Validation
   • IfCondition → ForEach、If、IfCondition、Switch、Until、Validation
   • Switch → ForEach、If、IfCondition、Switch、Until、Validation

2. 资源限制：

   • 管道活动数量（最多 120 个，达到 100 个时发出警告）
   • 管道参数数量（最多 50 个）
   • 管道变量数量（最多 50 个）
   • ForEach batchCount 限制（最多 50 个，严格模式下达到 30 个时发出警告）

3. 变量作用域违规：

   • 在并行 ForEach 中使用 SetVariable（会导致竞态条件）
   • 正确使用 AppendVariable 与 SetVariable

4. 数据集配置问题：

   • 基于文件的数据集缺少 fileName 或 wildcardFileName
   • AzureBlobFSLocation 缺少必需的 fileSystem 属性
   • DelimitedText、Json、Parquet 类型缺少必需属性

5. 复制活动验证：

   • 源/接收器类型与数据集类型的兼容性
   • Lookup 活动 firstRowOnly=false 警告（5000 行/4MB 限制）
   • Blob 文件依赖项（additionalColumns 日志记录模式）

与 CI/CD 集成

GitHub Actions 示例：

- name: Validate ADF Pipelines
  run: |
    pwsh -File validate-adf-pipelines.ps1 -PipelinePath pipeline -DatasetPath dataset
  shell: pwsh

Azure DevOps 示例：

- task: PowerShell@2
  displayName: 'Validate ADF Pipelines'
  inputs:
    filePath: 'validate-adf-pipelines.ps1'
    arguments: '-PipelinePath pipeline -DatasetPath dataset'
    pwsh: true

命令参考

使用 /adf-validate 命令，在正确的指引下运行验证脚本：

/adf-validate

此命令将：

1. 检测你的 ADF 存储库结构
2. 使用适当的路径运行验证脚本
3. 解析并解释发现的错误或警告
4. 针对每项违规提供具体解决方案
5. 根据结果建议后续操作
6. 提供 CI/CD 集成模式建议

退出代码

• 0：验证通过（无错误）
• 1：验证失败（发现错误——请勿部署）

最佳实践

1. 每次提交前都运行验证，及早发现问题
2. 将验证添加到 CI/CD 管道，防止无效部署
3. 在开发期间使用严格模式，获取额外警告
4. 批量更改或生成管道后重新验证
5. 如果必须忽略警告，请记录验证例外情况
6. 与团队分享验证结果，避免重复犯错

🚨 关键：强制执行协议

创建或修改 ADF 管道时：

1. 始终验证活动嵌套是否符合允许/禁止表
2. 拒绝任何创建禁止嵌套组合的尝试
3. 建议使用 Execute Pipeline 解决复杂的嵌套需求
4. 验证链接服务的身份验证是否与连接器类型匹配
5. 检查所有限制（活动、参数、ForEach 迭代次数等）
6. 确认已设置必需属性（例如，托管标识所需的 accountKind）
7. 警告用户注意所用连接器特有的常见问题

验证响应示例：

❌ INVALID PIPELINE STRUCTURE DETECTED:

Issue: ForEach activity contains another ForEach activity
Location: Pipeline "PL_DataProcessing" → ForEach "OuterLoop" → ForEach "InnerLoop"

This violates Azure Data Factory nesting rules:
- ForEach activities support only a SINGLE level of nesting
- You CANNOT nest ForEach within ForEach

✅ RECOMMENDED SOLUTION:
Use the Execute Pipeline pattern:
1. Create a child pipeline with the inner ForEach logic
2. Replace the inner ForEach with an Execute Pipeline activity
3. Pass required parameters to the child pipeline

Would you like me to generate the refactored pipeline structure?

📚 参考文档

Microsoft Learn 官方资源：

• 活动嵌套：https://learn.microsoft.com/en-us/azure/data-factory/concepts-nested-activities
• Blob Storage 连接器：https://learn.microsoft.com/en-us/azure/data-factory/connector-azure-blob-storage
• SQL Database 连接器：https://learn.microsoft.com/en-us/azure/data-factory/connector-azure-sql-database
• 管道限制：https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits#data-factory-limits

最后更新： 2025-01-24（基于 Microsoft 官方文档）

在创建或修改任何 Azure Data Factory 管道之前，必须查阅此验证规则技能，以确保符合平台限制和最佳实践。

渐进式披露参考资料

有关详细的验证矩阵和资源限制，请参阅：

• 嵌套规则：references/nesting-rules.md - 允许和禁止的活动嵌套组合及其变通模式的完整矩阵
• 资源限制：references/resource-limits.md - 所有 ADF 限制（管道、活动、触发器、数据流、集成运行时、表达式、API）的完整参考