Feltolerans för kopieringsaktivitet i Azure Data Factory- och Synapse Analytics-pipelines

Artikel
12/09/2023

GÄLLER FÖR: Azure Data Factory Azure Synapse Analytics

Dricks

Prova Data Factory i Microsoft Fabric, en allt-i-ett-analyslösning för företag. Microsoft Fabric omfattar allt från dataflytt till datavetenskap, realtidsanalys, business intelligence och rapportering. Lär dig hur du startar en ny utvärderingsversion kostnadsfritt!

När du kopierar data från källa till mållager ger kopieringsaktiviteten vissa feltoleranser för att förhindra avbrott från fel mitt i dataflytten. Du kopierar till exempel miljontals rader från källa till målarkiv, där en primärnyckel har skapats i måldatabasen, men källdatabasen inte har några definierade primära nycklar. När du råkar kopiera duplicerade rader från källan till målet stöter du på PK-överträdelsefelet i måldatabasen. För närvarande erbjuder kopieringsaktivitet två sätt att hantera sådana fel:

Du kan avbryta kopieringsaktiviteten när ett fel har påträffats.
Du kan fortsätta att kopiera resten genom att aktivera feltolerans för att hoppa över inkompatibla data. Hoppa till exempel över den duplicerade raden i det här fallet. Dessutom kan du logga överhoppade data genom att aktivera sessionsloggen i kopieringsaktiviteten. Mer information finns i sessionsloggen i kopieringsaktiviteten .

Kopiera binära filer

Tjänsten stöder följande feltoleransscenarier vid kopiering av binära filer. Du kan välja att avbryta kopieringsaktiviteten eller fortsätta att kopiera resten i följande scenarier:

De filer som ska kopieras av tjänsten tas bort av andra program samtidigt.
Vissa specifika mappar eller filer tillåter inte tjänståtkomst eftersom ACL:er för dessa filer eller mappar kräver högre behörighetsnivå än den konfigurerade anslutningsinformationen.
En eller flera filer verifieras inte för att vara konsekventa mellan käll- och mållagret om du aktiverar verifieringsinställningen för datakonsekvens.

Aktivera feltolerans med användargränssnittet

Utför följande steg för att konfigurera feltolerans i en aktiviteten Kopiera i en pipeline med användargränssnittet:

Om du inte redan har skapat en aktiviteten Kopiera för din pipeline söker du efter Kopiera i fönstret Pipelineaktiviteter och drar en kopieringsdataaktivitet till pipelinearbetsytan.
Välj den nya aktiviteten Kopiera data på arbetsytan om den inte redan är markerad och fliken Inställningar för att konfigurera feltolerans.

Konfiguration

När du kopierar binära filer mellan lagringslager kan du aktivera feltolerans enligt följande:

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

