Como copiar ficheiros SFTP para ADLS Gen2 em Azure Data Factory: passo a passo
Este tutorial mostra como copiar ficheiros de um servidor SFTP para uma conta ADLS Gen2 usando o Azure Data Factory, mantendo a estrutura de pastas, registando metadados e tratando falhas comuns. É útil para automatizar a ingestão segura de ficheiros externos para processamento posterior.
Pré-requisitos
- Conta Azure com permissões para criar recursos.
- Azure Data Factory (v2) criado.
- Acesso a um servidor SFTP (host, porta, utilizador, palavra-passe ou chave SSH).
- Conta ADLS Gen2 com um container e permissões (Storage Blob Data Contributor).
- Azure Key Vault opcional para guardar credenciais (recomendado).
Passo 1: Criar Linked Service para SFTP
Um Linked Service descreve como ligar ao SFTP. Se usar palavra-passe ou chave SSH, prefira armazenar no Azure Key Vault. No portal do ADF, vá a Manage > Linked services > New e escolha SFTP. Configure o host, a porta, a autenticação e teste a ligação.
{
"type": "Sftp",
"typeProperties": {
"host": "sftp.exemplo.com",
"port": 22,
"authenticationType": "Basic", /* ou "SSHPublicKey" */
"userName": "meu_utilizador",
"password": "@Microsoft.KeyVault(\'https://meu-kv.vault.azure.net/secrets/sftp-pwd\')"
}
}
Passo 2: Criar Linked Service para ADLS Gen2
Criar o Linked Service para a conta de armazenamento ADLS Gen2. Use a Managed Identity do ADF para evitar credenciais nas configurações. No portal, escolha Azure Data Lake Storage Gen2 e seleccione Authorization via Managed Identity.
{
"type": "AzureDataLakeStorageGen2",
"typeProperties": {
"url": "https://meuaccount.dfs.core.windows.net"
},
"connectVia": null
}
Passo 3: Criar DataSet SFTP e DataSet ADLS Gen2
Defina DataSets que apontem para o caminho de origem no SFTP e para a pasta de destino em ADLS Gen2. Configure wildcardPaths se quiser copiar múltiplos ficheiros ou toda a árvore.
{
"name": "SftpFiles",
"properties": {
"type": "FileShare",
"linkedServiceName": {"referenceName":"LS_SFTP","type":"LinkedServiceReference"},
"typeProperties": {"folderPath":"/incoming/{{year}}/{{month}}"}
}
}
{
"name": "ADLSFiles",
"properties": {
"type": "AzureBlobFS",
"linkedServiceName": {"referenceName":"LS_ADLS","type":"LinkedServiceReference"},
"typeProperties": {"folderPath":"/raw/sftp/{{year}}/{{month}}"}
}
}
Passo 4: Criar Pipeline com actividade Copy
Crie um pipeline com a actividade Copy. Para manter a estrutura de pastas use a opção Preserve Hierarchy no Copy behaviour. Configure fault tolerance e retry para lidar com falhas transitórias.
{
"name": "CopyFromSftpToADLS",
"properties": {
"activities": [
{
"name": "CopySftpToADLS",
"type": "Copy",
"typeProperties": {
"source": {"type":"BinarySource"},
"sink": {"type":"BinarySink"},
"enableStaging": false
},
"inputs": [{"referenceName":"SftpFiles","type":"DatasetReference"}],
"outputs": [{"referenceName":"ADLSFiles","type":"DatasetReference"}],
"policy": {"retry":3,"timeout":"00:30:00","retryIntervalInSeconds":60}
}
]
}
}
Passo 5: Registar metadados com actividade Lookup/Stored Procedure
Após a cópia, registe metadados (origem, destino, timestamp, tamanho) num ficheiro JSON ou numa tabela de metadados. Pode usar uma actividade Lookup para obter detalhes do ficheiro e depois uma Stored Procedure para gravar numa base de dados ou um Copy para um ficheiro de log.
{
"name": "WriteMetadata",
"type": "Copy",
"inputs": [{"referenceName":"MetadataSource","type":"DatasetReference"}],
"outputs": [{"referenceName":"ADLSMetadata","type":"DatasetReference"}]
}
Passo 6: Tratar erros comuns e limpar ficheiros incompletos
Erros comuns: falha de autenticação SFTP, timeouts, ficheiros bloqueados. Use politica de retry, validação do tamanho do ficheiro e uma coluna de estado nos metadados. Para ficheiros parcialmente transferidos, copie para uma pasta temporária e só mova para a pasta final após validação.
// Exemplo de lógica: mover apenas after_success
1. Copy para /raw/sftp/_staging/{{...}}
2. Verificar tamanho/MD5
3. Se OK, mover para /raw/sftp/{{year}}/{{month}}/
4. Se NOK, mover para /raw/sftp/_quarantine/
Verificar o resultado
Confirme que os ficheiros chegaram: abra o container ADLS Gen2 e verifique a estrutura de pastas preservada e ficheiros com tamanhos correctos. Verifique os logs do pipeline no Monitor do Azure Data Factory para entradas de sucesso e falhas. Confirme também que a tabela/ficheiro de metadados contém registos para cada ficheiro processado.
Conclusão
Agora tem um pipeline ADF que copia ficheiros de um servidor SFTP para ADLS Gen2, preservando a hierarquia, tratando falhas e guardando metadados. Próximos passos: automatizar com trigger, encriptar em trânsito/e em repouso e integrar com um processo ETL/Mapping Data Flows. Dica: experimente Managed Identity + Key Vault para a segurança das credenciais — já testou essa combinação?