Copiare dati da Amazon Simple Storage Service usando Azure Data Factory

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Questo articolo illustra come copiare dati da Amazon Simple Storage Service (Amazon S3). Per altre informazioni su Azure Data Factory, vedere l'articolo introduttivo.

Suggerimento

Per altre informazioni sullo scenario di migrazione dei dati da Amazon S3 a Archiviazione di Azure, vedere Usare Azure Data Factory per eseguire la migrazione dei dati da Amazon S3 a Archiviazione di Azure.

Funzionalità supportate

Il connettore Amazon S3 è supportato per le attività seguenti:

In particolare, questo connettore Amazon S3 supporta la copia di file così come sono o l'analisi dei file con i formati di file supportati e i codec di compressione. È anche possibile scegliere di mantenere i metadati del file durante la copia. Il connettore usa AWS Signature Version 4 per autenticare le richieste a S3.

Suggerimento

Per copiare dati da qualsiasi provider di archiviazione compatibile con S3, vedere Archiviazione compatibile con Amazon S3.

Autorizzazioni necessarie

Per copiare dati da Amazon S3, assicurarsi di aver ottenuto le autorizzazioni seguenti per le operazioni su oggetti Amazon S3: s3:GetObject e s3:GetObjectVersion .

Se si usa Data Factory'interfaccia utente per creare, sono necessarie autorizzazioni e aggiuntive per operazioni come il test della connessione al servizio collegato e s3:ListAllMyBuckets s3:ListBucket / s3:GetBucketLocation l'esplorazione dalla radice. Se non si vogliono concedere queste autorizzazioni, è possibile scegliere le opzioni "Test connection to file path" (Test connessione a percorso file) o "Browse from specified path" (Sfoglia dal percorso specificato) dall'interfaccia utente.

Per l'elenco completo delle autorizzazioni di Amazon S3, vedere Specifica delle autorizzazioni in un criterio nel sito AWS.

Introduzione

Per eseguire l'attività di copia con una pipeline, è possibile usare uno degli strumenti o SDK seguenti:

Le sezioni seguenti riportano informazioni dettagliate sulle proprietà che vengono usate per definire entità di Data Factory specifiche per Amazon S3.

Proprietà del servizio collegato

Per un servizio collegato Amazon S3 sono supportate le proprietà seguenti:

Proprietà Descrizione Obbligatoria
type La proprietà type deve essere impostata su AmazonS3.
authenticationType Specificare il tipo di autenticazione usato per connettersi ad Amazon S3. È possibile scegliere di usare le chiavi di accesso per un account AWS Identity and Access Management (IAM) o credenziali di sicurezza temporanee.
I valori consentiti sono: AccessKey (impostazione predefinita) e TemporarySecurityCredentials .
No
accessKeyId ID della chiave di accesso segreta.
secretAccessKey La stessa chiave di accesso segreta. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro in Data Factory oppure fare riferimento a un segreto archiviato in Azure Key Vault.
sessionToken Applicabile quando si usa l'autenticazione con credenziali di sicurezza temporanee. Informazioni su come richiedere credenziali di sicurezza temporanee da AWS.
Si noti che le credenziali temporanee di AWS scadono tra 15 minuti e 36 ore in base alle impostazioni. Assicurarsi che le credenziali siano valide durante l'esecuzione dell'attività, in particolare per il carico di lavoro operativo. Ad esempio, è possibile aggiornarla periodicamente e archiviarla in Azure Key Vault.
Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro in Data Factory oppure fare riferimento a un segreto archiviato in Azure Key Vault.
No
serviceUrl Specificare l'endpoint S3 https://<service url> personalizzato. No
connectVia Runtime di integrazione da usare per la connessione all'archivio dati. È possibile usare il runtime di integrazione di Azure o il runtime di integrazione self-hosted (se l'archivio dati si trova in una rete privata). Se questa proprietà non viene specificata, il servizio usa il runtime di integrazione di Azure predefinito. No

Esempio: uso dell'autenticazione con chiave di accesso