Property	beskrivning	Tillåtna värden	Obligatoriskt
skipErrorFile	En grupp med egenskaper för att ange vilka typer av fel som du vill hoppa över under dataflytten.		Nej
fileMissing	Ett av nyckel/värde-paren i skipErrorFile-egenskapspåsen för att avgöra om du vill hoppa över filer som tas bort av andra program när tjänsten utför kopieringsåtgärden. -Sant: du vill kopiera resten genom att hoppa över de filer som tas bort av andra program. – Falskt: du vill avbryta kopieringsaktiviteten när alla filer tas bort från källlagret mitt i dataflytten. Tänk på att den här egenskapen är inställd på true som standard.	True(standard) Falsk	Nej
fileForbidden	Ett av nyckel/värde-paren i skipErrorFile-egenskapspåsen för att avgöra om du vill hoppa över de specifika filerna, när ACL:er för dessa filer eller mappar kräver högre behörighetsnivå än den konfigurerade anslutningen. -Sant: du vill kopiera resten genom att hoppa över filerna. – Falskt: du vill avbryta kopieringsaktiviteten när du får behörighetsproblemet för mappar eller filer.	Sant False(standard)	Nej
dataInkonsekvens	Ett av nyckel/värde-paren i skipErrorFile-egenskapsväskan för att avgöra om du vill hoppa över inkonsekventa data mellan käll- och målarkivet. -Sant: du vill kopiera resten genom att hoppa över inkonsekventa data. – Falskt: du vill avbryta kopieringsaktiviteten när inkonsekventa data har hittats. Tänk på att den här egenskapen endast är giltig när du anger validateDataConsistency som True.	Sant False(standard)	Nej
invalidFileName	Ett av nyckel/värde-paren i skipErrorFile-egenskapspåsen för att avgöra om du vill hoppa över de specifika filerna, när filnamnen är ogiltiga för målarkivet. -Sant: du vill kopiera resten genom att hoppa över de filer som har ogiltiga filnamn. - Falskt: du vill avbryta kopieringsaktiviteten när alla filer har ogiltiga filnamn. Tänk på att den här egenskapen fungerar när du kopierar binära filer från ett lagringslager till ADLS Gen2 eller kopierar binära filer från AWS S3 till alla lagringslager.	Sant False(standard)	Nej
logg Inställningar	En grupp med egenskaper som kan anges när du vill logga de överhoppade objektnamnen.		Nej
linkedServiceName	Den länkade tjänsten för Azure Blob Storage eller Azure Data Lake Storage Gen2 för att lagra sessionsloggfilerna.	Namnen på en `AzureBlobStorage` länkad tjänst eller `AzureBlobFS` typ, som refererar till den instans som du använder för att lagra loggfilen.	Nej
path	Sökvägen till loggfilerna.	Ange den sökväg som du använder för att lagra loggfilerna. Om du inte anger någon sökväg skapar tjänsten en container åt dig.	Nej

Kommentar

Följande är kraven för att aktivera feltolerans i kopieringsaktiviteten vid kopiering av binära filer. För att hoppa över vissa filer när de tas bort från källarkivet:

Källdatauppsättningen och mottagardatauppsättningen måste vara binärt format och komprimeringstypen kan inte anges.
De datalagertyper som stöds är Azure Blob Storage, Azure Data Lake Storage Gen1, Azure Data Lake Storage Gen2, Azure Files, File System, FTP, SFTP, Amazon S3, Google Cloud Storage och HDFS.
Endast om du anger flera filer i källdatauppsättningen, som kan vara en mapp, jokertecken eller en lista över filer, kan kopieringsaktiviteten hoppa över de specifika felfilerna. Om en enskild fil anges i källdatauppsättningen som ska kopieras till målet misslyckas kopieringsaktiviteten om något fel uppstod.

För att hoppa över vissa filer när deras åtkomst är förbjuden från källarkivet:

Källdatauppsättningen och mottagardatauppsättningen måste vara binärt format och komprimeringstypen kan inte anges.
De datalagertyper som stöds är Azure Blob Storage, Azure Data Lake Storage Gen1, Azure Data Lake Storage Gen2, Azure Files, SFTP, Amazon S3 och HDFS.
Endast om du anger flera filer i källdatauppsättningen, som kan vara en mapp, jokertecken eller en lista över filer, kan kopieringsaktiviteten hoppa över de specifika felfilerna. Om en enskild fil anges i källdatauppsättningen som ska kopieras till målet misslyckas kopieringsaktiviteten om något fel uppstod.

För att hoppa över vissa filer när de verifieras vara inkonsekventa mellan käll- och målarkivet:

Du kan få mer information från dokumentet om datakonsekvens här.

Övervakning

Utdata från kopieringsaktivitet

Du kan hämta antalet filer som läss, skrivs och hoppas över via utdata från varje kopieringsaktivitetskörning.

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

Sessionslogg från kopieringsaktivitet

Om du konfigurerar för att logga de överhoppade filnamnen hittar du loggfilen från den här sökvägen: https://[your-blob-account].blob.core.windows.net/[path-if-configured]/copyactivity-logs/[copy-activity-name]/[copy-activity-run-id]/[auto-generated-GUID].csv.

Loggfilerna måste vara csv-filerna. Schemat för loggfilen är följande:

Kolumn	beskrivning
Tidsstämpel	Tidsstämpeln när filen hoppades över.
Nivå	Loggnivån för det här objektet. Det kommer att vara på varningsnivån för objektet som visar filhopp.
OperationName	aktiviteten Kopiera driftsbeteende för varje fil. Det blir "FileSkip" för att ange vilken fil som ska hoppas över.
OperationItem	De filnamn som ska hoppas över.
Meddelande	Mer information för att illustrera varför filen hoppas över.

Exemplet på en loggfil är följande:

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,'."

I loggen ovan kan du se att bigfile.csv har hoppats över på grund av att ett annat program tog bort den här filen när tjänsten kopierade den. Och 3_nopermission.txt har hoppats över eftersom tjänsten inte har behörighet att komma åt den på grund av behörighetsproblem.

Kopiera tabelldata

Stödda scenarier

aktiviteten Kopiera stöder tre scenarier för att identifiera, hoppa över och logga inkompatibla tabelldata:

Inkompatibilitet mellan källdatatypen och den interna mottagartypen.

Till exempel: Kopiera data från en CSV-fil i Blob Storage till en SQL-databas med en schemadefinition som innehåller tre KOLUMNER av INT-typ. CSV-filraderna som innehåller numeriska data, till exempel 123 456 789, kopieras till mottagararkivet. De rader som innehåller icke-numeriska värden, till exempel 123 456, abc identifieras dock som inkompatibla och hoppas över.
Matchningsfel i antalet kolumner mellan källan och mottagaren.

Till exempel: Kopiera data från en CSV-fil i Blob Storage till en SQL-databas med en schemadefinition som innehåller sex kolumner. CSV-filraderna som innehåller sex kolumner kopieras till mottagararkivet. CSV-filrader som innehåller fler än sex kolumner identifieras som inkompatibla och hoppas över.
Primär nyckelöverträdelse när du skriver till SQL Server/Azure SQL Database/Azure Cosmos DB.

Till exempel: Kopiera data från en SQL-server till en SQL-databas. En primärnyckel definieras i SQL-mottagardatabasen, men ingen sådan primärnyckel definieras i SQL-källservern. Det går inte att kopiera de duplicerade rader som finns i källan till mottagaren. aktiviteten Kopiera kopierar endast den första raden av källdata till mottagaren. Efterföljande källrader som innehåller det duplicerade primärnyckelvärdet identifieras som inkompatibla och hoppas över.

Kommentar

Om du vill läsa in data i Azure Synapse Analytics med PolyBase konfigurerar du PolyBase interna feltoleransinställningar genom att ange avvisa principer via "polyBase Inställningar" i kopieringsaktiviteten. Du kan fortfarande aktivera omdirigering av polybase-inkompatibla rader till Blob eller ADLS som vanligt enligt nedan.
Den här funktionen gäller inte när kopieringsaktiviteten har konfigurerats för att anropa Amazon Redshift Unload.
Den här funktionen gäller inte när kopieringsaktiviteten har konfigurerats för att anropa en lagrad procedur från en SQL-mottagare eller använda Upsert för att skriva data till en SQL-mottagare.

Konfiguration

I följande exempel finns en JSON-definition för att konfigurera hoppa över de inkompatibla raderna i kopieringsaktiviteten:

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

Property	beskrivning	Tillåtna värden	Obligatoriskt
enableSkipIncompatibleRow	Anger om du vill hoppa över inkompatibla rader under kopiering eller inte.	Sant False (standard)	Nej
logg Inställningar	En grupp med egenskaper som kan anges när du vill logga de inkompatibla raderna.		Nej
linkedServiceName	Den länkade tjänsten för Azure Blob Storage eller Azure Data Lake Storage Gen2 för att lagra loggen som innehåller de överhoppade raderna.	Namnen på en `AzureBlobStorage` länkad tjänst eller `AzureBlobFS` typ, som refererar till den instans som du använder för att lagra loggfilen.	Nej
path	Sökvägen till loggfilerna som innehåller de överhoppade raderna.	Ange den sökväg som du vill använda för att logga inkompatibla data. Om du inte anger någon sökväg skapar tjänsten en container åt dig.	Nej

Övervaka överhoppade rader

