Cómo copiar archivos SFTP a ADLS Gen2 en Azure Data Factory: paso a paso
Este tutorial muestra cómo copiar archivos desde un servidor SFTP a una cuenta ADLS Gen2 usando Azure Data Factory, manteniendo la estructura de carpetas, registrando metadatos y gestionando fallos comunes. Es útil para automatizar la ingestión segura de archivos externos para su posterior procesamiento.
Requisitos previos
- Cuenta Azure con permisos para crear recursos.
- Azure Data Factory (v2) creado.
- Acceso a un servidor SFTP (host, puerto, usuario, contraseña o clave SSH).
- Cuenta ADLS Gen2 con un contenedor y permisos (Storage Blob Data Contributor).
- Azure Key Vault opcional para almacenar credenciales (recomendado).
Paso 1: Crear Linked Service para SFTP
Un Linked Service describe cómo conectarse al SFTP. Si usa contraseña o clave SSH, prefiera almacenarlo en Azure Key Vault. En el portal del ADF, vaya a Manage > Linked services > New y elija SFTP. Configure el host, el puerto, la autenticación y pruebe la conexión.
{
"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\')"
}
}
Paso 2: Crear Linked Service para ADLS Gen2
Crear el Linked Service para la cuenta de almacenamiento ADLS Gen2. Use la Managed Identity del ADF para evitar credenciales en las configuraciones. En el portal, elija Azure Data Lake Storage Gen2 y seleccione Authorization via Managed Identity.
{
"type": "AzureDataLakeStorageGen2",
"typeProperties": {
"url": "https://meuaccount.dfs.core.windows.net"
},
"connectVia": null
}
Paso 3: Crear DataSet SFTP y DataSet ADLS Gen2
Defina DataSets que apunten a la ruta de origen en el SFTP y a la carpeta de destino en ADLS Gen2. Configure wildcardPaths si desea copiar múltiples archivos o todo el árbol.
{
"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}}"}
}
}
Paso 4: Crear Pipeline con actividad Copy
Creé un pipeline con la actividad Copy. Para mantener la estructura de carpetas use la opción Preserve Hierarchy en el Copy behaviour. Configure fault tolerance y retry para manejar fallos transitorios.
{
"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}
}
]
}
}
Paso 5: Registrar metadatos con actividad Lookup/Stored Procedure
Tras la copia, registre metadatos (origen, destino, timestamp, tamaño) en un archivo JSON o en una tabla de metadatos. Puede usar una actividad Lookup para obtener detalles del archivo y luego una Stored Procedure para escribir en una base de datos o un Copy para un archivo de log.
{
"name": "WriteMetadata",
"type": "Copy",
"inputs": [{"referenceName":"MetadataSource","type":"DatasetReference"}],
"outputs": [{"referenceName":"ADLSMetadata","type":"DatasetReference"}]
}
Paso 6: Gestionar errores comunes y limpiar archivos incompletos
Errores comunes: fallo de autenticación SFTP, timeouts, archivos bloqueados. Use política de retry, validación del tamaño del archivo y una columna de estado en los metadatos. Para archivos parcialmente transferidos, copie a una carpeta temporal y solo mueva a la carpeta final después de la validación.
// Ejemplo de lógica: mover solo after_success
1. Copy a /raw/sftp/_staging/{{...}}
2. Verificar tamaño/MD5
3. Si OK, mover a /raw/sftp/{{year}}/{{month}}/
4. Si NOK, mover a /raw/sftp/_quarantine/
Verificar el resultado
Confirme que los archivos llegaron: abra el contenedor ADLS Gen2 y verifique la estructura de carpetas preservada y archivos con tamaños correctos. Revise los logs del pipeline en Monitor do Azure Data Factory para entradas de éxito y fallos. Confirme también que la tabla/archivo de metadatos contiene registros para cada archivo procesado.
Conclusión
Ahora tiene un pipeline ADF que copia archivos desde un servidor SFTP a ADLS Gen2, preservando la jerarquía, gestionando fallos y guardando metadatos. Próximos pasos: automatizar con trigger, cifrar en tránsito/y en reposo e integrar con un proceso ETL/Mapping Data Flows. Consejo: pruebe Managed Identity + Key Vault para la seguridad de las credenciales — ¿ya ha probado esa combinación?