Azure Data Factory および Synapse Analytics パイプラインでのコピー アクティビティのフォールト トレランス

適用対象: Azure Data Factory Azure Synapse Analytics

ソース ストアからコピー先ストアにデータをコピーする場合は、データ移動中のエラーによる中断を防止するために、コピー アクティビティによって特定のレベルのフォールト トレランスが提供されます。 たとえば、ソース ストアからコピー先ストアに数百万の行をコピーしているとします。コピー先のデータベースには主キーが作成されていますが、ソース データベースには主キーが定義されていません。 ソースからコピー先への重複する行のコピーが発生した場合、コピー先のデータベースで PK 違反のエラーが発生します。 このとき、コピー アクティビティには、このようなエラーを処理する方法が 2 つ用意されています。

• エラーが発生したら直ちに、コピー アクティビティを中止できます。
• フォールト トレランスを有効にして、互換性のないデータをスキップすることで、残りの部分を引き続きコピーできます。 たとえば今回の場合であれば、重複する行をスキップします。 また、コピー アクティビティ内のセッション ログを有効にすることで、スキップされたデータをログに記録することもできます。 詳細については、「コピー アクティビティのセッション ログ」を参照してください。

バイナリ ファイルのコピー

このサービスでは、バイナリ ファイルをコピーする場合、次のフォールト トレランス シナリオがサポートされます。 次のシナリオにおいて、コピー アクティビティを中止するか、残りのコピーを続行するかを選択できます。

1. このサービスによってコピーされるファイルが、同時に他のアプリケーションによって削除されている。
2. 一部の特定のフォルダーまたはファイルの ACL には構成されている接続情報より高いアクセス許可レベルが必要なため、それらのファイルまたはフォルダーではこのサービスのアクセスが許可されない。
3. データ整合性の検証設定を有効にしている場合、ソース ストアとコピー先ストアの間で 1 つ以上のファイルの整合性が検証されない。

UI を使用してフォールト トレランスを有効にする

UI を使用してパイプライン内の Copy アクティビティでフォールト トレランスを構成するには、次の手順を実行します。

1. パイプラインの Copy アクティビティ をまだ作成していない場合は、パイプラインの [アクティビティ] ウィンドウで Copy を検索し、[データのコピー] アクティビティをパイプライン キャンバスにドラッグします。

2. キャンバス上で新しい [データのコピー] アクティビティ (まだ選択されていない場合)、その [設定] タブの順に選択して、フォールト トレランスを構成します。

   

構成

ストレージ ストア間でバイナリ ファイルをコピーする場合、次のようにフォールト トレランスを有効にすることができます。

{
  "name": "CopyActivityFaultTolerance",
  "type": "Copy",
  "typeProperties": {
    "source": {
      "type": "BinarySource",
      "storeSettings": {
        "type": "AzureDataLakeStoreReadSettings",
        "recursive": true
      }
    },
    "sink": {
      "type": "BinarySink",
      "storeSettings": {
        "type": "AzureDataLakeStoreWriteSettings"
      }
    },
    "skipErrorFile": {
      "fileMissing": true,
      "fileForbidden": true,
      "dataInconsistency": true,
      "invalidFileName": true
    },
    "validateDataConsistency": true,
    "logSettings": {
      "enableCopyActivityLog": true,
      "copyActivityLogSettings": {
        "logLevel": "Warning",
        "enableReliableLogging": false
      },
      "logLocationSettings": {
        "linkedServiceName": {
          "referenceName": "ADLSGen2",
          "type": "LinkedServiceReference"
        },
        "path": "sessionlog/"
      }
    }
  }
}

監視

コピー アクティビティからの出力

各コピー アクティビティの実行の出力によって、読み取り、書き込み、およびスキップされたファイルの数を取得できます。

"output": {
            "dataRead": 695,
            "dataWritten": 186,
            "filesRead": 3,  
            "filesWritten": 1, 
            "filesSkipped": 2, 
            "throughput": 297,
            "logFilePath": "myfolder/a84bf8d4-233f-4216-8cb5-45962831cd1b/",
            "dataConsistencyVerification": 
           { 
                "VerificationResult": "Verified", 
                "InconsistentData": "Skipped" 
           } 
        }

コピー アクティビティからのセッション ログ

スキップされたファイル名をログに記録するように構成した場合は、次のパスからログ ファイルを見つけることができます: https://[your-blob-account].blob.core.windows.net/[path-if-configured]/copyactivity-logs/[copy-activity-name]/[copy-activity-run-id]/[auto-generated-GUID].csv。

