Copiare e trasformare i dati nel server SFTP usando Azure Data Factory o Azure Synapse Analytics

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Questo articolo illustra come usare l'attività di copia per copiare dati da e verso il server FTP sicuro (SFTP) e usare Flusso di dati per trasformare i dati nel server SFTP. Per altre informazioni, vedere l'articolo introduttivo per Azure Data Factory o Azure Synapse Analytics.

Funzionalità supportate

Questo connettore SFTP è supportato per le funzionalità seguenti:

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

In particolare, il connettore SFTP supporta:

• Copia di file da e nel server SFTP usando la chiave pubblica SSH di base o l'autenticazione a più fattori.
• La copia di file così come è o tramite l'analisi o la generazione di file con i formati di file e i codec di compressione supportati.

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:

• Strumento Copia dati
• Il portale di Azure
• .NET SDK
• The Python SDK
• Azure PowerShell
• The REST API
• Modello di Azure Resource Manager

Creare un servizio collegato SFTP usando l'interfaccia utente

Usare la procedura seguente per creare un servizio collegato SFTP 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:

   • Azure Data Factory
   • Azure Synapse

   

2. Cercare SFTP e selezionare il connettore SFTP.

   

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

   

Dettagli di configurazione di Connessione or

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

Proprietà del servizio collegato

Per il servizio collegato SFTP sono supportate le proprietà seguenti:

Usare l'autenticazione di base

Per usare l'autenticazione di base, impostare la proprietà authenticationType su Basic e specificare le proprietà seguenti oltre alle proprietà generico del connettore SFTP introdotte nella sezione precedente:

Esempio:

{
    "name": "SftpLinkedService",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "<sftp server>",
            "port": 22,
            "skipHostKeyValidation": false,
            "hostKeyFingerPrint": "ssh-rsa 2048 xx:00:00:00:xx:00:x0:0x:0x:0x:0x:00:00:x0:x0:00",
            "authenticationType": "Basic",
            "userName": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of integration runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Usare l'autenticazione con chiave pubblica SSH

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

Esempio 1: autenticazione SshPublicKey con chiave privata filePath

{
    "name": "SftpLinkedService",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "<sftp server>",
            "port": 22,
            "skipHostKeyValidation": true,
            "authenticationType": "SshPublicKey",
            "userName": "xxx",
            "privateKeyPath": "D:\\privatekey_openssh",
            "passPhrase": {
                "type": "SecureString",
                "value": "<pass phrase>"
            }
        },
        "connectVia": {
            "referenceName": "<name of integration runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Esempio 2: autenticazione SshPublicKey con contenuto della chiave privata

{
    "name": "SftpLinkedService",
    "type": "Linkedservices",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "<sftp server>",
            "port": 22,
            "skipHostKeyValidation": true,
            "authenticationType": "SshPublicKey",
            "userName": "<username>",
            "privateKeyContent": {
                "type": "SecureString",
                "value": "<base64 string of the private key content>"
            },
            "passPhrase": {
                "type": "SecureString",
                "value": "<pass phrase>"
            }
        },
        "connectVia": {
            "referenceName": "<name of integration runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Usare l'autenticazione a più fattori

Per usare l'autenticazione a più fattori, ovvero una combinazione di autenticazioni di chiave pubblica SSH e di base, specificare il nome utente, la password e le informazioni sulla chiave privata descritte nelle sezioni precedenti.

Esempio: autenticazione a più fattori

{
    "name": "SftpLinkedService",
    "properties": {
        "type": "Sftp",
        "typeProperties": {
            "host": "<host>",
            "port": 22,
            "authenticationType": "MultiFactor",
            "userName": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            },
            "privateKeyContent": {
                "type": "SecureString",
                "value": "<base64 encoded private key content>"
            },
            "passPhrase": {
                "type": "SecureString",
                "value": "<passphrase for private key>"
            }
        },
        "connectVia": {
            "referenceName": "<name of integration runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Proprietà del set di dati

Per un elenco completo di sezioni e 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.

• Formato Avro
• Formato binario
• Formato testo delimitato
• Formato Excel
• Formato JSON
• Formato ORC
• Formato Parquet
• Formato XML

Le proprietà seguenti sono supportate per SFTP nelle location impostazioni nel set di dati basato sul formato:

Esempio:

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

Proprietà dell'attività di copia

Per un elenco completo di sezioni e proprietà disponibili per la definizione delle attività, vedere l'articolo Pipeline. In questa sezione viene fornito un elenco di proprietà supportate dall'origine SFTP.

SFTP come origine

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

• Formato Avro
• Formato binario
• Formato testo delimitato
• Formato Excel
• Formato JSON
• Formato ORC
• Formato Parquet
• Formato XML

Le proprietà seguenti sono supportate per SFTP nelle storeSettings impostazioni nell'origine copia basata sul formato:

Esempio:

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

SFTP come sink

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

• Formato Avro
• Formato binario
• Formato testo delimitato
• Formato JSON
• Formato ORC
• Formato Parquet

Le proprietà seguenti sono supportate per SFTP nelle storeSettings impostazioni in un sink di copia basato sul formato:

Esempio:

"activities":[
    {
        "name": "CopyToSFTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "BinarySink",
                "storeSettings":{
                    "type": "SftpWriteSettings",
                    "copyBehavior": "PreserveHierarchy"
                }
            }
        }
    }
]

Esempi di filtro file e cartelle

In questa sezione viene descritto il comportamento risultante dall'uso di filtri con caratteri jolly con percorsi di cartelle e nomi di file.

Esempi di elenco di file

Questa tabella descrive il comportamento risultante dall'uso di un percorso di elenco di file nell'origine attività Copy. Si presuppone che sia presente la struttura di cartelle di origine seguente e si voglia copiare i file in grassetto:

Proprietà del flusso di dati per mapping

Quando si trasformano i dati nei flussi di dati di mapping, è possibile leggere e scrivere file da SFTP nei formati seguenti:

• Avro
• Testo delimitato
• Excel
• JSON
• ORC
• Parquet
• XML

Le impostazioni specifiche del formato si trovano nella documentazione per tale formato. Per altre informazioni, vedere Trasformazione dell'origine nel flusso di dati di mapping e Trasformazione Sink nel flusso di dati di mapping.

Trasformazione origine

Nella tabella seguente sono elencate le proprietà supportate dall'origine SFTP. È possibile modificare queste proprietà nella scheda Opzioni origine. Quando si usa il set di dati inline, verranno visualizzate impostazioni aggiuntive, che corrispondono alle proprietà descritte nella sezione proprietà del set di dati.

Esempio di script di origine SFTP

Quando si usa il set di dati SFTP come tipo di origine, lo script del flusso di dati associato è:

source(allowSchemaDrift: true,
	validateSchema: false,
	ignoreNoFilesFound: true,
	purgeFiles: true,
	fileList: true,
	modifiedAfter: (toTimestamp(1647388800000L)),
	modifiedBefore: (toTimestamp(1647561600000L)),
	partitionRootPath: 'partdata',
	wildcardPaths:['partdata/**/*.csv']) ~> SFTPSource

Trasformazione sink

Nella tabella seguente sono elencate le proprietà supportate dal sink SFTP. È possibile modificare queste proprietà nella scheda Impostazioni. Quando si usa il set di dati inline, verranno visualizzate impostazioni aggiuntive, che corrispondono alle proprietà descritte nella sezione proprietà del set di dati.

Esempio di script sink SFTP

Quando si usa il set di dati SFTP come tipo di sink, lo script del flusso di dati associato è:

IncomingStream sink(allowSchemaDrift: true,
	validateSchema: false,
	filePattern:'loans[n].csv',
	truncate: true,
	skipDuplicateMapInputs: true,
	skipDuplicateMapOutputs: true) ~> SFTPSink

Proprietà dell'attività Lookup

Per informazioni sulle proprietà dell'attività di ricerca, vedere Attività di ricerca.

Proprietà dell'attività GetMetadata

Per informazioni sulle proprietà dell'attività GetMetadata, vedere Attività GetMetadata.

Proprietà dell'attività Delete

Per informazioni sulle proprietà dell'attività Delete, vedere Delete activity .For information about Delete activity properties, see Delete activity.

Modalità legacy

Modello di set di dati legacy

Esempio:

{
    "name": "SFTPDataset",
    "type": "Datasets",
    "properties": {
        "type": "FileShare",
        "linkedServiceName":{
            "referenceName": "<SFTP 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"
            }
        }
    }
}

Modello di origine legacy attività Copy

Esempio:

"activities":[
    {
        "name": "CopyFromSFTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<SFTP 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 di archivi dati supportati come origini e sink dal attività Copy, vedere archivi dati supportati.