Copia de datos desde un servidor FTP mediante Azure Data Factory

SE APLICA A: Azure Data Factory Azure Synapse Analytics

En este artículo se describe cómo copiar datos desde el servidor FTP. Para información sobre Azure Data Factory, lea el artículo de introducción.

Funcionalidades admitidas

Este conector FTP es compatible con las actividades siguientes:

En concreto, este conector FTP admite las siguientes funcionalidades:

El conector de FTP es compatible con el servidor FTP que se ejecuta en modo pasivo. No se admite el modo activo.

Requisitos previos

Si el almacén de datos se encuentra en una red local, una red virtual de Azure o una nube privada virtual de Amazon, debe configurar un entorno de ejecución de integración autohospedado para conectarse a él.

Si el almacén de datos es un servicio de datos en la nube administrado, puede usar Azure Integration Runtime. Si el acceso está restringido a las direcciones IP que están aprobadas en las reglas de firewall, puede agregar direcciones IP de Azure Integration Runtime a la lista de permitidos.

También puede usar la característica del entorno de ejecución de integración de red virtual administrada de Azure Data Factory para acceder a la red local sin instalar ni configurar un entorno de ejecución de integración autohospedado.

Consulte Estrategias de acceso a datos para más información sobre los mecanismos de seguridad de red y las opciones que admite Data Factory.

Introducción

Para realizar la actividad de copia con una canalización, puede usar una de los siguientes herramientas o SDK:

Creación de un servicio vinculado en un servidor FTP mediante la interfaz de usuario

Siga estos pasos para crear un servicio vinculado en un servidor FTP en la interfaz de usuario de Azure Portal.

  1. Vaya a la pestaña Administrar del área de trabajo de Azure Data Factory o Synapse y seleccione Servicios vinculados; luego haga clic en Nuevo:

  2. Busque FTP y seleccione el conector de FTP.

    Captura de pantalla del conector de FTP.

  3. Configure los detalles del servicio, pruebe la conexión y cree el nuevo servicio vinculado.

    Captura de pantalla de la configuración del servicio vinculado de un servidor FTP.

Detalles de configuración del conector

En las secciones siguientes se proporcionan detalles sobre las propiedades que se usan para definir entidades específicas de FTP.

Propiedades del servicio vinculado

Las siguientes propiedades son compatibles con el servicio vinculado de FTP:

Propiedad Descripción Obligatorio
type La propiedad type debe establecerse en: FtpServer.
host Especifique el nombre o dirección IP del servidor FTP.
port Especifique el puerto en el que se está realizando la escucha del servidor FTP.
Los valores permitidos son: enteros; el valor predeterminado es 21.
No
enableSsl Especificar si desea usar FTP a través del canal SSL/TLS.
Los valores permitidos son: True (valor predeterminado) y False.
No
enableServerCertificateValidation Especifique si desea habilitar la validación de certificados de servidor TLS/SSL al usar FTP sobre el canal SSL/TLS.
Los valores permitidos son: True (valor predeterminado) y False.
No
authenticationType Especifique el tipo de autenticación.
Los valores permitidos son: Basic, Anonymous
userName Especifique el usuario que tiene acceso al servidor FTP. No
password Especifique la contraseña del usuario (userName). Marque este campo como SecureString para almacenarlo de forma segura en Data Factory o para hacer referencia a un secreto almacenado en Azure Key Vault. No
connectVia El entorno Integration Runtime que se usará para conectarse al almacén de datos. Obtenga más información en la sección Requisitos previos. Si no se especifica, se usará Azure Integration Runtime. No

Nota

El conector FTP permite el acceso al servidor FTP sin cifrado o con cifrado de SSL/TLS explícito, pero no permite el cifrado SSL/TLS implícito.

Ejemplo 1: Uso de autenticación anónima

{
    "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"
        }
    }
}

Ejemplo 2: Uso de la autenticación básica

{
    "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"
        }
    }
}

Propiedades del conjunto de datos

Si desea ver una lista completa de las secciones y propiedades disponibles para definir conjuntos de datos, consulte el artículo sobre conjuntos de datos.

