Copiare dati dal server FTP usando Azure Data Factory o Synapse Analytics

  • Articolo

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Suggerimento

Provare Data Factory in Microsoft Fabric, una soluzione di analisi completa per le aziende. Microsoft Fabric copre tutti gli elementi, dallo spostamento dei dati all'analisi scientifica dei dati, all'analisi in tempo reale, alla business intelligence e alla creazione di report. Scopri come avviare gratuitamente una nuova versione di valutazione .

Questo articolo illustra come copiare i dati dal server FTP. Per altre informazioni, vedere gli articoli introduttivi per Azure Data Factory e Synapse Analytics.

Funzionalità supportate

Questo connettore FTP è supportato per le funzionalità seguenti:

Funzionalità supportate IR
attività Copy (source/-) ① ②
Attività Lookup ① ②
Attività GetMetadata ① ②
Attività Delete ① ②

(1) Runtime di integrazione di Azure (2) Runtime di integrazione self-hosted

In particolare, il connettore FTP supporta:

Il connettore FTP supporta il server FTP in esecuzione in modalità passiva. La modalità attiva non è supportata.

Prerequisiti

Se l'archivio dati si trova all'interno di una rete locale, una rete virtuale di Azure o un cloud privato virtuale di Amazon, è necessario configurare un runtime di integrazione self-hosted per connettersi.

Se l'archivio dati è un servizio dati cloud gestito, è possibile usare Azure Integration Runtime. Se l'accesso è limitato agli indirizzi IP approvati nelle regole del firewall, è possibile aggiungere indirizzi IP del runtime di integrazione di Azure all'elenco elementi consentiti.

È anche possibile usare la funzionalità di runtime di integrazione della rete virtuale gestita in Azure Data Factory per accedere alla rete locale senza installare e configurare un runtime di integrazione self-hosted.

Per altre informazioni sui meccanismi di sicurezza di rete e sulle opzioni supportate da Data Factory, vedere strategie di accesso ai dati.

Introduzione

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

Creare un servizio collegato a un server FTP usando l'interfaccia utente

Usare la procedura seguente per creare un servizio collegato a un server FTP nell'interfaccia utente di portale di Azure.

  1. Passare alla scheda Gestisci nell'area di lavoro di Azure Data Factory o Synapse e selezionare Servizi collegati, quindi fare clic su Nuovo:

  2. Cercare FTP e selezionare il connettore FTP.

    Screenshot of the FTP connector.

  3. Configurare i dettagli del servizio, testare la connessione e creare il nuovo servizio collegato.

    Screenshot of linked service configuration for an FTP server.

Dettagli di configurazione di Connessione or

Le sezioni seguenti forniscono informazioni dettagliate sulle proprietà usate per definire entità specifiche per FTP.

Proprietà del servizio collegato

Per il servizio collegato di FTP sono supportate le proprietà seguenti:

Proprietà Descrizione Richiesto
Tipo La proprietà type deve essere impostata su: FtpServer. Sì
host Specificare il nome o indirizzo IP del server FTP. Sì
port Specificare la porta su cui è in ascolto il server FTP.
I valori consentiti sono: integer; il valore predefinito è 21.		 No
enableSsl Specificare se usare FTP su un canale SSL/TLS.
I valori consentiti sono: true (predefinito), false.		 No
enableServerCertificateValidation Specificare se abilitare la convalida del certificato TLS/SSL del server quando si usa FTP sul canale SSL/TLS.
I valori consentiti sono: true (predefinito), false.		 No
authenticationType Specificare il tipo di autenticazione.
I valori consentiti sono: Di base, Anonima		 Sì
userName Specificare l'utente che ha accesso al server FTP. No
password Specificare la password per l'utente (userName). Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro o fare riferimento a un segreto archiviato in Azure Key Vault. No
connectVia Il runtime di integrazione da usare per la connessione all'archivio dati. Per altre informazioni, vedere la sezione Prerequisiti. Se non specificato, viene usato il runtime di integrazione di Azure predefinito. No

Nota

Il connettore FTP supporta l'accesso al server FTP senza crittografia o con crittografia SSL/TLS esplicita; non supporta la crittografia SSL/TLS implicita.

Esempio 1: uso dell'autenticazione anonima

