Azure Data Factory 和 Synapse Analytics 管線中複製活動的容錯

發行項
12/09/2023

適用于： Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory，這是適用于企業的單一分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告等所有專案。瞭解如何免費啟動新的試用版！

當您將資料從來源複製到目的地存放區時，複製活動會提供特定層級的容錯功能，以防止資料移動時發生失敗。例如，您要從來源複製數百萬個數據列到目的地存放區，其中主鍵已在目的地資料庫中建立，但源資料庫並未定義任何主鍵。當您碰巧將重複的資料列從來源複製到目的地時，您會在目的地資料庫上遇到 PK 違規失敗。目前，複製活動提供您兩種方式來處理這類錯誤：

發生任何失敗之後，您就可以中止複製活動。
您可以啟用容錯來略過不相容的資料，以繼續複製其餘部分。例如，在此案例中略過重複的資料列。此外，您可以在複製活動內啟用會話記錄，以記錄略過的資料。如需詳細資訊，請參閱複製活動的會話記錄。

複製二進位檔案

當複製二進位檔案時，服務支援下列容錯案例。您可以選擇中止複製活動，或在下列案例中繼續複製其餘專案：

服務所複製的檔案會同時由其他應用程式刪除。
某些特定資料夾或檔案不允許服務存取，因為這些檔案或資料夾的 ACL 需要比設定的連接資訊更高的許可權等級。
如果您啟用資料一致性驗證設定，則不會驗證一或多個檔案在來源和目的地存放區之間保持一致。

使用 UI 啟用容錯

若要在具有 UI 的管線中設定複製活動容錯，請完成下列步驟：

如果您尚未為管線建立複製活動，請在管線 [活動] 窗格中搜尋 [複製 ]，然後將 [複製資料] 活動拖曳至管線畫布。
如果尚未選取，請選取畫布上的新 [複製資料] 活動，以及其 [設定] 索引標籤，以設定容錯。

組態

當您在儲存體存放區之間複製二進位檔案時，您可以啟用容錯功能，如下所示：