Azure Data Factory admite los siguientes formatos de archivo. Consulte los artículos para conocer la configuración basada en el formato.

Las propiedades siguientes se admiten para FTP en la configuración location del conjunto de datos basado en formato:

Propiedad Descripción Obligatorio
type La propiedad type de location en el conjunto de datos se debe establecer en FtpServerLocation.
folderPath Ruta de acceso a la carpeta. Si quiere usar el carácter comodín para filtrar la carpeta, omita este valor y especifique la configuración del origen de actividad. No
fileName Nombre de archivo en la propiedad folderPath indicada. Si quiere usar el carácter comodín para filtrar los archivos, omita este valor y especifique la configuración del origen de actividad. No

Ejemplo:

{
    "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"
        }
    }
}

Propiedades de la actividad de copia

Si desea ver una lista completa de las secciones y propiedades disponibles para definir actividades, consulte el artículo sobre canalizaciones. En esta sección se proporciona una lista de las propiedades que admite el origen FTP.

FTP como origen

Azure Data Factory admite los siguientes formatos de archivo. Consulte los artículos para conocer la configuración basada en el formato.

Las propiedades siguientes se admiten para FTP en la configuración storeSettings del origen de copia basado en formato:

Propiedad Descripción Obligatorio
type La propiedad type de storeSettings se debe establecer en FtpReadSettings.
Buscar los archivos que se van a copiar:
OPCIÓN 1: ruta de acceso estática
Copia de la ruta de acceso de archivo o carpeta especificada en el conjunto de datos. Si quiere copiar todos los archivos de una carpeta, especifique también wildcardFileName como *.
OPCIÓN 2: carácter comodín
- wildcardFolderPath
Ruta de acceso de carpeta con caracteres comodín para filtrar las carpetas de origen.
Los caracteres comodín permitidos son: * (coincide con cero o más caracteres) y ? (coincide con cero o carácter individual); use ^ para el escape si el nombre real de la carpeta tiene un carácter comodín o este carácter de escape dentro.
Ver más ejemplos en Ejemplos de filtros de carpetas y archivos.
No
OPCIÓN 2: carácter comodín
- wildcardFileName
Nombre de archivo con caracteres comodín en la propiedad folderPath o wildcardFolderPath indicada para filtrar los archivos de origen.
Los caracteres comodín permitidos son: * (coincide con cero o más caracteres) y ? (coincide con cero o carácter individual); use ^ para el escape si el nombre real del archivo tiene un carácter comodín o este carácter de escape dentro. Ver más ejemplos en Ejemplos de filtros de carpetas y archivos.
OPCIÓN 3: una lista de archivos
- fileListPath
Indica que se copie un conjunto de archivos determinado. Apunte a un archivo de texto que incluya una lista de los archivos que quiere copiar, con un archivo por línea, que sea la ruta de acceso relativa a la ruta de acceso configurada en el conjunto de datos.
Al utilizar esta opción, no especifique el nombre de archivo en el conjunto de datos. Ver más ejemplos en Ejemplos de lista de archivos.
No
Configuración adicional:
recursive Indica si los datos se leen de forma recursiva de las subcarpetas o solo de la carpeta especificada. Tenga en cuenta que cuando recursive se establece en true y el receptor es un almacén basado en archivos, no se crea una carpeta o una subcarpeta vacía en el receptor.
Los valores permitidos son: True (valor predeterminado) y False.
Esta propiedad no se aplica al configurar fileListPath.
No
deleteFilesAfterCompletion Indica si los archivos binarios se eliminarán del almacén de origen después de moverse correctamente al almacén de destino. Cada archivo se elimina individualmente, de modo que cuando se produzca un error en la actividad de copia, algunos archivos ya se habrán copiado al destino y se habrán eliminado del origen, mientras que otros seguirán aún en el almacén de origen.
Esta propiedad solo es válida en el escenario de copia de archivos binarios. El valor predeterminado es false.
No
useBinaryTransfer Especifique si se usar el modo de transferencia binario. Los valores son True para el modo binario (valor predeterminado) y False para ASCII. No
enablePartitionDiscovery En el caso de archivos con particiones, especifique si quiere analizar las particiones de la ruta de acceso del archivo y agregarlas como columnas de origen adicionales.
Los valores permitidos son false (valor predeterminado) y true.
No
partitionRootPath Cuando esté habilitada la detección de particiones, especifique la ruta de acceso raíz absoluta para poder leer las carpetas con particiones como columnas de datos.

