次の方法で共有


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

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

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

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

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

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

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

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

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

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

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

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

    Shows the UI for a Copy Data activity on the Settings tab with the Fault Tolerance configuration highlighted.

構成

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

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

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