Kopieren von Daten aus oder in Azure Files mithilfe von Azure Data Factory

Gilt für: Azure Data Factory Azure Synapse Analytics

In diesem Artikel wird beschrieben, wie Daten in und aus Azure Files kopiert werden. Weitere Informationen zu Azure Data Factory finden Sie im Artikel introductory.

Unterstützte Funktionen

Dieser Azure Files Connector wird für die folgenden Funktionen unterstützt:

(1) Azure Integrationslaufzeit (2) Selbst gehostete Integrationslaufzeit

Sie können Daten aus Azure Files in jeden unterstützten Senkendatenspeicher kopieren oder Daten aus jedem 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.

Insbesondere unterstützt dieser Azure Files Connector 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

Zum Ausführen der Kopieraktivität mit einer Pipeline können Sie eines der folgenden Tools oder SDKs verwenden:

• Datenkopier-Tool
• Azure Portal
• .NET SDK
• Python SDK
• Azure PowerShell
• REST-API
• Azure Resource Manager Vorlage

Erstellen eines verknüpften Diensts zum Azure Files mithilfe der Benutzeroberfläche

Führen Sie die folgenden Schritte aus, um in der Benutzeroberfläche des Azure-Portals einen verknüpften Dienst zu Azure Files zu erstellen.

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

   • Azure Data Factory
   • Azure Synapse

   

2. Suchen Sie nach Datei, und wählen Sie den Connector für Azure Files mit der Bezeichnung Azure Dateispeicher aus.

   

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

   

Details zur Connector-Konfiguration

In den folgenden Abschnitten werden Details zu Eigenschaften bereitgestellt, die zum Definieren von Entitäten verwendet werden, die für Azure Files spezifisch sind.

Eigenschaften des verknüpften Diensts

Der 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 Azure Files Kontoschlüsselauthentifizierung:

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

Example: Speichern sie den Kontoschlüssel 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 Shared Access Signature (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 gemeinsamen Zugriffs-Signatur-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"
        }
    }
}

Example: 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 system zugewiesenen verwalteten Identität für Azure Ressourcen zugeordnet werden, die diese Ressource für die Authentifizierung für andere Azure Dienste darstellt. Sie können diese vom System zugewiesene verwaltete Identität für Azure Files Authentifizierung verwenden. Weitere Informationen zu verwalteten Identitäten für Azure Ressourcen finden Sie unter Managed-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 die Berechtigung "Verwaltete Identität" in Azure Files. Weitere Informationen zu den Rollen finden Sie in diesem Artikel.

   • Als Quelle, in Zugriffssteuerung (IAM), gewähren Sie mindestens die Rolle Storage File Data Privileged Reader.
   • Als Sink, in Zugriffssteuerung (IAM), gewähren Sie mindestens die Rolle Storage File Data Privileged Contributor.

Diese Eigenschaften werden für einen 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 mithilfe einer benutzerdefinierten verwalteten Identität

Eine Data Factory kann mit einer oder mehreren benutzerseitig zugewiesenen verwalteten Identitäten zugewiesen werden. Sie können diese vom Benutzer zugewiesene verwaltete Identität für Azure Files Authentifizierung verwenden, die den Zugriff auf und das Kopieren von Daten von oder Azure Files ermöglicht. Weitere Informationen zu verwalteten Identitäten für Azure Ressourcen finden Sie unter Managed-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 benutzerzugewiesene verwaltete Identitäten und gewähren Sie Berechtigungen in Azure Files. Weitere Informationen zu den Rollen finden Sie in diesem Artikel.

   • Als Quelle, in Zugriffssteuerung (IAM), gewähren Sie mindestens die Rolle Storage File Data Privileged Reader.
   • Als Sink, in Zugriffssteuerung (IAM), gewähren Sie mindestens die Rolle Storage File Data Privileged Contributor.

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 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
• Durch Trennzeichen getrenntes Textformat
• Excel-Format
• JSON-Format
• ORC-Format
• Parquet-Format
• XML-Format

Die folgenden Eigenschaften werden für Azure Files unter location Einstellungen im formatbasierten Datensatz 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 Azure Files Quelle und Sink 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
• Durch Trennzeichen getrenntes Textformat
• 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
• Durch Trennzeichen getrenntes Textformat
• 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.

Aktivitätseigenschaften löschen

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 Quellen und Senken für die Kopieraktivität unterstützt werden, finden Sie in unterstützte Datenspeicher.