{
    "name": "AmazonS3LinkedService",
    "properties": {
        "type": "AmazonS3",
        "typeProperties": {
            "accessKeyId": "<access key id>",
            "secretAccessKey": {
                "type": "SecureString",
                "value": "<secret access key>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Esempio: uso dell'autenticazione temporanea delle credenziali di sicurezza

{
    "name": "AmazonS3LinkedService",
    "properties": {
        "type": "AmazonS3",
        "typeProperties": {
            "authenticationType": "TemporarySecurityCredentials",
            "accessKeyId": "<access key id>",
            "secretAccessKey": {
                "type": "SecureString",
                "value": "<secret access key>"
            },
            "sessionToken": {
                "type": "SecureString",
                "value": "<session token>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Proprietà del set di dati

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione dei set di dati, vedere l'articolo Set di dati.

Azure Data Factory supporta i formati di file seguenti. Per impostazioni basate sui formati, fare riferimento ai singoli articoli.

Le proprietà seguenti sono supportate per Amazon S3 nelle location impostazioni in un set di dati basato sul formato:

Proprietà Descrizione Obbligatoria
type La proprietà type in in un set di dati deve essere location impostata su AmazonS3Location.
bucketName Il nome del bucket S3.
folderPath Percorso della cartella nel bucket specificato. Se si vuole usare un carattere jolly per filtrare la cartella, ignorare questa impostazione e specificarne l'impostazione nelle impostazioni dell'origine dell'attività. No
fileName Nome del file nel bucket e nel percorso della cartella specificato. Se si vuole usare un carattere jolly per filtrare i file, ignorare questa impostazione e specificarne l'impostazione nelle impostazioni dell'origine dell'attività. No
version La versione dell'oggetto S3 se è stato abilitato il controllo delle versioni S3. Se non è specificato, verrà recuperata la versione più recente. No

Esempio:

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<Amazon S3 linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "AmazonS3Location",
                "bucketName": "bucketname",
                "folderPath": "folder/subfolder"
            },
            "columnDelimiter": ",",
            "quoteChar": "\"",
            "firstRowAsHeader": true,
            "compressionCodec": "gzip"
        }
    }
}

Proprietà dell'attività di copia

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, vedere l'articolo sulle pipeline. Questa sezione fornisce un elenco delle proprietà supportate dall'origine Amazon S3.

Amazon S3 come tipo di origine

Azure Data Factory supporta i formati di file seguenti. Per impostazioni basate sui formati, fare riferimento ai singoli articoli.

Le proprietà seguenti sono supportate per Amazon S3 nelle storeSettings impostazioni in un'origine di copia basata su formato:

Proprietà Descrizione Obbligatoria
type La proprietà type in deve essere storeSettings impostata su AmazonS3ReadSettings.
Individuare i file da copiare:
OPZIONE 1: percorso statico
Copia dal percorso del bucket o della cartella/file specificato nel set di dati. Se si desidera copiare tutti i file da un bucket o da una cartella, specificare anche wildcardFileName come * .
OPZIONE 2: prefisso S3
- prefix
Prefisso per il nome della chiave S3 nel bucket specificato configurato in un set di dati per filtrare i file S3 di origine. Sono selezionate le chiavi S3 i cui bucket_in_dataset/this_prefix nomi iniziano con . Usa il filtro lato servizio di S3, che offre prestazioni migliori rispetto a un filtro con caratteri jolly.

Quando si usa il prefisso e si sceglie di copiare nel sink basato su file con gerarchia di mantenimento, si noti che il percorso secondario dopo l'ultimo "/" nel prefisso verrà mantenuto. Ad esempio, si dispone dell'origine bucket/folder/subfolder/file.txt e si configura il prefisso come , quindi il percorso del file mantenuto è folder/sub subfolder/file.txt .
No
OPZIONE 3: carattere jolly
- wildcardFolderPath
Percorso della cartella con caratteri jolly nel bucket specificato configurato in un set di dati per filtrare le cartelle di origine.
I caratteri jolly consentiti sono: * (corrispondenza di zero o più caratteri) e ? (corrispondenza di zero caratteri o di un carattere singolo). Usare ^ per eseguire l'escape se il nome della cartella contiene un carattere jolly o questo carattere di escape.
Vedere altri esempi in Esempi di filtro file e cartelle.
No
OPZIONE 3: carattere jolly
- wildcardFileName
Nome file con caratteri jolly nel bucket e nel percorso della cartella specificati (o percorso della cartella con caratteri jolly) per filtrare i file di origine.
I caratteri jolly consentiti sono: * (corrispondenza di zero o più caratteri) e ? (corrispondenza di zero caratteri o di un carattere singolo). Usare ^ per eseguire l'escape se il nome del file contiene un carattere jolly o questo carattere di escape. Vedere altri esempi in Esempi di filtro file e cartelle.
OPZIONE 4: un elenco di file
- fileListPath
Indica di copiare un determinato set di file. Puntare a un file di testo che include un elenco di file da copiare, un file per riga, ovvero il percorso relativo al percorso configurato nel set di dati.
Quando si usa questa opzione, non specificare un nome file nel set di dati. Per altri esempi, vedere Esempi di elenco di file.
No
Impostazioni aggiuntive:
ricorsiva Indica se i dati vengono letti in modo ricorsivo dalle cartelle secondarie o solo dalla cartella specificata. Si noti che quando recursive è impostato su true e il sink è un archivio basato su file, una cartella o una sottocartella vuota non viene copiata o creata nel sink.
I valori consentiti sono true (predefinito) e false.
Questa proprietà non è applicabile quando si configura fileListPath.
No
deleteFilesAfterCompletion Indica se i file binari verranno eliminati dall'archivio di origine dopo lo spostamento nell'archivio di destinazione. L'eliminazione del file è per ogni file, quindi quando l'attività di copia non riesce, si può vedere che alcuni file sono già stati copiati nella destinazione ed eliminati dall'origine, mentre altri sono ancora presenti nell'archivio di origine.
Questa proprietà è valida solo nello scenario di copia di file binari. Valore predefinito: false.
No
modifiedDatetimeStart I file vengono filtrati in base all'attributo : ultima modifica.
I file vengono selezionati se l'ora dell'ultima modifica è inclusa nell'intervallo di tempo tra modifiedDatetimeStart e modifiedDatetimeEnd. L'ora viene applicata a un fuso orario UTC nel formato "2018-12-01T05:00:00Z".
Le proprietà possono essere NULL, il che significa che al set di dati non verrà applicato alcun filtro di attributo di file. Quando ha un valore datetime ma è NULL, verranno selezionati i file il cui ultimo attributo modificato è maggiore o uguale al valore modifiedDatetimeStart modifiedDatetimeEnd datetime. Quando ha un valore datetime ma è NULL, verranno selezionati i file il cui ultimo attributo modificato è minore del modifiedDatetimeEnd modifiedDatetimeStart valore datetime.
Questa proprietà non è applicabile quando si configura fileListPath.
No
modifiedDatetimeEnd Come sopra. No
enablePartitionDiscovery Per i file partizionati, specificare se analizzare le partizioni dal percorso del file e aggiungerle come colonne di origine aggiuntive.
I valori consentiti sono false (impostazione predefinita) e true.
No
partitionRootPath Quando l'individuazione delle partizioni è abilitata, specificare il percorso radice assoluto per leggere le cartelle partizionate come colonne di dati.

Se non è specificato, per impostazione predefinita
- Quando si usa il percorso del file nel set di dati o nell'elenco di file nell'origine, il percorso radice della partizione è il percorso configurato nel set di dati.
- Quando si usa il filtro di cartelle con caratteri jolly, il percorso radice della partizione è il percorso secondario prima del primo carattere jolly.
- Quando si usa il prefisso, il percorso radice della partizione è un sottodirectory prima dell'ultimo "/".

Si supponga, ad esempio, di configurare il percorso nel set di dati come "root/folder/year=2020/month=08/day=27":
- Se si specifica il percorso radice della partizione come "root/folder/year=2020", l'attività di copia genererà altre due colonne e con valore month day "08" e "27" rispettivamente, oltre alle colonne all'interno dei file.
- Se il percorso radice della partizione non è specificato, non verrà generata alcuna colonna aggiuntiva.
No
maxConcurrentConnections Limite massimo di connessioni simultanee stabilite all'archivio dati durante l'esecuzione dell'attività. Specificare un valore solo quando si desidera limitare le connessioni simultanee. No

Esempio:

"activities":[
    {
        "name": "CopyFromAmazonS3",
        "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": "AmazonS3ReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Esempi di filtro file e cartelle

Questa sezione descrive il comportamento risultante del percorso cartella e del nome del file con i filtri con caratteri jolly.

bucket Key ricorsiva Struttura delle cartelle di origine e risultato del filtro (i file in grassetto sono stati recuperati)
bucket Folder*/* false bucket
    CartellaA
        File1.csv
        File2.json
        Sottocartella1
            File3.csv
            File4.json
            File5.csv
    AltraCartellaB
        File6.csv
bucket Folder*/* true bucket
    CartellaA
        File1.csv
        File2.json
        Sottocartella1
            File3.csv
            File4.json
            File5.csv
    AltraCartellaB
        File6.csv
bucket Folder*/*.csv false bucket
    CartellaA
        File1.csv
        File2.json
        Sottocartella1
            File3.csv
            File4.json
            File5.csv
    AltraCartellaB
        File6.csv
bucket Folder*/*.csv true bucket
    CartellaA
        File1.csv
        File2.json
        Sottocartella1
            File3.csv
            File4.json
            File5.csv
    AltraCartellaB
        File6.csv

Esempi di elenco di file

In questa sezione viene descritto il comportamento risultante dell'utilizzo di un percorso di elenco di file in un'attività Copy origine.

Si supponga di avere la struttura di cartelle di origine seguente e di voler copiare i file in grassetto:

Esempio di struttura di origine Contenuto in FileListToCopy.txt Data Factory configurazione
bucket
    CartellaA
        File1.csv
        File2.json
        Sottocartella1
            File3.csv
            File4.json
            File5.csv
    Metadati
        FileListToCopy.txt
File1.csv
Sottocartella1/File3.csv
Sottocartella1/File5.csv
Nel set di dati:
- Bucket: bucket
- Percorso cartella: FolderA

Nell'attività Copy seguente:
- Percorso elenco file: bucket/Metadata/FileListToCopy.txt

Il percorso dell'elenco di file punta a un file di testo nello stesso archivio dati che include un elenco di file da copiare, un file per riga, con il percorso relativo al percorso configurato nel set di dati.

Mantenere i metadati durante la copia

Quando si copiano file da Amazon S3 a Azure Data Lake Storage Gen2 o archiviazione BLOB di Azure, è possibile scegliere di mantenere i metadati del file insieme ai dati. Altre informazioni in Mantenere i metadati.

Proprietà dell'attività Lookup

Per altre informazioni sulle proprietà, vedere Attività Lookup.

Proprietà dell'attività GetMetadata

Per informazioni dettagliate sulle proprietà, controllare l'attività GetMetadata.

Proprietà dell'attività Delete

Per informazioni dettagliate sulle proprietà, selezionare Elimina attività.

Modalità legacy

Nota

I modelli seguenti sono ancora supportati come per la compatibilità con le versioni precedenti. È consigliabile usare il nuovo modello indicato in precedenza. L Data Factory'interfaccia utente di creazione è passata alla generazione del nuovo modello.

Modello di set di dati legacy

Proprietà Descrizione Obbligatoria
type La proprietà type del set di dati deve essere impostata su AmazonS3Object.
bucketName Il nome del bucket S3. Il filtro con caratteri jolly non è supportato. Sì per l'attività Copia o Ricerca, no per l'attività GetMetadata
Key Nome o filtro con caratteri jolly della chiave dell'oggetto S3 nel bucket specificato. Si applica solo quando la proprietà prefix non è specificata.

Il filtro con caratteri jolly è supportato sia per la parte cartella che per la parte del nome file. I caratteri jolly consentiti sono: * (corrispondenza di zero o più caratteri) e ? (corrispondenza di zero caratteri o di un carattere singolo).
- Esempio 1: "key": "rootfolder/subfolder/*.csv"
- Esempio 2: "key": "rootfolder/subfolder/???20180427.txt"
Vedere altri esempi in Esempi di filtro file e cartelle. Usare per eseguire l'escape se il nome effettivo della cartella o ^ del file contiene un carattere jolly o questo carattere di escape all'interno.
No
prefix Il prefisso per la chiave dell'oggetto S3. Vengono selezionati gli oggetti le cui chiavi iniziano con questo prefisso. Si applica solo quando la proprietà key non è specificata. No
version La versione dell'oggetto S3 se è stato abilitato il controllo delle versioni S3. Se non viene specificata una versione, verrà recuperata la versione più recente. No
modifiedDatetimeStart I file vengono filtrati in base all'attributo : ultima modifica. I file vengono selezionati se l'ora dell'ultima modifica è inclusa nell'intervallo di tempo tra modifiedDatetimeStart e modifiedDatetimeEnd. L'ora viene applicata in base al fuso orario UTC nel formato "2018-12-01T05:00:00Z".

Tenere presente che l'abilitazione di questa impostazione influirà sulle prestazioni complessive dello spostamento dei dati quando si vogliono filtrare grandi quantità di file.

Le proprietà possono essere NULL, il che significa che al set di dati non verrà applicato alcun filtro di attributi di file. Quando ha un valore datetime ma è NULL, verranno selezionati i file il cui ultimo attributo modificato è maggiore o uguale al valore modifiedDatetimeStart modifiedDatetimeEnd datetime. Quando ha un valore datetime ma è NULL, verranno selezionati i file il cui attributo dell'ultima modifica è minore del valore modifiedDatetimeEnd modifiedDatetimeStart datetime.
No
modifiedDatetimeEnd I file vengono filtrati in base all'attributo : ultima modifica. I file vengono selezionati se l'ora dell'ultima modifica è inclusa nell'intervallo di tempo tra modifiedDatetimeStart e modifiedDatetimeEnd. L'ora viene applicata in base al fuso orario UTC nel formato "2018-12-01T05:00:00Z".

Tenere presente che l'abilitazione di questa impostazione influirà sulle prestazioni complessive dello spostamento dei dati quando si vogliono filtrare grandi quantità di file.

Le proprietà possono essere NULL, il che significa che al set di dati non verrà applicato alcun filtro di attributo di file. Quando ha un valore datetime ma è NULL, verranno selezionati i file il cui ultimo attributo modificato è maggiore o uguale al valore modifiedDatetimeStart modifiedDatetimeEnd datetime. Quando ha un valore datetime ma è NULL, verranno selezionati i file il cui ultimo attributo modificato è minore del modifiedDatetimeEnd modifiedDatetimeStart valore datetime.
No
format Per copiare i file così come sono tra archivi basati su file (copia binaria), ignorare la sezione del formato nelle definizioni dei set di dati di input e di output.

Se si vuole analizzare o generare file con un formato specifico, sono supportati i tipi di formato file seguenti: TextFormat, JsonFormat, AvroFormat, OrcFormat, ParquetFormat. Impostare la proprietà type in format su uno di questi valori. Per altre informazioni, vedere le sezioni Formato testo, Formato JSON, Formato AVRO, Formato OCR e Formato Parquet.
No (solo per uno scenario di copia binaria)
compressione Specificare il tipo e il livello di compressione dei dati. Per altre informazioni, vedere l'articolo sui formati di file supportati e i codec di compressione.
I tipi supportati sono GZip, Deflate, BZip2 e ZipDeflate.
I livelli supportati sono Ottimale e Più veloce.
No

Suggerimento

Per copiare tutti i file in una cartella, specificare bucketName per il bucket e il prefisso per la parte della cartella.

Per copiare un singolo file con un nome specificato, specificare bucketName per il bucket e la chiave per la parte della cartella più il nome del file.

Per copiare un subset di file in una cartella, specificare bucketName per il bucket e la chiave per la parte della cartella più il filtro con caratteri jolly.

Esempio: uso del prefisso

{
    "name": "AmazonS3Dataset",
    "properties": {
        "type": "AmazonS3Object",
        "linkedServiceName": {
            "referenceName": "<Amazon S3 linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "bucketName": "testbucket",
            "prefix": "testFolder/test",
            "modifiedDatetimeStart": "2018-12-01T05:00:00Z",
            "modifiedDatetimeEnd": "2018-12-01T06:00:00Z",
            "format": {
                "type": "TextFormat",
                "columnDelimiter": ",",
                "rowDelimiter": "\n"
            },
            "compression": {
                "type": "GZip",
                "level": "Optimal"
            }
        }
    }
}

Esempio: uso della chiave e della versione (facoltativo)

{
    "name": "AmazonS3Dataset",
    "properties": {
        "type": "AmazonS3",
        "linkedServiceName": {
            "referenceName": "<Amazon S3 linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "bucketName": "testbucket",
            "key": "testFolder/testfile.csv.gz",
            "version": "XXXXXXXXXczm0CJajYkHf0_k6LhBmkcL",
            "format": {
                "type": "TextFormat",
                "columnDelimiter": ",",
                "rowDelimiter": "\n"
            },
            "compression": {
                "type": "GZip",
                "level": "Optimal"
            }
        }
    }
}

Modello di origine legacy per l'attività Copy

Proprietà Descrizione Obbligatoria
type La proprietà type dell'origine attività Copy deve essere impostata su FileSystemSource.
ricorsiva Indica se i dati vengono letti in modo ricorsivo dalle cartelle secondarie o solo dalla cartella specificata. Si noti che quando recursive è impostato su true e il sink è un archivio basato su file, una cartella o una sottocartella vuota non verrà copiata o creata nel sink.
I valori consentiti sono true (predefinito) e false.
No
maxConcurrentConnections Limite massimo di connessioni simultanee stabilite all'archivio dati durante l'esecuzione dell'attività. Specificare un valore solo quando si desidera limitare le connessioni simultanee. No

Esempio:

"activities":[
    {
        "name": "CopyFromAmazonS3",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Amazon S3 input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "FileSystemSource",
                "recursive": true
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Passaggi successivi

Per un elenco degli archivi dati supportati dal attività Copy in Azure Data Factory come origini e sink, vedere Archivi dati supportati.