{
    "name": "FTPLinkedService",
    "properties": {
        "type": "FtpServer",
        "typeProperties": {
            "host": "<ftp server>",
            "port": 21,
            "enableSsl": true,
            "enableServerCertificateValidation": true,
            "authenticationType": "Anonymous"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Esempio 2: uso dell'autenticazione di base

{
    "name": "FTPLinkedService",
    "properties": {
        "type": "FtpServer",
        "typeProperties": {
            "host": "<ftp server>",
            "port": 21,
            "enableSsl": true,
            "enableServerCertificateValidation": true,
            "authenticationType": "Basic",
            "userName": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "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 FTP nelle impostazioni location nel set di dati basato sul formato:

Proprietà Descrizione Richiesto
Tipo La proprietà type in location nel set di dati deve essere impostata su FtpServerLocation. Sì
folderPath Percorso della cartella. Se si intende usare un carattere jolly per filtrare le cartelle, ignorare questa impostazione e specificarla nelle impostazioni dell'origine dell'attività. No
fileName Nome del file nel percorso cartella specificato. Se si intende usare un carattere jolly per filtrare i file, ignorare questa impostazione e specificarla nelle impostazioni dell'origine dell'attività. No

Esempio:

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<FTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "FtpServerLocation",
                "folderPath": "root/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 presenta un elenco delle proprietà supportate dall'origine FTP.

FTP come 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 FTP nelle impostazioni storeSettings nell'origine di copia basata sul formato:

Proprietà Descrizione Richiesto
Tipo La proprietà type in storeSettings deve essere impostata su FtpReadSettings. Sì
Individuare i file da copiare:
OPZIONE 1: percorso statico
 Copia dal percorso di cartella/file specificato nel set di dati. Se si vogliono copiare tutti i file da una cartella, specificare anche wildcardFileName come *.
OPZIONE 2: carattere jolly
- wildcardFolderPath		 Percorso della cartella con caratteri jolly per filtrare le cartelle di origine.
I caratteri jolly consentiti sono: * (corrisponde a zero o più caratteri) e ? (corrisponde a zero caratteri o a un carattere singolo). Usare ^ come carattere di escape se il nome effettivo della cartella include caratteri jolly o questo carattere di escape.
Vedere altri esempi in Esempi di filtro file e cartelle.		 No
OPZIONE 2: carattere jolly
- wildcardFileName		 Nome file con caratteri jolly nel percorso folderPath/wildcardFolderPath specificato 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 il carattere escape se il nome effettivo del file include caratteri jolly o escape. Vedere altri esempi in Esempi di filtro file e cartelle.		 Sì
OPZIONE 3: 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 il nome del file nel set di dati. Per altri esempi, vedere Esempi di elenco di file.		 No
Impostazioni aggiuntive:
recursive Indica se i dati vengono letti in modo ricorsivo dalle cartelle secondarie o solo dalla cartella specificata. Si noti che quando la proprietà recursive è impostata 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 il corretto spostamento nell'archivio di destinazione. L'eliminazione del file è per file, quindi quando l'attività di copia ha esito negativo, si noterà che alcuni file sono già stati copiati nella destinazione ed eliminati dall'origine, mentre altri rimangono nell'archivio di origine.
Questa proprietà è valida solo nello scenario di copia dei file binari. Valore predefinito: false.		 No
useBinaryTransfer Specificare se usare la modalità di trasferimento binario. I valori sono true per la modalità binaria (predefinita) e false per ASCII. 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 delle cartelle con caratteri jolly, il percorso radice della partizione è il sottopercorso prima del primo carattere jolly.

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 month e day con il valore "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
disableChunking Quando si copiano dati da FTP, il servizio tenta di ottenere prima la lunghezza del file, quindi dividere il file in più parti e leggerli in parallelo. Specificare se il server FTP supporta il recupero della lunghezza del file o la ricerca di una determinata differenza.
I valori consentiti sono false (impostazione predefinita), true.		 No

Esempio:

"activities":[
    {
        "name": "CopyFromFTP",
        "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": "FtpReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv",
                    "disableChunking": false
                }
            },
            "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.

folderPath fileName recursive Struttura delle cartelle di origine e risultato del filtro (i file in grassetto sono stati recuperati)
Folder* (vuoto, usare valore predefinito) falso CartellaA
    File1.csv
    File2.json
    Sottocartella1
        File3.csv
        File4.json
        File5.csv
AltraCartellaB
    File6.csv
Folder* (vuoto, usare valore predefinito) true CartellaA
    File1.csv
    File2.json
    Sottocartella1
        File3.csv
        File4.json
        File5.csv
AltraCartellaB
    File6.csv
Folder* *.csv falso CartellaA
    File1.csv
    File2.json
    Sottocartella1
        File3.csv
        File4.json
        File5.csv
AltraCartellaB
    File6.csv
Folder* *.csv true CartellaA
    File1.csv
    File2.json
    Sottocartella1
        File3.csv
        File4.json
        File5.csv
AltraCartellaB
    File6.csv

Esempi di elenco di file

Questa sezione descrive il comportamento risultante dall'uso del percorso di elenco file nell'origine dell'attività di copia.

Si supponga di disporre della struttura di cartelle di origine seguente e di voler copiare i file in grassetto:

Esempio di struttura di origine Contenuto in FileListToCopy.txt Configurazione
root
    CartellaA
        File1.csv
        File2.json
        Sottocartella1
            File3.csv
            File4.json
            File5.csv
    Metadati UFX
        FileListToCopy.txt		 File1.csv
Sottocartella1/File3.csv
Sottocartella1/File5.csv		 Nel set di dati:
- Percorso cartella: root/FolderA

Nell'origine dell'attività Copy:
- Percorso elenco file: root/Metadata/FileListToCopy.txt

Il percorso dell'elenco di file fa riferimento 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 del percorso configurato nel set di dati.

Proprietà dell'attività Lookup

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

Proprietà dell'attività GetMetadata

Per altre informazioni sulle proprietà, vedere Attività GetMetadata

Proprietà dell'attività Delete

Per altre informazioni sulle proprietà, vedere Attività Delete

Modalità legacy

Nota

I modelli seguenti sono ancora supportati così come sono per la compatibilità con le versioni precedenti. Si consiglia di usare il nuovo modello menzionato nelle sezioni precedenti in futuro e l'interfaccia utente di creazione è passata alla generazione del nuovo modello.

Modello di set di dati legacy

Proprietà Descrizione Richiesto
Tipo La proprietà type del set di dati deve essere impostata su: FileShare Sì
folderPath Percorso della cartella. I filtri con caratteri jolly sono supportati, i caratteri jolly consentiti sono: * (corrispondenza di zero o più caratteri) e ? (corrispondenza di zero caratteri o di un carattere singolo). Usare ^ per applicare una sequenza di escape se il nome effettivo della cartella include caratteri jolly o tale carattere di escape.

Esempi: cartellaradice/sottocartella/. Vedere altri esempi in Esempi di filtro file e cartelle.		 Sì
fileName Filtro con nome o carattere jolly per i file nell'elemento "folderPath" specificato. Se non si specifica alcun valore per questa proprietà, il set di dati punta a tutti i file nella cartella.

Per un filtro, i caratteri jolly consentiti sono: * (corrispondenza di zero o più caratteri) e ? (corrispondenza di zero caratteri o di un carattere singolo).
- Esempio 1: "fileName": "*.csv"
- Esempio 2: "fileName": "???20180427.txt"
Usare ^ per il carattere escape se il nome effettivo del file include caratteri jolly o escape.		 No
format Per copiare i file così come sono tra archivi basati su file (copia binaria), è possibile ignorare la sezione del formato nelle definizioni dei set di dati di input e di output.

Se si vuole analizzare file con un formato specifico, sono supportati i tipi di formato seguenti: TextFormat, JsonFormat, AvroFormat, OrcFormat e ParquetFormat. Impostare la proprietà type nell'area format su uno di questi valori. Per altre informazioni, vedere le sezioni TextFormat, JsonFormat, AvroFormat, OrcFormat e ParquetFormat.		 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
useBinaryTransfer Specificare se usare la modalità di trasferimento binario. I valori sono true per la modalità binaria (predefinita) e false per ASCII. No

Suggerimento

Per copiare tutti i file in una cartella, specificare solo folderPath.
Per copiare un singolo file con un determinato nome, specificare folderPath con il percorso della cartella e fileName con il nome del file.
Per copiare un subset di file in una cartella, specificare folderPath con il percorso della cartella e fileName con il filtro con caratteri jolly.

Nota

Se si usa la proprietà "fileFilter" per il filtro dei file, è comunque supportata senza alcuna modifica, mentre in futuro verrà consigliato di usare la nuova funzionalità di filtro aggiunta a "fileName".

Esempio:

{
    "name": "FTPDataset",
    "properties": {
        "type": "FileShare",
        "linkedServiceName":{
            "referenceName": "<FTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "folderPath": "folder/subfolder/",
            "fileName": "myfile.csv.gz",
            "format": {
                "type": "TextFormat",
                "columnDelimiter": ",",
                "rowDelimiter": "\n"
            },
            "compression": {
                "type": "GZip",
                "level": "Optimal"
            }
        }
    }
}

Modello di origine dell'attività di copia legacy

Proprietà Descrizione Richiesto
Tipo La proprietà type dell'origine dell'attività di copia deve essere impostata su: FileSystemSource Sì
recursive Indica se i dati vengono letti in modo ricorsivo dalle cartelle secondarie o solo dalla cartella specificata. Si noti che se recursive è impostata su true e il sink è un archivio basato su file, la cartella o la sottocartella vuota non verrà copiata o creata nel sink.
I valori consentiti sono: true (predefinito), 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": "CopyFromFTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<FTP input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "FileSystemSource",
                "recursive": true
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Contenuto correlato

Per un elenco degli archivi dati supportati come origini e sink dall'attività di copia, vedere archivi dati supportati.