adf-validation-rules

Azure Data Factory の検証ルールと制限事項

🚨 重要：アクティビティのネストに関する制限

Azure Data Factory には、制御フローアクティビティの厳格なネストルールがあります。これらのルールに違反すると、パイプラインの実行に失敗したり、パイプラインを作成できなくなったりします。

ネストに対応している制御フローアクティビティ

次の 4 つの制御フローアクティビティは、アクティビティをネストできます。

• ForEach：コレクションを反復処理し、ループ内でアクティビティを実行します
• If Condition：真偽の評価に基づいて分岐します
• Until：タイムアウトオプション付きの do-until ループを実装します
• Switch：ケース条件に一致するアクティビティを評価します

✅ 許可されるネストの組み合わせ

親アクティビティ	含められるアクティビティ	備考
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	❌ 1 レベルのみです。Execute Pipeline の回避策を使用してください
Until	別の Until	❌ 1 レベルのみです。Execute Pipeline の回避策を使用してください
ForEach	Until	❌ 1 レベルのみです。Execute Pipeline の回避策を使用してください
Until	ForEach	❌ 1 レベルのみです。Execute Pipeline の回避策を使用してください

🚫 特定のアクティビティに関する制限

Validation アクティビティ：

• ❌ ネストされたアクティビティの中には配置できません
• ❌ 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
        ]
      }
    }
  ]
}

この方法が機能する理由：

• 各パイプラインでネストできるのは 1 レベルです
• Execute Pipeline によって新しいパイプラインコンテキストが作成されます
• 子パイプラインには独自のネストレベルの許容範囲が与えられます
• パイプラインを連鎖させることで、深さを無制限にできます

🔢 アクティビティとリソースの制限

パイプラインの制限

リソース	制限	備考
パイプラインあたりのアクティビティ数	80	コンテナー内の内部アクティビティを含みます
パイプラインあたりのパラメーター数	50	-
ForEach の同時反復数	50（最大）	batchCount プロパティで設定します
ForEach の項目数	100,000	-
Lookup アクティビティの行数	5,000	返される行の最大数
Lookup アクティビティのサイズ	4 MB	返されるデータの最大サイズ
Web アクティビティのタイムアウト	1 時間	Web アクティビティの既定のタイムアウト
Copy アクティビティのタイムアウト	7 日	最大実行時間

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 → 項目を一度に 1 つずつ実行します（遅いものの、予測しやすくなります）
• 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、マネージド ID、AAD）、ネットワーク構成、接続文字列のパターン）は、references/linked-services.md に記載されています。リンクされたサービスの JSON を作成または検証する際は、このリファレンスを読み込んでください。

🔍 データフローの制限事項

一般的な制限

• 列名の長さ：最大 128 文字
• 行サイズ：最大 1 MB（SQL など、一部のシンクでは上限がより低くなります）
• 文字列列のサイズ：シンクによって異なります（SQL：varchar は 8000、nvarchar は 4000）

変換固有の制限事項

変換	制限事項
Lookup	キャッシュサイズはクラスターのメモリによって制限されます
Join	大規模な結合ではメモリエラーが発生する場合があります
Pivot	一意の値は最大 10,000 個です
Window	大規模なデータセットではパーティション分割が必要です

パフォーマンスに関する考慮事項

• パーティション分割：変換の前に、大規模なデータセットは必ずパーティション分割してください
• ブロードキャスト：小規模なディメンションテーブルにはブロードキャストヒントを使用してください
• シンクの最適化：パフォーマンスを向上させるには、テーブルオプションで「Truncate」ではなく「Recreate」を有効にしてください

🛡️ パイプライン作成時の検証チェックリスト

パイプライン作成前

• アクティビティのネストが許可されている組み合わせに従っていることを確認する
• ForEach アクティビティにほかの ForEach/Until が含まれていないことを確認する
• If/Switch アクティビティに ForEach/Until/If/Switch が含まれていないことを確認する
• Validation アクティビティがパイプラインのルートレベルのみに配置されていることを確認する
• パイプラインあたりのアクティビティ総数が 80 未満であることを確認する
• 並列 ForEach 内に Set Variable アクティビティがないことを確認する

リンクされたサービスの検証

• Blob Storage：マネージド ID/サービスプリンシパルを使用する場合は、accountKind が設定されている
• SQL Database：認証方式がセキュリティ要件に適合している
• すべてのサービス：シークレットがハードコードされず、Key Vault に保存されている
• すべてのサービス：統合ランタイムの IP アドレスに対するファイアウォールルールが設定されている
• ネットワーク：VNet 統合を使用する場合は、プライベートエンドポイントが設定されている

アクティビティ構成の検証

• ForEach：並列実行の場合、batchCount が 50 以下である
• Lookup：クエリの結果が 5000 行未満かつ 4 MB 未満である
• Copy：DIU が適切に設定されている（Azure IR の場合は 2～256）
• Copy：大規模なデータ移動ではステージングが有効になっている
• すべてのアクティビティ：タイムアウト値が想定される実行時間に適している
• すべてのアクティビティ：一時的な障害に備えて再試行ロジックが設定されている

データフローの検証

• 列名が 128 文字以下である
• ソースクエリが 1 行あたり 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、strict モードでは 30 で警告）

3. 変数スコープ違反：

   • 並列 ForEach 内の SetVariable（競合状態の原因になります）
   • AppendVariable と SetVariable の適切な使い分け

4. データセット構成の問題：

   • ファイルベースのデータセットで fileName または wildcardFileName が未設定
   • AzureBlobFSLocation で必須の fileSystem プロパティが未設定
   • DelimitedText、Json、Parquet タイプで必須プロパティが未設定

5. Copy アクティビティの検証：

   • ソース／シンクのタイプとデータセットタイプの互換性
   • 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. 警告を追加で確認できるよう、開発中は strict モードを使用する
4. 一括変更や生成されたパイプラインの後に、再検証する
5. 警告を無視する必要がある場合は、検証の例外を文書化する
6. 同じミスの繰り返しを防ぐため、検証結果をチームで共有する

🚨 重要：適用プロトコル

ADF パイプラインを作成または変更する場合：

1. 許可／禁止の表に照らして、アクティビティのネストを必ず検証する
2. 禁止されたネストの組み合わせを作成しようとする試みを拒否する
3. 複雑なネストが必要な場合は、Execute Pipeline による回避策を提案する
4. リンクされたサービスの認証方式がコネクタのタイプと一致することを検証する
5. すべての制限（アクティビティ、パラメーター、ForEach の反復回数など）を確認する
6. 必須プロパティ（マネージド ID の 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）の完全なリファレンス