Spostare dati da un server SFTP usando Azure Data Factory

Questo articolo illustra come usare l'attività di copia in Azure Data Factory per spostare dati da un server SFTP locale o cloud a un archivio dati sink supportato. Questo articolo si basa sull'articolo relativo alle attività di spostamento dei dati, che offre una panoramica generale dello spostamento dei dati con attività di copia e l'elenco degli archivi dati supportati come origini/sink.

Data Factory supporta attualmente solo lo spostamento di dati da un server SFTP ad altri archivi dati, non da altri archivi dati a un server SFTP. Supporta i server SFTP locali e cloud.

Nota

L'attività di copia non elimina il file di origine dopo che è stato correttamente copiato nella destinazione. Se è necessario eliminare il file di origine dopo una copia con esito positivo, creare un'attività personalizzata per eliminare il file e usare l'attività nella pipeline.

Scenari supportati e tipi di autenticazione

È possibile usare questo connettore SFTP per copiare dati da server cloud SFTP e SFTP locali. Quando ci si connette al server SFTP sono supportati i tipi di chiave di autenticazione Base e SshPublicKey.

Quando si copiano dati da un server SFTP locale, è necessario installare un gateway di gestione dati nella VM di Azure o nell'ambiente locale. Per informazioni dettagliate sul gateway, vedere Gateway di gestione dati. Vedere l'articolo sullo spostamento di dati tra sedi locali e cloud per istruzioni dettagliate sulla configurazione e sull'uso del gateway.

Introduzione

È possibile creare una pipeline con l'attività di copia che sposta i dati da un'origine SFTP usando diversi strumenti/API.

Proprietà del servizio collegato

La tabella seguente contiene le descrizioni degli elementi JSON specifici del servizio collegato FTP.

Proprietà Descrizione Obbligatorio
type La proprietà type deve essere impostata su Sftp.
host Nome o indirizzo IP del server SFTP.
port Porta su cui è in ascolto il server SFTP. Il valore predefinito è 21 No
authenticationType Specificare il tipo di autenticazione. Valori consentiti: Base, SshPublicKey.

Fare riferimento alle sezioni Uso dell'autenticazione di base e Uso dell'autenticazione con chiave pubblica SSH rispettivamente per vedere altre proprietà ed esempi JSON.
skipHostKeyValidation Specificare se si desidera ignorare la convalida tramite della chiave host. No. Il valore predefinito è: falso
hostKeyFingerprint Specificare le impronte digitali della chiave host. Sì se skipHostKeyValidation è impostato su falso.
gatewayName Nome del gateway di gestione dati per connettersi a un server SFTP locale. Sì se si copiano i dati da un server SFTP locale.
encryptedCredential Credenziali crittografate per accedere al server SFTP. Generato automaticamente quando si specifica l'autenticazione di base (nome utente e password) o l'autenticazione SshPublicKey (nome utente e percorso della chiave privato o contenuto) nella copia guidata o nella finestra di dialogo popup ClickOnce. No. Applicare solo se si copiano i dati da un server SFTP locale.

Uso dell'autenticazione di base

Per usare l'autenticazione di base, impostare authenticationType come Basic e specificare le proprietà seguenti oltre a quelle generiche del connettore SFTP introdotte nell'ultima sezione:

Proprietà Descrizione Obbligatorio
username Utente che ha accesso al server SFTP.
password Password per l'utente (nome utente).

Esempio: autenticazione di base

{
    "name": "SftpLinkedService",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "mysftpserver",
            "port": 22,
            "authenticationType": "Basic",
            "username": "xxx",
            "password": "xxx",
            "skipHostKeyValidation": false,
            "hostKeyFingerPrint": "ssh-rsa 2048 xx:00:00:00:xx:00:x0:0x:0x:0x:0x:00:00:x0:x0:00",
            "gatewayName": "mygateway"
        }
    }
}

Esempio: autenticazione di base con credenziali crittografate

{
    "name": "SftpLinkedService",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "mysftpserver",
            "port": 22,
            "authenticationType": "Basic",
            "username": "xxx",
            "encryptedCredential": "xxxxxxxxxxxxxxxxx",
            "skipHostKeyValidation": false,
            "hostKeyFingerPrint": "ssh-rsa 2048 xx:00:00:00:xx:00:x0:0x:0x:0x:0x:00:00:x0:x0:00",
            "gatewayName": "mygateway"
        }
      }
}

Uso dell'autenticazione con chiave pubblica SSH

