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

[アーティクル]
11/09/2023

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

企業向けのオールインワン分析ソリューション、Microsoft Fabric の Data Factory をお試しください。 Microsoft Fabric は、データ移動からデータサイエンス、リアルタイム分析、ビジネスインテリジェンス、レポートまで、あらゆるものをカバーしています。無料で新しい試用版を開始する方法について説明します。

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

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

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

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

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

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

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

パイプラインの Copy アクティビティをまだ作成していない場合は、パイプラインの [アクティビティ] ウィンドウで Copy を検索し、[データのコピー] アクティビティをパイプラインキャンバスにドラッグします。
キャンバス上で新しい [データのコピー] アクティビティ (まだ選択されていない場合)、その [設定] タブの順に選択して、フォールトトレランスを構成します。

構成

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

{
  "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/"
      }
    }
  }
}

プロパティ	説明	使用できる値	必須
skipErrorFile	データの移動中にスキップするエラーの種類を指定するプロパティのグループ。		いいえ
fileMissing	このサービスがコピー操作を実行しているときに他のアプリケーションによって削除されているファイルをスキップするかどうかを指定する、skipErrorFile プロパティバッグ内のキーと値のペアの 1 つ。 -True: 他のアプリケーションによって削除されているファイルをスキップして、残りの部分をコピーします。 - False: データ移動中にソースストアからいずれかのファイルが削除された場合、コピーアクティビティを中止します。このプロパティは既定で true に設定されていることに注意してください。	True(既定値) False	いいえ
fileForbidden	ファイルまたはフォルダーの ACL に、構成されている接続より高いアクセス許可レベルが必要なときに、これらの特定のファイルをスキップするかどうかを指定する、skipErrorFile プロパティバッグ内のキーと値のペアの 1 つ。 -True: そのファイルをスキップして、残りの部分をコピーします。 - False: フォルダーまたはファイルに対してアクセス許可の問題が発生した場合に、コピーアクティビティを中止します。	True False (既定値)	いいえ
dataInconsistency	ソースストアとコピー先ストアの間で整合性のないデータをスキップするかどうかを指定する、skipErrorFile プロパティバッグ内のキーと値のペアの 1 つ。 -True: 整合性のないデータをスキップして、残りの部分をコピーします。 -False: 整合性のないデータが見つかった場合、コピーアクティビティを中止します。このプロパティは、validateDataConsistency を True に設定した場合にのみ有効であることに注意してください。	True False (既定値)	いいえ
invalidFileName	保存先ストアに対してファイル名が無効な場合に特定のファイルをスキップするかどうかを決定する、skipErrorFile プロパティバッグ内のキーと値のペアの 1 つ。 -True: 無効なファイル名を持つファイルをスキップして、残りの部分をコピーします。 -False: ファイルに無効なファイル名が付けられている場合、コピーアクティビティを中止します。このプロパティは、任意のストレージストアからバイナリファイルを ADLS Gen2 にコピーする場合、またはバイナリファイルを AWS S3 から任意のストレージストアにコピーする場合に機能することに注意してください。	True False (既定値)	いいえ
logSettings	スキップされたオブジェクト名をログに記録するときに指定できるプロパティのグループ。		いいえ
linkedServiceName	セッションログファイルを格納するための、Azure Blob Storage または Azure Data Lake Storage Gen2 のリンクされたサービスです。	`AzureBlobStorage` または `AzureBlobFS` 型のリンクされたサービスの名前。これは、ログファイルを格納するために使用するインスタンスを示します。	いいえ
path	ログファイルのパス。	ログファイルの格納に使用するパスを指定します。パスを指定しないと、サービスによってコンテナーが作成されます。	いいえ

注意

バイナリファイルをコピーするときに、コピーアクティビティのフォールトトレランスを有効にするための前提条件は次のとおりです。特定のファイルがソースストアから削除されるときにスキップする場合:

ソースデータセットとシンクデータセットはバイナリ形式である必要があり、圧縮の種類を指定することはできません。
サポートされているデータストアの種類は、Azure Blob Sorage、Azure Data Lake Storage Gen1、Azure Data Lake Storage Gen2、Azure Files、ファイルステム、FTP、SFTP、Amazon S3、Google Cloud Storage、HDFS です。
ソースデータセットの複数のファイル (フォルダー、ワイルドカード、またはファイルのリストを指定できます) を指定する場合にのみ、コピーアクティビティで、特定のエラーファイルをスキップできます。コピー先にコピーする 1 つのファイルがソースデータセットに指定されている場合、エラーが発生すると、コピーアクティビティは失敗します。

