Kopieren von Daten aus bzw. in Azure Files mithilfe von Azure Data Factory

GILT FÜR: Azure Data Factory Azure Synapse Analytics

In diesem Artikel wird beschrieben, wie Sie Daten in und aus Azure Files kopieren. Informationen zu Azure Data Factory finden Sie im Einführungsartikel.

Unterstützte Funktionen

Dieser Azure Files-Connector wird für die folgenden Aktivitäten unterstützt:

① Azure Integration Runtime ② Selbstgehostete Integration Runtime

Sie können Daten aus Azure Files in einen beliebigen unterstützten Senkendatenspeicher bzw. Daten aus einem beliebigen unterstützten Quelldatenspeicher in Azure Files kopieren. Eine Liste der Datenspeicher, die die Kopieraktivität als Quellen und Senken unterstützt, finden Sie unter Unterstützte Datenspeicher und Formate.

Der Azure Files-Connector unterstützt insbesondere Folgendes:

• Kopieren von Dateien mithilfe der Authentifizierung per Kontoschlüssel oder per Dienst-SAS (Shared Access Signature).
• Kopieren von Dateien im jeweiligen Zustand oder Analysieren bzw. Generieren von Dateien mit den unterstützten Dateiformaten und Codecs für die Komprimierung

Erste Schritte

Sie können eines der folgenden Tools oder SDKs verwenden, um die Kopieraktivität mit einer Pipeline zu verwenden:

• Das Tool „Daten kopieren“
• Azure-Portal
• Das .NET SDK
• Das Python SDK
• Azure PowerShell
• Die REST-API
• Die Azure Resource Manager-Vorlage

Erstellen eines verknüpften Diensts mit Azure Files über die Benutzeroberfläche

Verwenden Sie die folgenden Schritte, um einen verknüpften Dienst für die Azure Files auf der Azure-Portal-Benutzeroberfläche zu erstellen.

1. Navigieren Sie in Ihrem Azure Data Factory- oder Synapse-Arbeitsbereich zu der Registerkarte „Verwalten“, wählen Sie „Verknüpfte Dienste“ aus und klicken Sie dann auf „Neu“:

   • Azure Data Factory
   • Azure Synapse

   

2. Suchen Sie nach der Datei und wählen Sie den Connector für Azure Files Azure File Storage.

   

3. Konfigurieren Sie die Dienstdetails, testen Sie die Verbindung, und erstellen Sie den neuen verknüpften Dienst.

   

Details zur Connector-Konfiguration

Die folgenden Abschnitte enthalten Details zu den Eigenschaften, die zum Definieren von Entitäten speziell für Azure Files verwendet werden.

Eigenschaften des verknüpften Diensts

Dieser Azure Files-Connector unterstützt die folgenden Authentifizierungstypen. Weitere Informationen finden Sie in den entsprechenden Abschnitten.

• Kontoschlüsselauthentifizierung
• SAS-Authentifizierung (Shared Access Signature)
• Authentifizierung mit einer systemseitig zugewiesenen verwalteten Identität
• Authentifizierung mit einer benutzerseitig zugewiesenen verwalteten Identität

Kontoschlüsselauthentifizierung

Data Factory unterstützt die folgenden Eigenschaften für die Kontoschlüsselauthentifizierung von Azure Files:

Beispiel:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountName>;AccountKey=<accountKey>;EndpointSuffix=core.windows.net;",
            "fileShare": "<file share name>"
        },
        "connectVia": {
          "referenceName": "<name of Integration Runtime>",
          "type": "IntegrationRuntimeReference"
        }
    }
}

Beispiel: Speichern des Kontoschlüssels in Azure Key Vault

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountname>;",
            "fileShare": "<file share name>",
            "accountKey": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName>" 
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }            
    }
}

SAS-Authentifizierung (Shared Access Signature)

Shared Access Signatures bieten delegierten Zugriff auf Ressourcen in Ihrem Speicherkonto. Sie können eine SAS verwenden, um einem Client für einen bestimmten Zeitraum eingeschränkte Berechtigungen für Objekte in Ihrem Speicherkonto zu gewähren. Weitere Informationen zu Shared Access Signatures finden Sie unter Shared Access Signatures (SAS): Verstehen des Shared Access Signature-Modells.

Der Dienst unterstützt die folgenden Eigenschaften für die Verwendung der SAS-Authentifizierung:

Beispiel:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "sasUri": {
                "type": "SecureString",
                "value": "<SAS URI of the resource e.g. https://<accountname>.file.core.windows.net/?sv=<storage version>&st=<start time>&se=<expire time>&sr=<resource>&sp=<permissions>&sip=<ip range>&spr=<protocol>&sig=<signature>>"
            },
            "fileShare": "<file share name>",
            "snapshot": "<snapshot version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Beispiel: Speichern des SAS-Tokens in Azure Key Vault

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "sasUri": {
                "type": "SecureString",
                "value": "<SAS URI of the Azure Storage resource without token e.g. https://<accountname>.file.core.windows.net/>"
            },
            "sasToken": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName with value of SAS token e.g. ?sv=<storage version>&st=<start time>&se=<expire time>&sr=<resource>&sp=<permissions>&sip=<ip range>&spr=<protocol>&sig=<signature>>" 
            },
            "fileShare": "<file share name>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Authentifizierung mit einer systemseitig zugewiesenen verwalteten Identität