När kopieringsaktiviteten har körts kan du se antalet överhoppade rader i utdata från kopieringsaktiviteten:

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

Om du konfigurerar för att logga de inkompatibla raderna kan du hitta loggfilen från den här sökvägen: https://[your-blob-account].blob.core.windows.net/[path-if-configured]/copyactivity-logs/[copy-activity-name]/[copy-activity-run-id]/[auto-generated-GUID].csv.

Loggfilerna är csv-filerna. Schemat för loggfilen är följande:

Kolumn	beskrivning
Tidsstämpel	Tidsstämpeln när de inkompatibla raderna hoppades över
Nivå	Loggnivån för det här objektet. Det hamnar på varningsnivån om det här objektet visar de överhoppade raderna
OperationName	aktiviteten Kopiera driftsbeteende på varje rad. Det blir "TabularRowSkip" för att ange att den specifika inkompatibla raden har hoppats över
OperationItem	De överhoppade raderna från källdatalagret.
Meddelande	Mer information för att illustrera varför den här raden inte är kompatibel.

Ett exempel på loggfilens innehåll är följande:

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

Från exempelloggfilen ovan kan du se att en rad "data1, data2, data3" har hoppat över på grund av typkonverteringsproblem från källa till målarkiv. En annan rad "data4, data5, data6" har hoppats över på grund av PK-överträdelseproblem från källa till målarkiv.

Kopiera tabelldata (äldre):

Följande metod är det äldre sättet att aktivera feltolerans för att endast kopiera tabelldata. Om du skapar en ny pipeline eller aktivitet uppmanas du att börja härifrån i stället.

Konfiguration

I följande exempel finns en JSON-definition för att konfigurera hoppa över de inkompatibla raderna i kopieringsaktiviteten:

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

Property	beskrivning	Tillåtna värden	Obligatoriskt
enableSkipIncompatibleRow	Anger om du vill hoppa över inkompatibla rader under kopiering eller inte.	Sant False (standard)	Nej
redirectIncompatibleRow Inställningar	En grupp med egenskaper som kan anges när du vill logga de inkompatibla raderna.		Nej
linkedServiceName	Den länkade tjänsten för Azure Storage eller Azure Data Lake Store för att lagra loggen som innehåller de överhoppade raderna.	Namnen på en `AzureStorage` länkad tjänst eller `AzureDataLakeStore` typ, som refererar till den instans som du vill använda för att lagra loggfilen.	Nej
path	Sökvägen till loggfilen som innehåller de överhoppade raderna.	Ange den sökväg som du vill använda för att logga inkompatibla data. Om du inte anger någon sökväg skapar tjänsten en container åt dig.	Nej

Övervaka överhoppade rader

När kopieringsaktiviteten har körts kan du se antalet överhoppade rader i utdata från kopieringsaktiviteten:

"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": []
        },

Om du konfigurerar för att logga de inkompatibla raderna hittar du loggfilen på den här sökvägen: https://[your-blob-account].blob.core.windows.net/[path-if-configured]/[copy-activity-run-id]/[auto-generated-GUID].csv.

Loggfilerna kan bara vara csv-filerna. De ursprungliga data som hoppas över loggas med kommatecken som kolumnavgränsare om det behövs. Vi lägger till ytterligare två kolumner "ErrorCode" och "ErrorMessage" utöver de ursprungliga källdata i loggfilen, där du kan se rotorsaken till inkompatibiliteten. ErrorCode och ErrorMessage citeras med dubbla citattecken.

Ett exempel på loggfilens innehåll är följande:

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

Se de andra artiklarna om kopieringsaktivitet:

Feltolerans för kopieringsaktivitet i Azure Data Factory- och Synapse Analytics-pipelines

Kopiera binära filer

Aktivera feltolerans med användargränssnittet

Konfiguration

Övervakning

Utdata från kopieringsaktivitet

Sessionslogg från kopieringsaktivitet

Kopiera tabelldata

Stödda scenarier

Konfiguration

Övervaka överhoppade rader

Kopiera tabelldata (äldre):

Konfiguration

Övervaka överhoppade rader

Relaterat innehåll

Ytterligare resurser