Per usare l'autenticazione con chiave pubblica SSH, impostare authenticationType su SshPublicKey e specificare le proprietà seguenti oltre a quelle generiche del connettore SFTP presentate nell'ultima sezione:

Proprietà Descrizione Obbligatorio
username Utente che ha accesso al server SFTP
privateKeyPath Specificare un percorso assoluto al file di chiave privato a cui il gateway può accedere. Specificare privateKeyPath o privateKeyContent.

Applicare solo se si copiano i dati da un server SFTP locale.
privateKeyContent Una stringa serializzata del contenuto di chiave privata. La copia guidata può leggere il file di chiave privata ed estrarre automaticamente il contenuto della chiave privata. Se si usa un qualsiasi altro strumento/SDK, usare la proprietà privateKeyPath. Specificare privateKeyPath o privateKeyContent.
passPhrase Specificare la passphrase o la password per decrittografare la chiave privata se il file della chiave è protetto da una passphrase. Sì se il file della chiave privata è protetto da una passphrase.
Nota

Il connettore SFTP supporta solo chiavi OpenSSH. Assicurarsi che il file della chiave sia nel formato corretto. Per eseguire una conversione dal formato ppk al formato OpenSSH, è possibile usare lo strumento Putty.

Esempio: Autenticazione SshPublicKey con chiave privata filePath

{
    "name": "SftpLinkedServiceWithPrivateKeyPath",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "mysftpserver",
            "port": 22,
            "authenticationType": "SshPublicKey",
            "username": "xxx",
            "privateKeyPath": "D:\\privatekey_openssh",
            "passPhrase": "xxx",
            "skipHostKeyValidation": true,
            "gatewayName": "mygateway"
        }
    }
}

Esempio: Autenticazione SshPublicKey con contenuto della chiave privata

{
    "name": "SftpLinkedServiceWithPrivateKeyContent",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "mysftpserver.westus.cloudapp.azure.com",
            "port": 22,
            "authenticationType": "SshPublicKey",
            "username": "xxx",
            "privateKeyContent": "<base64 string of the private key content>",
            "passPhrase": "xxx",
            "skipHostKeyValidation": true
        }
    }
}

Proprietà dei set di dati

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione di set di dati, vedere l'articolo sulla creazione di set di dati. Le sezioni come struttura, disponibilità e criteri di un set di dati JSON sono simili per tutti i tipi di set di dati.

La sezione typeProperties è diversa per ogni tipo di set di dati. Fornisce informazioni specifiche del tipo di set di dati. La sezione typeProperties per un set di dati di tipo FileShare presenta le proprietà seguenti:

Proprietà Descrizione Obbligatorio
folderPath Sottopercorso alla cartella. Usare il carattere di escape "\" per i caratteri speciali nella stringa. Per ottenere alcuni esempi, vedere Servizio collegato di esempio e definizioni del set di dati .

È possibile combinare questa proprietà con partitionBy per ottenere percorsi di cartelle basati su data e ora di inizio/fine delle sezioni.
fileName Specificare il nome del file in folderPath se si vuole che la tabella faccia riferimento a un file specifico nella cartella. Se non si specifica alcun valore per questa proprietà, la tabella punta a tutti i file nella cartella.

Quando fileName non viene specificato per un set di dati di output, il nome del file generato sarà nel formato seguente:

Data..txt, ad esempio: Data.0a405f8a-93ff-4c6f-b3be-f69616f1df7a.txt
No
fileFilter Specificare un filtro da usare per selezionare un sottoinsieme di file in folderPath anziché tutti i file.

I valori consentiti sono: * (più caratteri) e ? (carattere singolo).

Esempi 1: "fileFilter": "*.log"
Esempio 2: "fileFilter": 2014-1-?.txt"

fileFilter è applicabile per un set di dati di input FileShare. Questa proprietà non è supportata con HDFS.
No
partitionedBy partitionedBy può essere usato per specificare un valore folderPath dinamico e un nome file per i dati di una serie temporale. Ad esempio, folderPath con parametri per ogni ora di dati. No
format 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.

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.
No
compressione Specificare il tipo e il livello di compressione dei dati. I tipi supportati sono GZip, Deflate, BZip2 e ZipDeflate. I livelli supportati sono Ottimale e Più veloce. Per altre informazioni, vedere File e formati di compressione in Azure Data Factory. No
useBinaryTransfer Specificare se usare la modalità di trasferimento binario. True per la modalità binaria e false per ASCII. Valore predefinito: True. Questa proprietà può essere usata solo quando il tipo di servizio collegato associato è di tipo: FtpServer. No
Nota