{
  "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	一組屬性，指定要在資料移動期間略過之失敗類型。		No
fileMissing	skipErrorFile 屬性包內的其中一個機碼/值組，以判斷您是否要略過服務執行複製作業時，其他應用程式正在刪除的檔案。 -True：您想要略過其他應用程式刪除的檔案來複製其餘檔案。 - False：您想要在資料移動中間從來源存放區刪除任何檔案之後中止複製活動。請注意，此屬性設定為 true 作為預設值。	True（預設值） False	No
fileForbidden	skipErrorFile 屬性包內的其中一個索引鍵/值組，以判斷您是否要略過特定檔案，當這些檔案或資料夾的 ACL 需要高於設定的連接許可權等級時。 -True：您想要略過檔案來複製其餘部分。 - False：一旦取得資料夾或檔案的許可權問題，您想要中止複製活動。	真 False（預設值）	No
dataInconsistency	skipErrorFile 屬性包內的其中一個索引鍵/值組，以判斷您是否要略過來源和目的地存放區之間的不一致資料。 -True：您想要略過不一致的資料來複製其餘部分。 - False：一旦找到不一致的資料，您想要中止複製活動。請注意，只有在您將 validateDataConsistency 設定為 True 時，此屬性才有效。	真 False（預設值）	No
invalidFileName	skipErrorFile 屬性包內的其中一個機碼/值組，以判斷您是否要略過特定檔案，當目的地存放區檔案名無效時。 -True：您想要略過具有無效檔案名的檔案，以複製其餘的檔案。 - False：一旦任何檔案的檔案名無效，您想要中止複製活動。請注意，此屬性適用于將二進位檔案從任何儲存體存放區複製到 ADLS Gen2，或只將二進位檔案從 AWS S3 複製到任何儲存體存放區時。	真 False（預設值）	No
log設定	當您想要記錄略過的物件名稱時，可以指定的屬性群組。		No
linkedServiceName	Azure Blob 儲存體或 Azure Data Lake 儲存體 Gen2 的連結服務，以儲存會話記錄檔。	或 `AzureBlobFS` 型別連結服務的名稱 `AzureBlobStorage` ，其會參考您用來儲存記錄檔的實例。	No
path	記錄檔的路徑。	指定您用來儲存記錄檔的路徑。如果您沒有提供路徑，服務會為您建立容器。	No

注意

以下是複製二進位檔案時啟用複製活動容錯的必要條件。若要在從來源存放區中刪除特定檔案時略過這些檔案：

來源資料集和接收資料集必須是二進位格式，而且無法指定壓縮類型。
支援的資料存放區類型包括 Azure Blob 儲存體、Azure Data Lake 儲存體 Gen1、Azure Data Lake 儲存體 Gen2、Azure 檔案儲存體、檔案系統、FTP、SFTP、Amazon S3、Google Cloud 儲存體和 HDFS。
只有當您在源資料集中指定多個檔案時，這可以是資料夾、萬用字元或檔案清單時，複製活動才能略過特定的錯誤檔案。如果在要複製到目的地的來源資料集中指定單一檔案，如果發生任何錯誤，複製活動將會失敗。

針對在來源存放區禁止其存取時略過特定檔案：

來源資料集和接收資料集必須是二進位格式，而且無法指定壓縮類型。
支援的資料存放區類型包括 Azure Blob 儲存體、Azure Data Lake 儲存體 Gen1、Azure Data Lake 儲存體 Gen2、Azure 檔案儲存體、SFTP、Amazon S3 和 HDFS。
只有當您在源資料集中指定多個檔案時，這可以是資料夾、萬用字元或檔案清單時，複製活動才能略過特定的錯誤檔案。如果在要複製到目的地的來源資料集中指定單一檔案，如果發生任何錯誤，複製活動將會失敗。

當驗證特定檔案在來源和目的地存放區之間不一致時略過：

您可以在這裡從資料一致性檔取得更多詳細資料。

監視

複製活動的輸出

您可以透過每個複製活動執行的輸出，取得讀取、寫入和略過的檔案數目。

"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 檔案。記錄檔的架構如下所示：

資料行	描述
時間戳記	略過檔案時的時間戳記。
等級	這個專案的記錄層級。它將會處於顯示檔案略過之專案的「警告」層級。
OperationName	複製活動每個檔案的操作行為。將 'FileSkip' 指定要略過的檔案。
OperationItem	要略過的檔案名。
訊息	詳細資訊，說明為何要略過檔案。

記錄檔的範例如下：

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。

複製表格式資料

支援的案例

複製活動支援三種偵測、略過和記錄不相容表格式資料的案例：

源資料類型與接收原生類型 之間的不相容。

例如：將資料從 Blob 儲存體中的 CSV 檔案複製到包含三個 INT 類型資料行的架構定義 SQL 資料庫。包含數值資料的 CSV 檔案資料列，例如 123,456,789 已成功複製到接收存放區。不過，包含非數值的資料列，例如 123,456、abc 會偵測為不相容且略過。
來源與接收 之間的資料行數目不符。

例如：將資料從 Blob 儲存體中的 CSV 檔案複製到包含六個數據行的架構定義 SQL 資料庫。包含六個數據行的 CSV 檔案資料列已成功複製到接收存放區。包含六個以上資料行的 CSV 檔案資料列會偵測為不相容且略過。
寫入 SQL Server/Azure SQL 資料庫/Azure Cosmos DB 時發生主鍵違規。

例如：將資料從 SQL Server 複製到 SQL 資料庫。主鍵定義于接收 SQL 資料庫中，但來源 SQL Server 中未定義這類主鍵。來源中存在的重復資料列無法複製到接收。複製活動只會將來源資料的第一個資料列複製到接收中。後續包含重複主鍵值的來來源資料列會偵測為不相容且略過。

注意

若要使用 PolyBase 將資料載入 Azure Synapse Analytics，請在複製活動中透過「 polyBase設定」指定拒絕原則，以設定 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 (預設)	No
log設定	當您想要記錄不相容的資料列時，可以指定的屬性群組。		No
linkedServiceName	Azure Blob 儲存體或 Azure Data Lake 儲存體 Gen2 的連結服務，用來儲存包含略過資料列的記錄。	或 `AzureBlobFS` 型別連結服務的名稱 `AzureBlobStorage` ，其會參考您用來儲存記錄檔的實例。	No
path	包含略過之資料列的記錄檔路徑。	指定您想要用來記錄不相容資料的路徑。如果您沒有提供路徑，服務會為您建立容器。	No

監視略過的資料列

複製活動執行完成之後，您可以在複製活動的輸出中看到略過的資料列數目：

"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 檔案。記錄檔的架構如下所示：

資料行	描述
時間戳記	略過不相容資料列時的時間戳記
等級	這個專案的記錄層級。如果此專案顯示略過的資料列，則會處於「警告」層級
OperationName	複製活動每個資料列的操作行為。將 'TabularRowSkip' 指定已略過特定不相容的資料列
OperationItem	來源資料存放區中略過的資料列。
訊息	如需詳細資訊，說明為何此特定資料列不相容。

記錄檔內容的範例如下：

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

從上述範例記錄檔中，您可以看到一個資料列「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 (預設)	No
redirectIncompatibleRow設定	當您想要記錄不相容的資料列時，可以指定的屬性群組。		No
linkedServiceName	Azure 儲存體或 Azure Data Lake Store 的連結服務，用來儲存包含略過資料列的記錄。	或 `AzureDataLakeStore` 型別連結服務的名稱 `AzureStorage` ，其是指您想要用來儲存記錄檔的實例。	No
path	包含略過之資料列的記錄檔路徑。	指定您想要用來記錄不相容資料的路徑。如果您沒有提供路徑，服務會為您建立容器。	No

監視略過的資料列

複製活動執行完成之後，您可以在複製活動的輸出中看到略過的資料列數目：

"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」，您可以在其中看到不相容的根本原因。 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 啟用容錯

組態

監視

複製活動的輸出

複製活動的會話記錄

複製表格式資料

支援的案例

組態

監視略過的資料列

複製表格式資料（舊版）：

組態

監視略過的資料列

相關內容

其他資源