特定のファイルへのアクセスがソースストアで禁止されているときにスキップする場合:

ソースデータセットとシンクデータセットはバイナリ形式である必要があり、圧縮の種類を指定することはできません。
サポートされているデータストアの種類は、Azure Blob Storage、Azure Data Lake Storage Gen1、Azure Data Lake Storage Gen2、Azure Files、SFTP、Amazon S3、HDFS です。
ソースデータセットの複数のファイル (フォルダー、ワイルドカード、またはファイルのリストを指定できます) を指定する場合にのみ、コピーアクティビティで、特定のエラーファイルをスキップできます。コピー先にコピーする 1 つのファイルがソースデータセットに指定されている場合、エラーが発生すると、コピーアクティビティは失敗します。

特定のファイルがソースストアとターゲットストアの間で矛盾していることが確認されたときにスキップする場合:

詳細については、こちらのデータ整合性ドキュメントを参照してください。

監視

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

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

"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	この項目のログレベル。ファイルのスキップを示す項目は、'Warning' レベルになります。
OperationName	各ファイルでのコピーアクティビティの実行動作。スキップされるファイルを指定する場合は 'FileSkip' になります。
OperationItem	スキップされるファイル名。
Message	ファイルがスキップされた理由を示す詳細情報。

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

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

Note

PolyBase を使用して Azure Synapse Analytics にデータを読み込むには、コピーアクティビティの拒否ポリシーで "polyBaseSettings" を指定して PolyBase のネイティブフォールトトレランス設定を構成します。 PolyBase 互換性のない行は、次に示すように、通常どおり Blob または ADLS へのリダイレクトを有効にできます。
コピーアクティビティが Amazon Redshift Unload を呼び出すように構成されている場合、この機能は適用されません。
この機能は、コピーアクティビティが SQL シンクからストアドプロシージャを呼び出すように構成されている場合や、Upsert を使用して 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/"
        }
    } 
},

プロパティ	説明	使用できる値	必須
enableSkipIncompatibleRow	コピー中に互換性のない行をスキップするかどうかを指定します。	True False (既定値)	いいえ
logSettings	互換性のない行をログに記録するときに指定できるプロパティのグループ。		いいえ
linkedServiceName	スキップされた行を含むログを格納する Azure Blob Storage または Azure Data Lake Storage Gen2 のリンクされたサービス。	`AzureBlobStorage` または `AzureBlobFS` 型のリンクされたサービスの名前。これは、ログファイルを格納するために使用するインスタンスを示します。	いいえ
path	スキップされた行を含むログファイルのパス。	互換性のないデータをログに記録するパスを指定します。パスを指定しないと、サービスによってコンテナーが作成されます。	いいえ

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

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

"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	この項目のログレベル。スキップされた行がこの項目に表示される場合は、'Warning' レベルになります
OperationName	各行でのコピーアクティビティの実行動作。特定の互換性のない行がスキップされたことを記載する場合は、'TabularRowSkip' になります
OperationItem	ソースデータストアからスキップされた行。
Message	この特定の行に互換性がない理由を示す詳細情報。

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

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"
     }
}

プロパティ	説明	使用できる値	必須
enableSkipIncompatibleRow	コピー中に互換性のない行をスキップするかどうかを指定します。	True False (既定値)	いいえ
redirectIncompatibleRowSettings	互換性のない行をログに記録するときに指定できるプロパティのグループ。		いいえ
linkedServiceName	スキップされる行が含まれたログを格納する Azure Storage または Azure Data Lake Store のリンクサービス。	`AzureStorage` または `AzureDataLakeStore` 型のリンクされたサービスの名前。これは、ログファイルを格納するために使用するインスタンスを示します。	いいえ
path	スキップした行を含むログファイルのパス。	互換性のないデータをログに記録するパスを指定します。パスを指定しないと、サービスによってコンテナーが作成されます。	いいえ

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

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

"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)."

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

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

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

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

構成

監視

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

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

表形式データのコピー

サポートされるシナリオ

構成

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

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

構成

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

関連するコンテンツ

その他のリソース

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

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

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

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

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