ログ ファイルは csv ファイルである必要があります。 ログ ファイルのスキーマは次のとおりです。

ログ ファイルの例を次に示します。

Timestamp,Level,OperationName,OperationItem,Message 
2020-03-24 05:35:41.0209942,Warning,FileSkip,"bigfile.csv","File is skipped after read 322961408 bytes: ErrorCode=UserErrorSourceBlobNotExist,'Type=Microsoft.DataTransfer.Common.Shared.HybridDeliveryException,Message=The required Blob is missing. ContainerName: https://transferserviceonebox.blob.core.windows.net/skipfaultyfile, path: bigfile.csv.,Source=Microsoft.DataTransfer.ClientLibrary,'." 
2020-03-24 05:38:41.2595989,Warning,FileSkip,"3_nopermission.txt","File is skipped after read 0 bytes: ErrorCode=AdlsGen2OperationFailed,'Type=Microsoft.DataTransfer.Common.Shared.HybridDeliveryException,Message=ADLS Gen2 operation failed for: Operation returned an invalid status code 'Forbidden'. Account: 'adlsgen2perfsource'. FileSystem: 'skipfaultyfilesforbidden'. Path: '3_nopermission.txt'. ErrorCode: 'AuthorizationPermissionMismatch'. Message: 'This request is not authorized to perform this operation using this permission.'. RequestId: '35089f5d-101f-008c-489e-01cce4000000'..,Source=Microsoft.DataTransfer.ClientLibrary,''Type=Microsoft.DataTransfer.Common.Shared.HybridDeliveryException,Message=Operation returned an invalid status code 'Forbidden',Source=,''Type=Microsoft.Azure.Storage.Data.Models.ErrorSchemaException,Message='Type=Microsoft.Azure.Storage.Data.Models.ErrorSchemaException,Message=Operation returned an invalid status code 'Forbidden',Source=Microsoft.DataTransfer.ClientLibrary,',Source=Microsoft.DataTransfer.ClientLibrary,'." 

上記のログから、このサービスが bigfile.csv をコピーしているときに別のアプリケーションがこのファイルを削除したため、このファイルがスキップされたことを確認できます。 また、3_nopermission.txt は、アクセス許可の問題のためにこのサービスがアクセスを許可されていないため、スキップされました。

表形式データのコピー

サポートされるシナリオ

コピー アクティビティでは、互換性のない表形式データを検出、スキップ、およびログ記録するための 3 つのシナリオがサポートされます。

• ソース データの型とシンクのネイティブ型の間の非互換性。

  次に例を示します。Blob Storage 内の CSV ファイルから、INT 型の 3 つの列を含むスキーマ定義を持つ SQL データベースにデータをコピーします。 数値データを含む CSV ファイルの行 (123,456,789 など) はシンク ストアに正常にコピーされます。 ただし、数値以外を含む行 (123,456, abc など) は互換性のない行として検出され、スキップされます。

• ソースとシンクの間での列数の不一致。

  次に例を示します。Blob Storage 内の CSV ファイルから、6 つの列を含むスキーマ定義を持つ SQL データベースにデータをコピーします。 6 つの列を含む CSV ファイルの行が、シンク ストアに正常にコピーされます。 含まれる列の数が 6 を超える CSV ファイルの行は、互換性のないものとして検出され、スキップされます。

• SQL Server/Azure SQL Database/Azure Cosmos DB への書き込み時の主キー違反。

  次に例を示します。データを SQL サーバーから SQL データベースにコピーします。 シンクの SQL データベースでは主キーが定義されていますが、ソースの SQL サーバーではそのような主キーは定義されていません。 ソースに存在する重複している行は、シンクにはコピーできません。 コピー アクティビティでは、ソース データの最初の行のみがシンクにコピーされます。 それ以降のソース行に重複している主キーの値が含まれている場合、互換性のないものとして検出され、スキップされます。

構成

次の例では、コピー アクティビティで互換性のない行をスキップするように構成する JSON 定義について説明します。

"typeProperties": { 
    "source": { 
        "type": "AzureSqlSource" 
    }, 
    "sink": { 
        "type": "AzureSqlSink" 
    }, 
    "enableSkipIncompatibleRow": true, 
    "logSettings": {
        "enableCopyActivityLog": true,
        "copyActivityLogSettings": {            
            "logLevel": "Warning",
            "enableReliableLogging": false
        },
        "logLocationSettings": {
            "linkedServiceName": {
               "referenceName": "ADLSGen2",
               "type": "LinkedServiceReference"
            },
            "path": "sessionlog/"
        }
    } 
}, 

スキップされた行を監視する

コピー アクティビティの実行が完了したら、コピー アクティビティの出力で、スキップされた行の数を次のように確認できます。

"output": {
            "dataRead": 95,
            "dataWritten": 186,
            "rowsCopied": 9,
            "rowsSkipped": 2,
            "copyDuration": 16,
            "throughput": 0.01,
            "logFilePath": "myfolder/a84bf8d4-233f-4216-8cb5-45962831cd1b/",
            "errors": []
        },

互換性のない行をログに記録するように構成した場合は、次のパスからログ ファイルを見つけることができます: https://[your-blob-account].blob.core.windows.net/[path-if-configured]/copyactivity-logs/[copy-activity-name]/[copy-activity-run-id]/[auto-generated-GUID].csv。

ログ ファイルは csv ファイルになります。 ログ ファイルのスキーマは次のとおりです。

ログ ファイルの内容の例は次のとおりです。

Timestamp, Level, OperationName, OperationItem, Message
2020-02-26 06:22:32.2586581, Warning, TabularRowSkip, """data1"", ""data2"", ""data3""," "Column 'Prop_2' contains an invalid value 'data3'. Cannot convert 'data3' to type 'DateTime'." 
2020-02-26 06:22:33.2586351, Warning, TabularRowSkip, """data4"", ""data5"", ""data6"",", "Violation of PRIMARY KEY constraint 'PK_tblintstrdatetimewithpk'. Cannot insert duplicate key in object 'dbo.tblintstrdatetimewithpk'. The duplicate key value is (data4)." 

上記のサンプル ログ ファイルからは、ソース ストアからコピー先ストアへの型変換の問題により、1 行目の "data1, data2, data3" がスキップされたことがわかります。 別の行 "data4, data5, data6" は、ソース ストアからコピー先ストアへの PK 違反の問題によりスキップされました。

表形式データのコピー (レガシ):

次の方法は、表形式データのみをコピーする際にフォールト トレランスを有効にする従来の方法です。 新しいパイプラインまたはアクティビティを作成している場合は、代わりにこちらから始めることをお勧めします。

構成

次の例では、コピー アクティビティで互換性のない行をスキップするように構成する JSON 定義について説明します。

"typeProperties": {
    "source": {
        "type": "BlobSource"
    },
    "sink": {
        "type": "SqlSink",
    },
    "enableSkipIncompatibleRow": true,
    "redirectIncompatibleRowSettings": {
         "linkedServiceName": {
              "referenceName": "<Azure Storage or Data Lake Store linked service>",
              "type": "LinkedServiceReference"
            },
            "path": "redirectcontainer/erroroutput"
     }
}

スキップされた行を監視する

コピー アクティビティの実行が完了したら、コピー アクティビティの出力で、スキップされた行の数を次のように確認できます。

"output": {
            "dataRead": 95,
            "dataWritten": 186,
            "rowsCopied": 9,
            "rowsSkipped": 2,
            "copyDuration": 16,
            "throughput": 0.01,
            "redirectRowPath": "https://myblobstorage.blob.core.windows.net//myfolder/a84bf8d4-233f-4216-8cb5-45962831cd1b/",
            "errors": []
        },

互換性のない行をログに記録するように構成した場合は、パス https://[your-blob-account].blob.core.windows.net/[path-if-configured]/[copy-activity-run-id]/[auto-generated-GUID].csv でログ ファイルを見つけることができます。

ログ ファイルは、csv のファイル形式のみです。 スキップされた元のデータは、必要に応じて、列区切り記号にコンマを使用して記録されます。 非互換性の根本原因を確認できるように、ログ ファイルの元のソース データに加えて、"ErrorCode" および "ErrorMessage" という 2 つの列を追加しています。 ErrorCode および ErrorMessage は、二重引用符で囲まれます。

ログ ファイルの内容の例は次のとおりです。

data1, data2, data3, "UserErrorInvalidDataValue", "Column 'Prop_2' contains an invalid value 'data3'. Cannot convert 'data3' to type 'DateTime'."
data4, data5, data6, "2627", "Violation of PRIMARY KEY constraint 'PK_tblintstrdatetimewithpk'. Cannot insert duplicate key in object 'dbo.tblintstrdatetimewithpk'. The duplicate key value is (data4)."

関連するコンテンツ

コピー アクティビティの他の記事を参照してください。

• コピー アクティビティの概要
• コピー アクティビティのパフォーマンス