Copia y transformación de los datos de Azure Data Lake Storage Gen2 mediante Azure Data Factory

SE APLICA A: Azure Data Factory Azure Synapse Analytics

Azure Data Lake Storage Gen2 (ADLS Gen2) es un conjunto de funcionalidades dedicadas al análisis de macrodatos integrado en Azure Blob Storage. Puede usarlo para interactuar con los datos usando el paradigma de sistema de archivos o el de almacenamiento de objetos.

En este artículo, se explica el uso de la actividad de copia en Azure Data Factory para copiar datos utilizando Azure Data Lake Storage Gen2 como origen o destino y el uso de Data Flow para transformar datos en Azure Data Lake Storage Gen2. Para información sobre Azure Data Factory, lea el artículo de introducción.

Sugerencia

Para ver un escenario de migración de un lago de datos o un almacenamiento de datos, obtenga más información en Uso de Azure Data Factory para migrar datos del lago de datos y el almacenamiento de datos a Azure.

Funcionalidades admitidas

Este conector de Azure Data Lake Storage Gen2 es compatible con las actividades siguientes:

En el caso de la actividad de copia, con este conector puede:

Introducción

Sugerencia

Para ver un tutorial sobre cómo usar el conector de Data Lake Storage Gen2, consulte Carga de datos en Azure Data Lake Storage Gen2.

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

En las secciones siguientes se proporciona información acerca de las propiedades que se usan para definir entidades de Data Factory específicas para Data Lake Storage Gen2.

Propiedades del servicio vinculado

El conector de Azure Data Lake Storage Gen2 admite los siguientes tipos de autenticación. Consulte las secciones correspondientes para más información:

Nota

  • Si desea utilizar el entorno de ejecución de integración de Azure público para conectarse a Data Lake Storage Gen2 con la opción Permitir que los servicios de Microsoft de confianza accedan a esta cuenta de almacenamiento habilitada en el firewall de Azure Storage, debe usar la autenticación de identidad administrada.
  • Cuando use PolyBase o la instrucción COPY para cargar datos en Azure Synapse Analytics, si la instancia de origen o almacenamiento provisional de Data Lake Storage Gen2 está configurada con un punto de conexión de Azure Virtual Network, deberá usar la autenticación de identidad administrada como requiere Synapse. Consulte la sección sobre autenticación de identidad administrada que incluye más requisitos previos de configuración.

Autenticación de clave de cuenta

Para usar la autenticación de clave de cuenta de almacenamiento, se admiten las siguientes propiedades:

Propiedad Descripción Obligatorio
type La propiedad type debe establecerse en: AzureBlobFS.
url Punto de conexión de Data Lake Storage Gen2 con el patrón de https://<accountname>.dfs.core.windows.net.
accountKey Clave de cuenta para Data Lake Storage Gen2. 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.
connectVia El entorno de ejecución de integración que se usará para conectarse al almacén de datos. Si el almacén de datos está en una red privada, se puede usar Azure Integration Runtime o un entorno de ejecución de integración autohospedado. Si no se especifica esta propiedad, se usa el valor predeterminado de Azure Integration Runtime. No

Nota

No se admite el punto de conexión del sistema de archivos ADLS secundario al usar la autenticación de clave de cuenta. Puede usar otros tipos de autenticación.

Ejemplo:

{
    "name": "AzureDataLakeStorageGen2LinkedService",
    "properties": {
        "type": "AzureBlobFS",
        "typeProperties": {
            "url": "https://<accountname>.dfs.core.windows.net", 
            "accountkey": { 
                "type": "SecureString", 
                "value": "<accountkey>" 
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Autenticación de entidad de servicio

Antes de usar la autenticación de entidad de servicio, siga estos pasos.

  1. Registre una entidad de aplicación en Azure Active Directory (Azure AD) como se indica en Registro de la aplicación con un inquilino de Azure AD. Anote los siguientes valores; los usará para definir el servicio vinculado:

    • Identificador de aplicación
    • Clave de la aplicación
    • Id. de inquilino
  2. Conceda a la entidad de servicio el permiso adecuado. Consulte ejemplos sobre el funcionamiento del permiso en Data Lake Storage Gen2 en Listas de control de acceso en archivos y directorios.

    • Como origen: en el Explorador de Storage, conceda al menos permiso de ejecución para TODAS las carpetas de nivel superior y el sistema de archivos, junto con el permiso de lectura para los archivos que se van a copiar. Como alternativa, en el control de acceso (IAM), conceda al menos el rol Lector de datos de Storage Blob.
    • Como receptor: en el Explorador de Storage, conceda al menos permiso de ejecución para TODAS las carpetas de nivel superior y el sistema de archivos, junto con el permiso de escritura para la carpeta del receptor. Como alternativa, en el control de acceso (IAM), conceda al menos el rol Colaborador de datos de Storage Blob.

Nota

Si usa la interfaz de usuario de Data Factory para la creación, y la entidad de servicio no está configurada con el rol "Lector o colaborador de datos de Storage Blob" en IAM, al realizar las pruebas de conexión o al explorar las carpetas o navegar por ellas, elija "Test connection to file path" (Probar conexión con la ruta de acceso del archivo) o "Browse from specified path" (Examinar desde la ruta de acceso especificada) y especifique una ruta de acceso con el permiso de lectura y ejecución para continuar.

Estas propiedades son compatibles con el servicio vinculado:

Propiedad Descripción Obligatorio
type La propiedad type debe establecerse en: AzureBlobFS.
url Punto de conexión de Data Lake Storage Gen2 con el patrón de https://<accountname>.dfs.core.windows.net.
servicePrincipalId Especifique el id. de cliente de la aplicación.
servicePrincipalCredentialType Tipo de credencial que se usará para la autenticación de entidades de servicio. Los valores válidos son ServicePrincipalKey y ServicePrincipalCert.
servicePrincipalCredential Credencial de entidad de servicio.
Al usar ServicePrincipalKey como tipo de credenciales, especifique la clave de la aplicación. Marque este campo como SecureString para almacenarlo de forma segura en Data Factory, o bien para hacer referencia a un secreto almacenado en Azure Key Vault.
Al usar ServicePrincipalCert como credencial, haga referencia a un certificado de Azure Key Vault.
servicePrincipalKey Especifique la clave de la aplicación. Marque este campo como SecureString para almacenarlo de forma segura en Data Factory, o bien para hacer referencia a un secreto almacenado en Azure Key Vault.
Esta propiedad se sigue admitiendo tal cual para servicePrincipalId + servicePrincipalKey. Cuando ADF agrega una nueva autenticación de certificado de entidad de servicio, el nuevo modelo de autenticación de entidades de servicio es servicePrincipalId + servicePrincipalCredentialType + servicePrincipalCredential.
No
tenant Especifique la información del inquilino (nombre de dominio o identificador de inquilino) en el que reside la aplicación. Para recuperarlo, mantenga el puntero del mouse en la esquina superior derecha de Azure Portal.
azureCloudType Para la autenticación de la entidad de servicio, especifique el tipo de entorno de nube de Azure en el que está registrada la aplicación de Azure Active Directory.
Los valores permitidos son AzurePublic, AzureChina, AzureUsGovernment y AzureGermany. De forma predeterminada, se usa el entorno de nube de la factoría de datos.
No
connectVia El entorno de ejecución de integración que se usará para conectarse al almacén de datos. Si el almacén de datos está en una red privada, se puede usar Azure Integration Runtime o un entorno de ejecución de integración autohospedado. Si no se especifica, se usa el valor predeterminado de Azure Integration Runtime. No

Ejemplo: uso de la autenticación de claves de entidad de servicio

También puede almacenar la clave de entidad de servicio en Azure Key Vault.

{
    "name": "AzureDataLakeStorageGen2LinkedService",
    "properties": {
        "type": "AzureBlobFS",
        "typeProperties": {
            "url": "https://<accountname>.dfs.core.windows.net", 
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Ejemplo: uso de la autenticación de certificados de entidad de servicio

{
    "name": "AzureDataLakeStorageGen2LinkedService",
    "properties": {
        "type": "AzureBlobFS",
        "typeProperties": {
            "url": "https://<accountname>.dfs.core.windows.net", 
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalCredential": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<AKV reference>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<certificate name in AKV>" 
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Identidades administradas para la autenticación de recursos de Azure

Una factoría de datos se puede asociar con una identidad administrada para recursos de Azure, que representa esa factoría de datos concreta. Puede usar directamente esta identidad administrada para la autenticación en Data Lake Storage Gen2, de forma similar a como usa su propia entidad de servicio. Permite que esta fábrica designada acceda a datos y los copie en Data Lake Storage Gen2 o desde este.

Para usar identidades administradas para la autenticación de recursos de Azure, siga estos pasos.

  1. Recupere la información de la identidad administrada de Data Factory mediante la copia del valor de Id. del objeto de identidad administrada que se ha generado junto con la factoría.

  2. Conceda el permiso adecuado de identidad administrada. Consulte ejemplos sobre el funcionamiento del permiso en Data Lake Storage Gen2 en Listas de control de acceso en archivos y directorios.

    • Como origen: en el Explorador de Storage, conceda al menos permiso de ejecución para TODAS las carpetas de nivel superior y el sistema de archivos, junto con el permiso de lectura para los archivos que se van a copiar. Como alternativa, en el control de acceso (IAM), conceda al menos el rol Lector de datos de Storage Blob.
    • Como receptor: en el Explorador de Storage, conceda al menos permiso de ejecución para TODAS las carpetas de nivel superior y el sistema de archivos, junto con el permiso de escritura para la carpeta del receptor. Como alternativa, en el control de acceso (IAM), conceda al menos el rol Colaborador de datos de Storage Blob.

Nota

Si usa la interfaz de usuario de Data Factory para la creación, y la identidad administrada no está configurada con el rol "Lector o colaborador de datos de Storage Blob" en IAM, al realizar las pruebas de conexión o al explorar las carpetas o navegar por ellas, elija "Test connection to file path" (Probar conexión con la ruta de acceso del archivo) o "Browse from specified path" (Examinar desde la ruta de acceso especificada) y especifique una ruta de acceso con el permiso de lectura y ejecución para continuar.

Importante

Si usa PolyBase o una instrucción COPY para cargar datos de Data Lake Storage Gen2 en Azure Synapse Analytics, cuando use la autenticación de identidad administrada para Data Lake Storage Gen2, asegúrese de seguir los pasos 1 a 3 de esta guía. En estos pasos se registrará el servidor con Azure AD y se asignará el rol Colaborador de datos de Storage Blob en el servidor. Data Factory controla el resto. Si configura Blob Storage con un punto de conexión de Azure Virtual Network, también debe tener la opción Permitir que los servicios de Microsoft de confianza accedan a esta cuenta de almacenamiento activada en el menú de configuración Firewalls y redes virtuales de la cuenta de Azure Storage, tal como requiere Synapse.

Estas propiedades son compatibles con el servicio vinculado:

Propiedad Descripción Obligatorio
type La propiedad type debe establecerse en: AzureBlobFS.
url Punto de conexión de Data Lake Storage Gen2 con el patrón de https://<accountname>.dfs.core.windows.net.
connectVia El entorno de ejecución de integración que se usará para conectarse al almacén de datos. Si el almacén de datos está en una red privada, se puede usar Azure Integration Runtime o un entorno de ejecución de integración autohospedado. Si no se especifica, se usa el valor predeterminado de Azure Integration Runtime. No

Ejemplo:

{
    "name": "AzureDataLakeStorageGen2LinkedService",
    "properties": {
        "type": "AzureBlobFS",
        "typeProperties": {
            "url": "https://<accountname>.dfs.core.windows.net", 
        },
        "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 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 Data Lake Store Gen2 en la configuración location del conjunto de datos basado en formato:

Propiedad Descripción Obligatorio
type La propiedad type de location del conjunto de datos debe establecerse en AzureBlobFSLocation.
fileSystem Nombre del sistema de archivos de Data Lake Storage Gen2. No
folderPath Ruta de acceso a una carpeta en el sistema de archivos especificado. Si quiere usar un carácter comodín para filtrar carpetas, omita este valor y especifíquelo en la configuración del origen de actividad. No
fileName Nombre de archivo en la propiedad fileSystem + folderPath indicada. Si quiere usar un carácter comodín para filtrar archivos, omita este valor y especifíquelo en la configuración del origen de actividad. No

Ejemplo:

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<Data Lake Storage Gen2 linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "AzureBlobFSLocation",
                "fileSystem": "filesystemname",
                "folderPath": "folder/subfolder"
            },
            "columnDelimiter": ",",
            "quoteChar": "\"",
            "firstRowAsHeader": true,
            "compressionCodec": "gzip"
        }
    }
}

Propiedades de la actividad de copia

Para ver una lista completa de las secciones y propiedades disponibles para definir actividades, consulte los artículos sobre configuraciones de actividades de copia y canalizaciones y actividades. En esta sección se proporciona una lista de las propiedades que el receptor y el origen de Data Lake Storage Gen2 admiten.

Azure Data Lake Storage Gen2 como tipo de origen

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

Tiene varias opciones para copiar datos de ADLS Gen2:

  • Copiar la ruta de acceso de archivo especificada en el conjunto de datos.
  • Filtrar con caracteres comodín en la ruta de acceso de la carpeta o el nombre de archivo (vea wildcardFolderPath y wildcardFileName).
  • Copiar los archivos definidos en un archivo de texto determinado como un conjunto de archivos (vea fileListPath).

Las propiedades siguientes se admiten para Data Lake Store Gen2 en la configuración storeSettings en el origen de copia basado en formato:

Propiedad Descripción Obligatorio
type La propiedad type de storeSettings se debe establecer en AzureBlobFSReadSettings.
Buscar los archivos que se van a copiar:
OPCIÓN 1: ruta de acceso estática
Copia de la ruta de acceso de carpeta/sistema de archivos especificada en el conjunto de datos. Si quiere copiar todos los archivos de una carpeta o un sistema de archivos, especifique también wildcardFileName como *.
OPCIÓN 2: carácter comodín
- wildcardFolderPath
Ruta de acceso de carpeta con caracteres comodín en el sistema de archivos especificado configurado en el conjunto de datos 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 file system + 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
modifiedDatetimeStart Filtro de archivos basado en el atributo: Última modificación.
Los archivos se seleccionarán si la hora de su última modificación está dentro del intervalo de tiempo entre modifiedDatetimeStart y modifiedDatetimeEnd. La hora se aplica a la zona horaria UTC en el formato "2018-12-01T05:00:00Z".
Las propiedades pueden ser NULL, lo que significa que no se aplica ningún filtro de atributo de archivo al conjunto de datos. Cuando modifiedDatetimeStart tiene el valor de fecha y hora, pero modifiedDatetimeEnd es NULL, significa que se seleccionarán los archivos cuyo último atributo modificado sea mayor o igual que el valor de fecha y hora. Cuando modifiedDatetimeEnd tiene el valor de fecha y hora, pero modifiedDatetimeStart es NULL, significa que se seleccionarán los archivos cuyo último atributo modificado sea inferior al valor de fecha y hora.
Esta propiedad no se aplica al configurar fileListPath.
No
modifiedDatetimeEnd Igual que el anterior. 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

Ejemplo:

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

Azure Data Lake Storage Gen2 como tipo de receptor

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 Data Lake Store Gen2 en la configuración storeSettings en el destino de copia basado en formato:

Propiedad Descripción Obligatorio
type La propiedad type de storeSettings se debe establecer en AzureBlobFSWriteSettings.
copyBehavior Define el comportamiento de copia cuando el origen son archivos de un almacén de datos basados en archivos.

Los valores permitidos son:
- PreserveHierarchy (valor predeterminado): conserva la jerarquía de archivos en la carpeta de destino. La ruta de acceso relativa del archivo de origen a la carpeta de origen es idéntica que la ruta de acceso relativa del archivo de destino a la carpeta de destino.
- FlattenHierarchy: todos los archivos de la carpeta de origen están en el primer nivel de la carpeta de destino. Los archivos de destino tienen nombres generados automáticamente.
- MergeFiles: combina todos los archivos de la carpeta de origen en un archivo. Si se especifica el nombre del archivo, el nombre de archivo combinado es el nombre especificado. De lo contrario, es un nombre de archivo generado automáticamente.
No
blockSizeInMB Especifique el tamaño de bloque en MB que se usa para escribir datos en ADLS Gen2. Más información sobre los blobs en bloques.
El valor permitido está entre 4 y 100 MB.
De forma predeterminada, ADF determina automáticamente el tamaño de bloque en función del tipo y los datos del almacén de origen. En el caso de una copia no binaria en ADLS Gen2, el tamaño de bloque predeterminado es de 100 MB, con el fin de ajustarse como máximo a 4,95 TB de datos. Este tamaño puede no ser óptimo cuando los datos no son grandes, en especial cuando se usa el entorno de ejecución de integración autohospedado con una red deficiente, lo que produce un problema de tiempo de espera de operación o rendimiento. Puede especificar explícitamente un tamaño de bloque, al tiempo que se garantiza que blockSizeInMB *50000 es lo suficientemente grande como para almacenar los datos; de lo contrario, se producirá un error en la ejecución de la actividad de copia.
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": "CopyToADLSGen2",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Parquet output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "ParquetSink",
                "storeSettings":{
                    "type": "AzureBlobFSWriteSettings",
                    "copyBehavior": "PreserveHierarchy"
                }
            }
        }
    }
]

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
fileSystem
    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:
Sistema de archivos: filesystem
Ruta de acceso a la carpeta: FolderA

En origen de la actividad de copia:
- Ruta de acceso de la lista de archivos: filesystem/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.

Algunos ejemplos de recursive y copyBehavior

En esta sección se describe el comportamiento resultante de la operación de copia para diferentes combinaciones de valores recursive y copyBehavior.

recursive copyBehavior Estructura de carpetas de origen Destino resultante
true preserveHierarchy Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
El destino Folder1 se crea con la misma estructura que el origen:

Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
true flattenHierarchy Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
La carpeta de destino Folder1 se crea con la estructura siguiente:

Folder1
    nombre de archivo generado automáticamente para File1
    nombre de archivo generado automáticamente para File2
    nombre de archivo generado automáticamente para File3
    nombre de archivo generado automáticamente para File4
    nombre de archivo generado automáticamente para File5
true mergeFiles Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
La carpeta de destino Folder1 se crea con la estructura siguiente:

Folder1
    El contenido de File1 + File2 + File3 + File4 + File5 se combina en un archivo con un nombre de archivo generado automáticamente.
false preserveHierarchy Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
La carpeta de destino Folder1 se crea con la estructura siguiente:

Folder1
    File1
    File2

No se selecciona la subcarpeta Subfolder1, con File3, File4 y File5.
false flattenHierarchy Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
La carpeta de destino Folder1 se crea con la estructura siguiente:

Folder1
    nombre de archivo generado automáticamente para File1
    nombre de archivo generado automáticamente para File2

No se selecciona la subcarpeta Subfolder1, con File3, File4 y File5.
false mergeFiles Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
La carpeta de destino Folder1 se crea con la estructura siguiente:

Folder1
    El contenido de File1 + File2 se combina en un archivo con un nombre de archivo generado automáticamente. nombre de archivo generado automáticamente para File1

No se selecciona la subcarpeta Subfolder1, con File3, File4 y File5.

Conservación de los metadatos durante la copia

Al copiar archivos de Amazon S3/Blob de Azure/Azure Data Lake Storage Gen2 a Azure Data Lake Storage Gen2/Blob de Azure, puede optar por conservar los metadatos de archivo junto con los datos. Más información en Conservación de metadatos.

Conservación de ACL desde Data Lake Storage Gen1/Gen2

Al copiar archivos de Azure Data Lake Storage Gen1/Gen2 a Gen2, puede elegir conservar las listas de control de acceso (ACL) de POSIX junto con los datos. Obtenga más información en Conservar las ACL de Data Lake Storage Gen1/Gen2 en Gen2 .

Sugerencia

Para copiar datos desde Azure Data Lake Storage Gen1 en Gen2 en general, consulte Copia de datos de Azure Data Lake Storage Gen1 en Gen2 con Azure Data Factory para ver un tutorial y los procedimientos recomendados.

Propiedades de Asignación de instancias de Data Flow

Al transformar datos en los flujos de datos de asignación, puede leer y escribir archivos de Azure Data Lake Storage Gen2 en los siguientes formatos:

La configuración específica de formato se encuentra en la documentación de ese formato. Para obtener más información, consulte los artículos sobre la transformación de origen en un flujo de datos de asignación y la transformación de receptor en un flujo de datos de asignación.

Transformación de origen

En la transformación de origen, puede leer de un contenedor, una carpeta o un archivo individual en Azure Data Lake Storage Gen2. La pestaña Opciones de origen permite administrar cómo se leen los archivos.

Opciones de origen

Ruta de acceso de comodín: El uso de un patrón de caracteres comodín indicará a ADF que recorra todos los archivos y carpetas que coincidan en una única transformación del origen. Se trata de una manera eficaz de procesar varios archivos en un único flujo. Agregue varios patrones de coincidencia de caracteres comodín con el signo + que aparece al desplazar el puntero sobre el patrón de caracteres comodín existente.

En el contenedor de origen, elija una serie de archivos que coincidan con un patrón. Solo se puede especificar un contenedor en el conjunto de datos. La ruta de acceso con carácter comodín, por tanto, también debe incluir la ruta de acceso de la carpeta de la carpeta raíz.

Ejemplos de caracteres comodín:

  • * Representa cualquier conjunto de caracteres.

  • ** Representa el anidamiento recursivo de directorios.

  • ? Reemplaza un carácter.

  • [] Coincide con uno de los caracteres entre corchetes.

  • /data/sales/**/*.csv Obtiene todos los archivos csv que se encuentra en /data/sales.

  • /data/sales/20??/**/ Obtiene todos los archivos del siglo XX.

  • /data/sales/*/*/*.csv Obtiene los archivos CSV en dos niveles bajo /data/sales.

  • /data/sales/2004/*/12/[XY]1?.csv Obtiene todos los archivos csv de diciembre de 2004 que comienzan con X o Y precedido por un número de dos dígitos.

Partition Root Path: (Ruta de acceso de la raíz de la partición) Si tiene carpetas con particiones en el origen de archivo con un formato key=value (por ejemplo, year=2019), puede asignar el nivel superior del árbol de carpetas de la partición a un nombre de columna del flujo de datos.

En primer lugar, establezca un comodín que incluya todas las rutas de acceso que sean carpetas con particiones y, además, los archivos de hoja que desee leer.

Configuración del archivo de origen de partición

Use el valor de Partition Root Path (Ruta de acceso de la raíz de la partición) para definir cuál es el nivel superior de la estructura de carpetas. Cuando vea el contenido de los datos mediante una vista previa, verá que ADF agregará las particiones resueltas que se encuentran en cada uno de los niveles de las carpetas.

Ruta de acceso raíz de la partición

Lista de archivos: Se trata de un conjunto de archivos. Cree un archivo de texto que incluya una lista de archivos de ruta de acceso relativa para procesar. Apunte a este archivo de texto.

Column to store file name: (Columna para almacenar el nombre de archivo) Almacene el nombre del archivo de origen en una columna de los datos. Escriba aquí el nombre de una nueva columna para almacenar la cadena de nombre de archivo.

After completion: (Tras finalizar) Elija no hacer nada con el archivo de origen después de que se ejecute el flujo de datos o bien elimine o mueva el archivo de origen. Las rutas de acceso para mover los archivos de origen son relativas.

Para mover archivos de origen a otra ubicación posterior al procesamiento, primero seleccione "Mover" para la operación de archivo. A continuación, establezca el directorio "from". Si no usa ningún carácter comodín para la ruta de acceso, la configuración de "from" será la misma carpeta que la carpeta de origen.

Si tiene una ruta de acceso de origen con un comodín, su sintaxis será como esta:

/data/sales/20??/**/*.csv

puede especificar "from" como

/data/sales

y "to" como

/backup/priorSales

En este caso, todos los subdirectorios cuyo origen se encuentra en /data/sales se mueven a /backup/priorSales.

Nota

Las operaciones de archivo solo se ejecutan cuando el flujo de datos se inicia desde una ejecución de canalización (depuración o ejecución de canalización) que usa la actividad de ejecución de Data Flow de una canalización. Las operaciones de archivo no se ejecutan en modo de depuración de Data Flow.

Filter by last modified: (Filtrar últimos modificados) Puede filtrar los archivos que desea procesar especificando un intervalo de fechas de la última vez que se modificaron. Todas las horas están en formato UTC.

Propiedades del receptor

En la transformación del receptor, puede escribir en un contenedor o una carpeta en Azure Data Lake Storage Gen2. La pestaña Configuración le permite administrar cómo se escriben los archivos.

Opciones del receptor

Clear the folder (Borrar la carpeta): determina si se borra o no la carpeta de destino antes de escribir los datos.

File name option (Opción de nombre de archivo): determina cómo se denominan los archivos de destino en la carpeta de destino. Las opciones de nombre de archivo son:

  • Valor predeterminado: permita que Spark nombre los archivos según los valores predeterminados de PART.
  • Patrón: escriba un patrón que enumere los archivos de salida por partición. Por ejemplo, loans[n].csv creará loans1.csv, loans2.csv, etc.
  • Por partición: escriba un nombre de archivo por partición.
  • Como datos de columna: establezca el archivo de salida en el valor de una columna. La ruta de acceso es relativa al contenedor del conjunto de datos, no a la carpeta de destino. Si tiene una ruta de acceso de carpeta en el conjunto de datos, se invalidará.
  • Salida en un solo archivo: combine los archivos de salida con particiones en un solo archivo con nombre. La ruta de acceso es relativa a la carpeta del conjunto de datos. Tenga en cuenta que la operación de combinación probablemente produzca un error en función del tamaño del nodo. Esta opción no se recomienda para conjuntos de datos de gran tamaño.

Quote all (Entrecomillar todo): determina si se deben entrecomillar todos los valores.

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: AzureBlobFSFile.
folderPath Ruta de acceso a la carpeta de Data Lake Storage Gen2. Si no se especifica, apunta a la raíz.

Se admiten filtros con caracteres comodín. Los caracteres comodín permitidos son: * (equivale a cero o a varios caracteres) y ? (equivale a cero o a un único carácter). Use ^ como escape si el nombre real de la carpeta contiene un carácter comodín o este carácter de escape.

Ejemplos: filesystem/folder/. Ver más ejemplos en Ejemplos de filtros de carpetas y archivos.
No
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.

Cuando fileName no se especifica para un conjunto de datos de salida y preserveHierarchy no se determina en el receptor de la actividad, la actividad de copia generará automáticamente el nombre de archivo con el siguiente patrón: "Data.[GUID de Id. de ejecución de actividad].[GUID si FlattenHierarchy].[formato si se ha configurado].[compresión si se ha configurado] ", por ejemplo, "Data.0a405f8a-93ff-4c6f-b3be-f69616f1df7a.txt.gz". Si realiza una copia desde el origen tabular mediante el nombre de una tabla en lugar de una consulta, el patrón del nombre es " [nombre de tabla].[formato].[compresión, si está configurada] ", por ejemplo, "MyTable.csv".
No
modifiedDatetimeStart Filtro de archivos basado en el atributo Last Modified. Los archivos se seleccionan si la hora de su última modificación está dentro del intervalo de tiempo entre modifiedDatetimeStart y modifiedDatetimeEnd. La hora se aplica a la zona horaria UTC en el formato "2018-12-01T05:00:00Z".

El rendimiento general del movimiento de datos se ve afectado si habilita esta configuración cuando quiere filtrar archivos con grandes cantidades de archivos.

Las propiedades pueden ser NULL, lo que significa que no se aplica ningún filtro de atributo de archivo al conjunto de datos. Cuando modifiedDatetimeStart tiene un valor de fecha y hora, pero modifiedDatetimeEnd es NULL, significa que se seleccionarán los archivos cuyo último atributo modificado sea mayor o igual que el valor de fecha y hora. Cuando modifiedDatetimeEnd tiene el valor de fecha y hora, pero modifiedDatetimeStart es NULL, significa que se seleccionarán los archivos cuyo último atributo modificado sea inferior al valor de fecha y hora.
No
modifiedDatetimeEnd Filtro de archivos basado en el atributo Last Modified. Los archivos se seleccionan si la hora de su última modificación está dentro del intervalo de tiempo entre modifiedDatetimeStart y modifiedDatetimeEnd. La hora se aplica a la zona horaria UTC en el formato "2018-12-01T05:00:00Z".

El rendimiento general del movimiento de datos se ve afectado si habilita esta configuración cuando quiere filtrar archivos con grandes cantidades de archivos.

Las propiedades pueden ser NULL, lo que significa que no se aplica ningún filtro de atributo de archivo al conjunto de datos. Cuando modifiedDatetimeStart tiene un valor de fecha y hora, pero modifiedDatetimeEnd es NULL, significa que se seleccionarán los archivos cuyo último atributo modificado sea mayor o igual que el valor de fecha y hora. Cuando modifiedDatetimeEnd tiene el valor de fecha y hora, pero modifiedDatetimeStart es NULL, significa que se seleccionarán los archivos cuyo último atributo modificado sea inferior al valor de fecha y hora.
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 o generar archivos con un formato concreto, se admiten los siguientes tipos de formato de archivo: TextFormat, JsonFormat, AvroFormat, OrcFormat y ParquetFormat. Establezca la propiedad type en format 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.
Los tipos admitidos son GZip, Deflate, BZip2 y ZipDeflate.
Niveles admitidos son Optimal y Fastest.
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 un elemento de carpeta y fileName con un nombre de archivo.
Para copiar un subconjunto de archivos en una carpeta, especifique folderPath con un elemento de carpeta y fileName con un filtro de comodín.

Ejemplo:

{
    "name": "ADLSGen2Dataset",
    "properties": {
        "type": "AzureBlobFSFile",
        "linkedServiceName": {
            "referenceName": "<Azure Data Lake Storage Gen2 linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "folderPath": "myfilesystem/myfolder",
            "fileName": "*",
            "modifiedDatetimeStart": "2018-12-01T05:00:00Z",
            "modifiedDatetimeEnd": "2018-12-01T06:00:00Z",
            "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: AzureBlobFSSource.
recursive Indica si los datos se leen de forma recursiva de las subcarpetas o solo de la carpeta especificada. 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.
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": "CopyFromADLSGen2",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<ADLS Gen2 input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "AzureBlobFSSource",
                "recursive": true
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Modelo de receptor de actividad de copia heredada

Propiedad Descripción Obligatorio
type La propiedad type del receptor de la actividad de copia debe establecerse en AzureBlobFSSink.
copyBehavior Define el comportamiento de copia cuando el origen son archivos de un almacén de datos basados en archivos.

Los valores permitidos son:
- PreserveHierarchy (valor predeterminado): conserva la jerarquía de archivos en la carpeta de destino. La ruta de acceso relativa del archivo de origen a la carpeta de origen es idéntica que la ruta de acceso relativa del archivo de destino a la carpeta de destino.
- FlattenHierarchy: todos los archivos de la carpeta de origen están en el primer nivel de la carpeta de destino. Los archivos de destino tienen nombres generados automáticamente.
- MergeFiles: combina todos los archivos de la carpeta de origen en un archivo. Si se especifica el nombre del archivo, el nombre de archivo combinado es el nombre especificado. De lo contrario, es un nombre de archivo generado automáticamente.
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": "CopyToADLSGen2",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<ADLS Gen2 output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "AzureBlobFSSink",
                "copyBehavior": "PreserveHierarchy"
            }
        }
    }
]

Pasos siguientes

Para ver la lista de almacenes de datos que la actividad de copia de Data Factory admite como orígenes y receptores consulte Almacenes de datos y formatos que se admiten.