filename e fileFilter non possono essere usati contemporaneamente.

Uso della proprietà partionedBy

Come indicato nella sezione precedente, partitionedBy può essere usato per specificare un valore folderPath dinamico e un nome file per i dati di una serie temporale. È possibile eseguire questa operazione con le macro della data factory e le variabili di sistema SliceStart, SliceEnd, che indicano il periodo di tempo logico per una sezione di dati specificata.

Per informazioni sui set di dati delle serie temporali, sulla pianificazione e sulle sezioni, vedere gli articoli Creazione di set di dati, Pianificazione ed esecuzione e Creazione di pipeline.

Esempio 1.

"folderPath": "wikidatagateway/wikisampledataout/{Slice}",
"partitionedBy":
[
    { "name": "Slice", "value": { "type": "DateTime", "date": "SliceStart", "format": "yyyyMMddHH" } },
],

In questo esempio {Slice} viene sostituito con il valore della variabile di sistema SliceStart di Data Factory nel formato (AAAAMMGGHH) specificato. SliceStart fa riferimento all'ora di inizio della sezione. La proprietà folderPath è diversa per ogni sezione. Esempio: wikidatagateway/wikisampledataout/2014100103 o wikidatagateway/wikisampledataout/2014100104.

Esempio 2:

"folderPath": "wikidatagateway/wikisampledataout/{Year}/{Month}/{Day}",
"fileName": "{Hour}.csv",
"partitionedBy":
 [
    { "name": "Year", "value": { "type": "DateTime", "date": "SliceStart", "format": "yyyy" } },
    { "name": "Month", "value": { "type": "DateTime", "date": "SliceStart", "format": "MM" } },
    { "name": "Day", "value": { "type": "DateTime", "date": "SliceStart", "format": "dd" } },
    { "name": "Hour", "value": { "type": "DateTime", "date": "SliceStart", "format": "hh" } }
],

In questo esempio l'anno, il mese, il giorno e l'ora di SliceStart vengono estratti in variabili separate che vengono usate dalle proprietà folderPath e fileName.

Proprietà dell'attività di copia

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, fare riferimento all'articolo Creazione di pipeline. Per tutti i tipi di attività sono disponibili proprietà come nome, descrizione, tabelle di input e output e criteri.

Le proprietà disponibili nella sezione typeProperties dell'attività variano invece in base al tipo di attività. Per l'attività di copia, le proprietà del tipo variano in base ai tipi di origine e sink.

Nell'attività di copia con origine di tipo FileSystemSource, nella sezione typeProperties sono disponibili le proprietà seguenti:

Proprietà Descrizione Valori consentiti Obbligatorio
ricorsiva Indica se i dati vengono letti in modo ricorsivo dalle cartelle secondarie o solo dalla cartella specificata. True, False (valore predefinito) No

Formati di file e di compressione supportati

Per i dettagli, vedere l'articolo relativo ai file e formati di compressione in Azure Data Factory.

Esempio JSON: copiare i dati dal server SFTP in BLOB di Azure

L'esempio seguente fornisce le definizioni JSON campione da usare per creare una pipeline con il Portale di Azure, Visual Studio o Azure PowerShell. Illustrano come copiare dati da un'origine SFTP in un archivio BLOB di Azure. Tuttavia, i dati possono essere copiati direttamente da una delle origini in qualsiasi sink dichiarato qui usando l'attività di copia in Data factory di Azure.

Importante

Questo esempio fornisce frammenti di codice JSON. Non include istruzioni dettagliate per la creazione della data factory. Le istruzioni dettagliate sono disponibili nell'articolo Spostare dati tra origini locali e il cloud .

L'esempio include le entità di Data factory seguenti:

Nell'esempio i dati vengono copiati da un server SFTP a un BLOB di Azure ogni ora. Le proprietà JSON usate in questi esempi sono descritte nelle sezioni riportate dopo gli esempi.

Servizio collegato SFTP

Questo esempio usa l'autenticazione di base con il nome utente e la password in testo normale. È possibile anche usare uno dei tre metodi seguenti:

  • Autenticazione di base con credenziali crittografate
  • Autenticazione con chiave pubblica SSH

Per i diversi tipi di autenticazione disponibili, vedere la sezione relativa al servizio collegato FTP.