Eine Data Factory- oder Synapse-Pipeline kann einer systemseitig zugewiesenen verwalteten Identität für Azure-Ressourcen zugeordnet werden, die diese Ressource für die Authentifizierung bei anderen Azure-Diensten darstellt. Sie können diese systemseitig zugewiesene verwaltete Identität für die Azure Files-Authentifizierung verwenden. Weitere Informationen zu verwalteten Identitäten für Azure-Ressourcen finden Sie unter Verwaltete Identitäten für Azure-Ressourcen.

Führen Sie die folgenden Schritte aus, um die Authentifizierung mit einer systemseitig zugewiesenen verwalteten Identität zu verwenden:

1. Rufen Sie die Informationen zur systemseitig zugewiesenen verwalteten Identität ab, indem Sie den Wert der Objekt-ID der systemseitig zugewiesenen verwalteten Identität kopieren, die zusammen mit Ihrer Factory- oder Ihrem Synapse-Arbeitsbereich generiert wurde.

2. Erteilen Sie der verwalteten Identität Berechtigungen in Azure Files. Weitere Informationen zu diesem Thema finden Sie in diesem Artikel.

   • Erteilen Sie als Quelle in der Zugriffssteuerung (IAM) mindestens die Rolle Privilegierter Leser von Speicherdateidaten.
   • Erteilen Sie als Senke in der Zugriffssteuerung (IAM) mindestens die Rolle Privilegierter Mitwirkender für Speicherdateidaten.

Diese Eigenschaften werden für einen mit Azure Files verknüpften Dienst unterstützt:

Beispiel:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {            
            "serviceEndpoint": "https://<accountName>.file.core.windows.net/",
            "fileShare": "<file share name>",
            "snapshot": "<snapshot version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Authentifizierung mit einer benutzerseitig zugewiesenen verwalteten Identität

Eine Data Factory kann mit einer oder mehreren benutzerseitig zugewiesenen verwalteten Identitäten zugewiesen werden. Sie können diese benutzerseitig zugewiesene verwaltete Identität für die Azure Files-Authentifizierung verwenden, die den Zugriff auf Azure Files und das Kopieren von Daten von dort oder dorthin ermöglicht. Weitere Informationen zu verwalteten Identitäten für Azure-Ressourcen finden Sie unter Verwaltete Identitäten für Azure-Ressourcen.

Führen Sie die folgenden Schritte aus, um die Authentifizierung mit einer benutzerseitig zugewiesenen verwalteten Identität zu verwenden:

1. Erstellen Sie eine oder mehrere benutzerseitig zugewiesene verwaltete Identitäten, und gewähren Sie ihnen Berechtigungen in Azure Files. Weitere Informationen zu diesem Thema finden Sie in diesem Artikel.

   • Erteilen Sie als Quelle in der Zugriffssteuerung (IAM) mindestens die Rolle Privilegierter Leser von Speicherdateidaten.
   • Erteilen Sie als Senke in der Zugriffssteuerung (IAM) mindestens die Rolle Privilegierter Mitwirkender für Speicherdateidaten.

2. Weisen Sie Ihrer Data Factory eine oder mehrere benutzerseitig zugewiesene verwaltete Identitäten zu, und erstellen Sie Anmeldeinformationen für jede benutzerseitig zugewiesene verwaltete Identität.

Diese Eigenschaften werden für einen mit Azure Files verknüpften Dienst unterstützt:

Beispiel:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {            
            "serviceEndpoint": "https://<accountName>.file.core.windows.net/",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            },
            "fileShare": "<file share name>",
            "snapshot": "<snapshot version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Legacymodell

Beispiel:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "host": "\\\\<storage name>.file.core.windows.net\\<file service name>",
            "userid": "AZURE\\<storage name>",
            "password": {
                "type": "SecureString",
                "value": "<storage access key>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Dataset-Eigenschaften

Eine vollständige Liste mit den Abschnitten und Eigenschaften, die zum Definieren von Datasets zur Verfügung stehen, finden Sie im Artikel zu Datasets.

Azure Data Factory unterstützt die folgenden Dateiformate. Informationen zu formatbasierten Einstellungen finden Sie in den jeweiligen Artikeln.

• Avro-Format
• Binärformat
• Textformat mit Trennzeichen
• Excel-Format
• JSON-Format
• ORC-Format
• Parquet-Format
• XML-Format

Folgende Eigenschaften werden für Azure Files unter den location-Einstellungen in formatbasierten Datasets unterstützt:

Beispiel:

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<Azure File Storage linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "AzureFileStorageLocation",
                "folderPath": "root/folder/subfolder"
            },
            "columnDelimiter": ",",
            "quoteChar": "\"",
            "firstRowAsHeader": true,
            "compressionCodec": "gzip"
        }
    }
}

Eigenschaften der Kopieraktivität

Eine vollständige Liste mit den Abschnitten und Eigenschaften zum Definieren von Aktivitäten finden Sie im Artikel Pipelines. Dieser Abschnitt enthält eine Liste der Eigenschaften, die von der Azure Files-Quelle und -senke unterstützt werden.

Azure Files als Quelle

Azure Data Factory unterstützt die folgenden Dateiformate. Informationen zu formatbasierten Einstellungen finden Sie in den jeweiligen Artikeln.

• Avro-Format
• Binärformat
• Textformat mit Trennzeichen
• Excel-Format
• JSON-Format
• ORC-Format
• Parquet-Format
• XML-Format

Folgende Eigenschaften werden für Azure-Files unter den storeSettings-Einstellungen in der formatbasierten Kopierquelle unterstützt:

Beispiel:

"activities":[
    {
        "name": "CopyFromAzureFileStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Delimited text input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "DelimitedTextSource",
                "formatSettings":{
                    "type": "DelimitedTextReadSettings",
                    "skipLineCount": 10
                },
                "storeSettings":{
                    "type": "AzureFileStorageReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Azure Files als Senke

Azure Data Factory unterstützt die folgenden Dateiformate. Informationen zu formatbasierten Einstellungen finden Sie in den jeweiligen Artikeln.

• Avro-Format
• Binärformat
• Textformat mit Trennzeichen
• JSON-Format
• ORC-Format
• Parquet-Format

Folgende Eigenschaften werden für Azure-Files unter den storeSettings-Einstellungen in der formatbasierten Kopiersenke unterstützt:

Beispiel:

"activities":[
    {
        "name": "CopyToAzureFileStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Parquet output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "ParquetSink",
                "storeSettings":{
                    "type": "AzureFileStorageWriteSettings",
                    "copyBehavior": "PreserveHierarchy"
                }
            }
        }
    }
]

Beispiele für Ordner- und Dateifilter

Dieser Abschnitt beschreibt das sich ergebende Verhalten für den Ordnerpfad und den Dateinamen mit Platzhalterfiltern.

Beispiele für Dateilisten

In diesem Abschnitt wird das resultierende Verhalten beschrieben, wenn der Dateilistenpfad in der Quelle der Kopieraktivität verwendet wird.

Angenommen, Sie haben die folgende Quellordnerstruktur und möchten die Dateien kopieren, deren Namen fett formatiert sind:

Beispiele für "recursive" und "copyBehavior"

Dieser Abschnitt beschreibt das resultierende Verhalten des Kopiervorgangs für verschiedene Kombinationen von rekursiven und CopyBehavior-Werten.

Eigenschaften der Lookup-Aktivität

Ausführliche Informationen zu den Eigenschaften finden Sie unter Lookup-Aktivität.

Eigenschaften der GetMetadata-Aktivität

Ausführliche Informationen zu den Eigenschaften finden Sie unter GetMetadata-Aktivität.

Eigenschaften der Delete-Aktivität

Ausführliche Informationen zu den Eigenschaften finden Sie unter Delete-Aktivität.

Legacy-Modelle

Legacy-Datasetmodell

Beispiel:

{
    "name": "AzureFileStorageDataset",
    "properties": {
        "type": "FileShare",
        "linkedServiceName":{
            "referenceName": "<Azure File Storage linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "folderPath": "folder/subfolder/",
            "fileName": "*",
            "modifiedDatetimeStart": "2018-12-01T05:00:00Z",
            "modifiedDatetimeEnd": "2018-12-01T06:00:00Z",
            "format": {
                "type": "TextFormat",
                "columnDelimiter": ",",
                "rowDelimiter": "\n"
            },
            "compression": {
                "type": "GZip",
                "level": "Optimal"
            }
        }
    }
}

Legacy-Kopieraktivität: Quellenmodell

Beispiel:

"activities":[
    {
        "name": "CopyFromAzureFileStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure File Storage input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "FileSystemSource",
                "recursive": true
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Legacy-Kopieraktivität – Senkenmodell

Beispiel:

"activities":[
    {
        "name": "CopyToAzureFileStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Azure File Storage output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "FileSystemSink",
                "copyBehavior": "PreserveHierarchy"
            }
        }
    }
]

Zugehöriger Inhalt

Eine Liste der Datenspeicher, die als Quelles und Senken für die Kopieraktivität unterstützt werden, finden Sie in der Dokumentation für Unterstützte Datenspeicher.