Si no se especifica, de forma predeterminada,
- Cuando se usa la ruta de acceso de archivo en un conjunto de datos o una lista de archivos del origen, la ruta de acceso raíz de la partición es la ruta de acceso configurada en el conjunto de datos.
- Cuando se usa el filtro de carpeta con caracteres comodín, la ruta de acceso raíz de la partición es la subruta antes del primer carácter comodín.

Por ejemplo, supongamos que configura la ruta de acceso en el conjunto de datos como "root/folder/year=2020/month=08/day=27":
- Si especifica la ruta de acceso raíz de la partición como "root/folder/year=2020", la actividad de copia generará dos columnas más, month y day, con el valor "08" y "27", respectivamente, además de las columnas de los archivos.
- Si no se especifica la ruta de acceso raíz de la partición, no se generará ninguna columna adicional.
No
maxConcurrentConnections Número máximo de conexiones simultáneas establecidas en el almacén de datos durante la ejecución de la actividad. Especifique un valor solo cuando quiera limitar las conexiones simultáneas. No

Cuando se copian datos desde FTP, actualmente ADF primero intenta obtener la longitud del archivo y, después, lo divide en varias partes y las lee en paralelo. Si el servidor FTP no admite la obtención de la longitud del archivo o la búsqueda de lectura desde un desplazamiento concreto, es posible que se produzca un error.

Ejemplo:

"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"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Ejemplos de filtros de carpetas y archivos

Esta sección describe el comportamiento resultante de la ruta de acceso de la carpeta y el nombre de archivo con los filtros de carácter comodín.

folderPath fileName recursive Resultado de estructura de carpeta de origen y filtro (se recuperan los archivos en negrita)
Folder* (vacío, usar el valor predeterminado) false FolderA
    File1.csv
    File2.json
    Subfolder1
        File3.csv
        File4.json
        File5.csv
AnotherFolderB
    File6.csv
Folder* (vacío, usar el valor predeterminado) true FolderA
    File1.csv
    File2.json
    Subfolder1
        File3.csv
        File4.json
        File5.csv
AnotherFolderB
    File6.csv
Folder* *.csv false FolderA
    File1.csv
    File2.json
    Subfolder1
        File3.csv
        File4.json
        File5.csv
AnotherFolderB
    File6.csv
Folder* *.csv true FolderA
    File1.csv
    File2.json
    Subfolder1
        File3.csv
        File4.json
        File5.csv
AnotherFolderB
    File6.csv

Ejemplos de lista de archivos

En esta sección se describe el comportamiento resultante de usar la ruta de acceso de la lista de archivos en el origen de la actividad de copia.

Suponga que tiene la siguiente estructura de carpetas de origen y quiere copiar los archivos en negrita:

Estructura de origen de ejemplo Contenido de FileListToCopy.txt Configuración de ADF
root
    FolderA
        File1.csv
        File2.json
        Subfolder1
            File3.csv
            File4.json
            File5.csv
    Metadatos
        FileListToCopy.txt
File1.csv
Subfolder1/File3.csv
Subfolder1/File5.csv
En el conjunto de datos:
- Ruta de acceso a la carpeta: root/FolderA

En origen de la actividad de copia:
- Ruta de acceso de la lista de archivos: root/Metadata/FileListToCopy.txt

La ruta de acceso de la lista de archivos apunta a un archivo de texto en el mismo almacén de datos que incluye una lista de archivos que se quiere copiar, un archivo por línea con la ruta de acceso relativa a la ruta de acceso configurada en el conjunto de datos.

Propiedades de la actividad de búsqueda

Para obtener información detallada sobre las propiedades, consulte Actividad de búsqueda.

Propiedades de la actividad GetMetadata

Para información detallada sobre las propiedades, consulte Actividad de obtención de metadatos.

Propiedades de la actividad de eliminación

Para información detallada sobre las propiedades, consulte Actividad de eliminación.

Modelos heredados

Nota

Estos modelos siguen siendo compatibles con versiones anteriores. Se recomienda usar el nuevo modelo mencionado en la sección anterior de ahora en adelante; además, la interfaz de usuario de creación de ADF ha pasado a generar el nuevo modelo.

Modelo de conjunto de datos heredado

Propiedad Descripción Obligatorio
type La propiedad type del conjunto de datos debe establecerse en: FileShare
folderPath Ruta de acceso a la carpeta. Se admite el filtro de comodín, los caracteres comodín permitidos son: * (coincide con cero o más caracteres) y ? (coincide con cero o carácter individual); use ^ para el escape si el nombre real de la carpeta tiene un carácter comodín o este carácter de escape dentro.

Ejemplos: rootfolder/subfolder/ver más en Ejemplos de filtros de carpetas y archivos.
fileName Filtro de nombre o de comodín para los archivos de la ruta "folderPath" especificada. Si no especifica ningún valor para esta propiedad, el conjunto de datos apunta a todos los archivos de la carpeta.

Para filtrar, los caracteres comodín permitidos son: * (equivale a cero o a varios caracteres) y ? (equivale a cero o a un único carácter).
- Ejemplo 1: "fileName": "*.csv"
- Ejemplo 2: "fileName": "???20180427.txt"
Use ^ como escape si el nombre de archivo real contiene un comodín o este carácter de escape.
No
format Si desea copiar los archivos tal cual entre los almacenes basados en archivos (copia binaria), omita la sección de formato en las definiciones de los conjuntos de datos de entrada y salida.

Si quiere analizar archivos con un formato concreto, se admiten los siguientes tipos de formato de archivo: TextFormat, JsonFormat, AvroFormat, OrcFormat, ParquetFormat. Establezca la propiedad type de formato en uno de los siguientes valores. Para más información, consulte las secciones Formato de texto, Formato Json, Formato Avro, Formato Orc y Formato Parquet.
No (solo para el escenario de copia binaria)
compression Especifique el tipo y el nivel de compresión de los datos. Para más información, consulte el artículo sobre códecs de compresión y formatos de archivo compatibles.
Estos son los tipos que se admiten: GZip, Deflate, BZip2 y ZipDeflate.
Estos son los niveles que se admiten: Optimal y Fastest.
No
useBinaryTransfer Especifique si se usar el modo de transferencia binario. Los valores son True para el modo binario (valor predeterminado) y False para ASCII. No

Sugerencia

Para copiar todos los archivos en una carpeta, especifique solo folderPath.
Para copiar un único archivo con un nombre determinado, especifique folderPath con el elemento de carpeta y fileName con el nombre de archivo.
Para copiar un subconjunto de archivos en una carpeta, especifique folderPath con el elemento de carpeta y fileName con el filtro de comodín.

Nota

Si estaba usando la propiedad "fileFilter" para el filtro de archivos, esta todavía se admite como está, aunque se le sugiere que use la nueva funcionalidad de filtro agregada a "fileName" de ahora en adelante.

Ejemplo:

{
    "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"
            }
        }
    }
}

Modelo de origen de actividad de copia heredada

Propiedad Descripción Obligatorio
type La propiedad type del origen de la actividad de copia debe establecerse en: FileSystemSource
recursive Indica si los datos se leen de forma recursiva de las subcarpetas o solo de la carpeta especificada. Tenga en cuenta que cuando recursive se establezca en true y el receptor sea un almacén basado en archivos, la carpeta o subcarpeta vacías no se copiarán ni crearán en el receptor.
Los valores permitidos son: True (valor predeterminado) y False
No
maxConcurrentConnections Número máximo de conexiones simultáneas establecidas en el almacén de datos durante la ejecución de la actividad. Especifique un valor solo cuando quiera limitar las conexiones simultáneas. No

Ejemplo:

"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>"
            }
        }
    }
]

Pasos siguientes

Consulte los almacenes de datos compatibles para ver la lista de almacenes de datos que la actividad de copia de Azure Data Factory admite como orígenes y receptores.