{
    "name": "SftpLinkedService",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "mysftpserver",
            "port": 22,
            "authenticationType": "Basic",
            "username": "myuser",
            "password": "mypassword",
            "skipHostKeyValidation": false,
            "hostKeyFingerPrint": "ssh-rsa 2048 xx:00:00:00:xx:00:x0:0x:0x:0x:0x:00:00:x0:x0:00",
            "gatewayName": "mygateway"
        }
    }
}

Servizio collegato Archiviazione di Azure

{
  "name": "AzureStorageLinkedService",
  "properties": {
    "type": "AzureStorage",
    "typeProperties": {
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountname>;AccountKey=<accountkey>"
    }
  }
}

Set di dati di input SFTP

Questo set di dati fa riferimento alla cartella FTP mysharedfolder e al file test.csv. La pipeline copia il file nella destinazione.

Impostando "external": "true" si comunica al servizio Data Factory che il set di dati è esterno alla data factory e non è prodotto da un'attività al suo interno.

{
  "name": "SFTPFileInput",
  "properties": {
    "type": "FileShare",
    "linkedServiceName": "SftpLinkedService",
    "typeProperties": {
      "folderPath": "mysharedfolder",
      "fileName": "test.csv"
    },
    "external": true,
    "availability": {
      "frequency": "Hour",
      "interval": 1
    }
  }
}

Set di dati di output del BLOB di Azure

I dati vengono scritti in un nuovo BLOB ogni ora (frequenza: ora, intervallo: 1). Il percorso della cartella per il BLOB viene valutato dinamicamente in base all'ora di inizio della sezione in fase di elaborazione. Il percorso della cartella usa le parti anno, mese, giorno e ora dell'ora di inizio.

{
    "name": "AzureBlobOutput",
    "properties": {
        "type": "AzureBlob",
        "linkedServiceName": "AzureStorageLinkedService",
        "typeProperties": {
            "folderPath": "mycontainer/sftp/yearno={Year}/monthno={Month}/dayno={Day}/hourno={Hour}",
            "format": {
                "type": "TextFormat",
                "rowDelimiter": "\n",
                "columnDelimiter": "\t"
            },
            "partitionedBy": [
                {
                    "name": "Year",
                    "value": {
                        "type": "DateTime",
                        "date": "SliceStart",
                        "format": "yyyy"
                    }
                },
                {
                    "name": "Month",
                    "value": {
                        "type": "DateTime",
                        "date": "SliceStart",
                        "format": "MM"
                    }
                },
                {
                    "name": "Day",
                    "value": {
                        "type": "DateTime",
                        "date": "SliceStart",
                        "format": "dd"
                    }
                },
                {
                    "name": "Hour",
                    "value": {
                        "type": "DateTime",
                        "date": "SliceStart",
                        "format": "HH"
                    }
                }
            ]
        },
        "availability": {
            "frequency": "Hour",
            "interval": 1
        }
    }
}

Pipeline con attività di copia

La pipeline contiene un'attività di copia configurata per usare i set di dati di input e output ed è programmata per essere eseguita ogni ora. Nella definizione JSON della pipeline, il tipo di origine è impostato su FileSystemSource e il tipo di sink è impostato su BlobSink.

{
    "name": "pipeline",
    "properties": {
        "activities": [{
            "name": "SFTPToBlobCopy",
            "inputs": [{
                "name": "SFTPFileInput"
            }],
            "outputs": [{
                "name": "AzureBlobOutput"
            }],
            "type": "Copy",
            "typeProperties": {
                "source": {
                    "type": "FileSystemSource"
                },
                "sink": {
                    "type": "BlobSink"
                }
            },
            "scheduler": {
                "frequency": "Hour",
                "interval": 1
            },
            "policy": {
                "concurrency": 1,
                "executionPriorityOrder": "NewestFirst",
                "retry": 1,
                "timeout": "00:05:00"
            }
        }],
        "start": "2017-02-20T18:00:00Z",
        "end": "2017-02-20T19:00:00Z"
    }
}

Ottimizzazione delle prestazioni

Per informazioni sui fattori chiave che influiscono sulle prestazioni dello spostamento dei dati, ovvero dell'attività di copia, in Azure Data Factory e sui vari modi per ottimizzare tali prestazioni, vedere la Guida alle prestazioni delle attività di copia e all'ottimizzazione.

Passaggi successivi

Vedere gli articoli seguenti: