Copiar dados para ou do Azure Data Lake Storage Gen1 usando o Azure Data Factory ou o Azure Synapse Analytics

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma avaliação gratuita!

Este artigo descreve como copiar dados de e para o Azure Data Lake Storage Gen1. Para saber mais, leia o artigo introdutório do Azure Data Factory ou do Azure Synapse Analytics.

Funcionalidades com suporte

Este conector do Azure Data Lake Storage Gen1 é compatível com as seguintes funcionalidades:

Funcionalidades com suporte IR
Atividade de cópia (origem/coletor) 6/6
Fluxo de dados de mapeamento (origem/coletor) 2
Atividade de pesquisa 6/6
Atividade GetMetadata 6/6
Excluir atividade 6/6

① Runtime de integração do Azure ② Runtime de integração auto-hospedada

Especificamente, com esse conector, você pode:

Importante

Se você copiar dados usando o runtime de integração auto-hospedada, configure o firewall corporativo para permitir o tráfego de saída para <ADLS account name>.azuredatalakestore.net e login.microsoftonline.com/<tenant>/oauth2/token na porta 443. O último é o Serviço de Token de Segurança do Azure com que o runtime de integração precisa se comunicar para obter o token de acesso.

Introdução

Dica

Para obter um passo a passo de como usar o conector do Azure Data Lake Storage, veja Carregar dados no Azure Data Lake Storage.

Para executar a atividade de Cópia com um pipeline, será possível usar as ferramentas ou os SDKs abaixo:

Criar um serviço vinculado ao Azure Data Lake Storage Gen1 usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado ao Azure Data Lake Storage Gen1 na interface do usuário do portal do Azure.

  1. Navegue até a guia Gerenciar no workspace do Azure Data Factory ou do Synapse e selecione Serviços Vinculados. Depois, selecione Novo:

  2. Procure Azure Data Lake Storage Gen1 e selecione o conector do Azure Data Lake Storage Gen1.

    Screenshot of the Azure Data Lake Storage Gen1 connector.

  3. Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

    Screenshot of linked service configuration for Azure Data Lake Storage Gen1.

Detalhes da configuração do conector

As seções a seguir fornecem informações sobre propriedades que são usadas para definir entidades específicas do Azure Data Lake Storage Gen1.

Propriedades do serviço vinculado

As propriedades a seguir têm suporte no serviço vinculado do Azure Data Lake Store:

Propriedade Descrição Obrigatório
type A propriedade type deve ser definida como: AzureDataLakeStore. Sim
dataLakeStoreUri Informações sobre a conta do Azure Data Lake Store. Essas informações usam um dos seguintes formatos: https://[accountname].azuredatalakestore.net/webhdfs/v1 ou adl://[accountname].azuredatalakestore.net/. Sim
subscriptionId A ID de assinatura do Azure à qual a conta do Data Lake Store pertence. Obrigatório para coletor
resourceGroupName O nome do grupo de recursos do Azure ao qual a conta do Data Lake Store pertence. Obrigatório para coletor
connectVia O runtime de integração a ser usado para se conectar ao armazenamento de dados. Você poderá usar o runtime de integração do Azure ou um runtime de integração auto-hospedada se o seu armazenamento de dados estiver localizado em uma rede privada. Se essa propriedade não for especificada, o runtime de integração do Azure padrão será usado. Não

Usar a autenticação de entidade de serviço

Para usar a autenticação de entidade de serviço, siga estas etapas.

  1. Registre uma entidade de aplicativo no Microsoft Entra ID e conceda a ela o acesso ao Data Lake Storage. Para encontrar as etapas detalhadas, consulte Autenticação de serviço a serviço. Anote os seguintes valores, que são usados para definir o serviço vinculado:

    • ID do aplicativo
    • Chave do aplicativo
    • ID do locatário
  2. Conceda a permissão adequada da entidade de serviço. Veja exemplos de como a permissão funciona no Data Lake Storage Gen1 em Controle de acesso no Azure Data Lake Storage Gen1.

    • Como origem: em Data Explorer>Acesso, conceda pelo menos a permissão Execução para TODAS as pastas acima, incluindo a raiz, junto com a permissão Leitura para os arquivos que serão copiados. Você pode optar por adicionar a Esta pasta e todos os filhos para recursivo e adicionar como uma permissão de acesso e uma entrada de permissão padrão. Não há requisito de controle de acesso no nível da conta (IAM).
    • Como coletor: em Data Explorer>Acesso, conceda pelo menos a permissão Execução para TODAS as pastas acima, incluindo a raiz, junto com a permissão Gravação para a pasta coletora. Você pode optar por adicionar a Esta pasta e todos os filhos para recursivo e adicionar como uma permissão de acesso e uma entrada de permissão padrão.

Há suporte para as seguintes propriedades:

Propriedade Descrição Obrigatório
servicePrincipalId Especifique a ID do cliente do aplicativo. Sim
servicePrincipalKey Especifique a chave do aplicativo. Marque este campo como uma SecureString para armazená-la com segurança, ou faça referência a um segredo armazenado no Azure Key Vault. Sim
locatário Especifique as informações de locatário, como nome de domínio ou ID do locatário, em que o aplicativo reside. É possível recuperá-las focalizando o mouse no canto superior direito do Portal do Azure. Sim
azureCloudType Para autenticação da entidade de serviço, especifique o tipo de ambiente em nuvem do Azure em que seu aplicativo do Microsoft Entra está registrado.
Os valores permitidos são AzurePublic, AzureChina, AzureUsGovernment e AzureGermany. Por padrão, é usado o ambiente de nuvem do serviço.
Não

Exemplo:

{
    "name": "AzureDataLakeStoreLinkedService",
    "properties": {
        "type": "AzureDataLakeStore",
        "typeProperties": {
            "dataLakeStoreUri": "https://<accountname>.azuredatalakestore.net/webhdfs/v1",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "subscriptionId": "<subscription of ADLS>",
            "resourceGroupName": "<resource group of ADLS>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Usar a autenticação de identidade gerenciada atribuída pelo sistema

Um workspace do Data Factory ou do Synapse pode ser associado a uma identidade gerenciada atribuída pelo sistema, que representa o serviço para autenticação. Você pode usar essa identidade gerenciada atribuída pelo sistema diretamente para a autenticação do Data Lake Storage da mesma maneira que no uso de sua própria entidade de serviço. Ele permite que este recurso designado acesse e copie dados de ou para o seu Data Lake Store.

Para usar a autenticação de identidade gerenciada atribuída pelo sistema, siga estas etapas.

  1. Recuperar a identidade gerenciada atribuída pelo sistema copiando o valor de "ID do Aplicativo de Identidade do Serviço" gerado junto com workspace do Factory ou do Synapse.

  2. Conceda à identidade gerenciada atribuída pelo sistema acesso ao Data Lake Storage. Veja exemplos de como a permissão funciona no Data Lake Storage Gen1 em Controle de acesso no Azure Data Lake Storage Gen1.

    • Como origem: em Data Explorer>Acesso, conceda pelo menos a permissão Execução para TODAS as pastas acima, incluindo a raiz, junto com a permissão Leitura para os arquivos que serão copiados. Você pode optar por adicionar a Esta pasta e todos os filhos para recursivo e adicionar como uma permissão de acesso e uma entrada de permissão padrão. Não há requisito de controle de acesso no nível da conta (IAM).
    • Como coletor: em Data Explorer>Acesso, conceda pelo menos a permissão Execução para TODAS as pastas acima, incluindo a raiz, junto com a permissão Gravação para a pasta coletora. Você pode optar por adicionar a Esta pasta e todos os filhos para recursivo e adicionar como uma permissão de acesso e uma entrada de permissão padrão.

Você não precisa especificar nenhuma propriedade além das informações do Data Lake Store gerais no serviço vinculado.

Exemplo:

{
    "name": "AzureDataLakeStoreLinkedService",
    "properties": {
        "type": "AzureDataLakeStore",
        "typeProperties": {
            "dataLakeStoreUri": "https://<accountname>.azuredatalakestore.net/webhdfs/v1",
            "subscriptionId": "<subscription of ADLS>",
            "resourceGroupName": "<resource group of ADLS>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Usar a autenticação de identidade gerenciada atribuída pelo usuário

Um data factory pode ser atribuído com uma ou várias identidades gerenciadas atribuídas pelo usuário. Você pode usar essa identidade gerenciada atribuída pelo usuário para autenticação do Armazenamento de Blob, que permite acessar e copiar dados de ou para o Data Lake Store. Para saber mais sobre as identidades gerenciadas para os recursos do Azure, confira o artigo Identidades gerenciadas para recursos do Azure

Para usar a autenticação de identidade gerenciada atribuída pelo usuário, siga estas etapas:

  1. Crie uma ou várias identidades gerenciadas atribuídas ao usuário e conceda acesso ao Azure Data Lake. Veja exemplos de como a permissão funciona no Data Lake Storage Gen1 em Controle de acesso no Azure Data Lake Storage Gen1.

    • Como origem: em Data Explorer>Acesso, conceda pelo menos a permissão Execução para TODAS as pastas acima, incluindo a raiz, junto com a permissão Leitura para os arquivos que serão copiados. Você pode optar por adicionar a Esta pasta e todos os filhos para recursivo e adicionar como uma permissão de acesso e uma entrada de permissão padrão. Não há requisito de controle de acesso no nível da conta (IAM).
    • Como coletor: em Data Explorer>Acesso, conceda pelo menos a permissão Execução para TODAS as pastas acima, incluindo a raiz, junto com a permissão Gravação para a pasta coletora. Você pode optar por adicionar a Esta pasta e todos os filhos para recursivo e adicionar como uma permissão de acesso e uma entrada de permissão padrão.
  2. Atribua uma ou várias identidades gerenciadas atribuídas pelo usuário a seu data factory e crie credenciais para cada identidade gerenciada atribuída pelo usuário.

A propriedade a seguir tem suporte:

Propriedade Descrição Obrigatório
credenciais Especifique a identidade gerenciada atribuída pelo usuário como o objeto da credencial. Sim

Exemplo:

{
    "name": "AzureDataLakeStoreLinkedService",
    "properties": {
        "type": "AzureDataLakeStore",
        "typeProperties": {
            "dataLakeStoreUri": "https://<accountname>.azuredatalakestore.net/webhdfs/v1",
            "subscriptionId": "<subscription of ADLS>",
            "resourceGroupName": "<resource group of ADLS>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Propriedades do conjunto de dados

Para obter uma lista completa das seções e propriedades disponíveis para definir os conjuntos de dados, confira o artigo sobre Conjuntos de Dados.

O Azure Data Factory é compatível com os formatos de arquivo a seguir. Confira cada artigo para obter configurações baseadas em formato.

As seguintes propriedades são compatíveis com o Azure Data Lake Storage Gen1 em configurações de location no conjunto de dados baseado em formato:

Propriedade Descrição Obrigatório
type A propriedade type em location no conjunto de dados deve ser definida como AzureDataLakeStoreLocation. Sim
folderPath O caminho para uma pasta. Se você quiser usar um caractere curinga para filtrar a pasta, ignore essa configuração e especifique-o nas configurações de origem da atividade. Não
fileName O nome do arquivo sob o folderPath fornecido. Se você quiser usar um caractere curinga para filtrar os arquivos, ignore essa configuração e especifique-o nas configurações de origem da atividade. Não

Exemplo:

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

Propriedades da atividade de cópia

Para obter uma lista completa das seções e propriedades disponíveis para definir as atividades, veja Pipelines. Esta seção fornece uma lista das propriedades com suporte pela origem e pelo coletor do Azure Data Lake Store.

Azure Data Lake Store como fonte

O Azure Data Factory é compatível com os formatos de arquivo a seguir. Confira cada artigo para obter configurações baseadas em formato.

As seguintes propriedades são compatíveis com o Azure Data Lake Storage Gen1 em configurações de storeSettings na fonte de dados baseada em formato:

Propriedade Descrição Obrigatório
type A propriedade type em storeSettings deve ser configurada com AzureDataLakeStoreReadSettings. Sim
Localize os arquivos a serem copiados:
OPÇÃO 1: caminho estático
Copiar do caminho de pasta/arquivo especificado no conjunto de dados. Se quiser copiar todos os arquivos de uma pasta, especifique também wildcardFileName como *.
OPÇÃO 2: intervalo de nome
- listAfter
Recupera as pastas/arquivos cujo nome está depois desse valor em ordem alfabética (exclusivo). Utiliza o filtro do lado do serviço para ADLS Gen1, que fornece melhor desempenho do que um filtro curinga.
O serviço aplica esse filtro ao caminho definido no conjunto de dados e há suporte para apenas um nível de entidade. Veja mais exemplos em exemplos de filtro de intervalo de nome.
No
OPÇÃO 2: intervalo de nome
- listBefore
Recupera as pastas/arquivos cujo nome está antes desse valor em ordem alfabética (inclusivo). Utiliza o filtro do lado do serviço para ADLS Gen1, que fornece melhor desempenho do que um filtro curinga.
O serviço aplica esse filtro ao caminho definido no conjunto de dados e há suporte para apenas um nível de entidade. Veja mais exemplos em exemplos de filtro de intervalo de nome.
Não
OPÇÃO 3: curinga
- wildcardFolderPath
O caminho da pasta com caracteres curinga para filtrar as pastas de origem.
Os curingas permitidos são: * (corresponde a zero ou mais caracteres) e ? (corresponde a zero ou caractere único); use ^ para escape se o nome de pasta atual tiver curinga ou esse caractere interno de escape.
Veja mais exemplos em Exemplos de filtro de pastas e arquivos.
Não
OPÇÃO 3: curinga
- wildcardFileName
O nome do arquivo com caracteres curinga sob o folderPath/wildcardFolderPath fornecido para filtrar os arquivos de origem.
Os curingas permitidos são: * (corresponde a zero ou mais caracteres) e ? (corresponde a zero ou caractere único); use ^ para escape se o nome de arquivo real tiver curinga ou esse caractere interno de escape. Veja mais exemplos em Exemplos de filtro de pastas e arquivos.
Sim
OPÇÃO 4: uma lista de arquivos
- fileListPath
Indica a cópia de um determinado conjunto de arquivos. Aponte para um arquivo de texto que inclui a lista de arquivos que você deseja copiar com um arquivo por linha, que é o caminho relativo para o caminho configurado no conjunto de dados.
Ao utilizar essa opção, não especifique o nome do arquivo no conjunto de dados. Veja mais exemplos em Exemplos de lista de arquivos.
Não
Configurações adicionais:
recursiva Indica se os dados são lidos recursivamente das subpastas ou somente da pasta especificada. Quando recursiva é definida como true e o coletor é um armazenamento baseado em arquivo, uma pasta vazia ou subpasta não é copiada ou criada no coletor.
Os valores permitidos são true (padrão) e false.
Essa propriedade não se aplica quando você configura fileListPath.
Não
deleteFilesAfterCompletion Indica se os arquivos binários serão excluídos do repositório de origem após a movimentação com êxito para o repositório de destino. A exclusão de arquivos é feita por arquivo, portanto, quando a atividade de Cópia falhar, você conferirá que alguns arquivos já foram copiados para o destino e excluídos da origem, enquanto outros ainda permanecem no armazenamento de origem.
Essa propriedade só é válida no cenário de cópia de arquivos binários. O valor padrão é false.
Não
modifiedDatetimeStart Filtro de arquivos com base no atributo: Última Modificação.
Os arquivos são selecionados se a hora da última modificação for maior ou igual a modifiedDatetimeStart e menor que modifiedDatetimeEnd. A hora é aplicada ao fuso horário de UTC no formato "2018-12-01T05:00:00Z".
As propriedades podem ser NULL, o que significa que nenhum filtro de atributo de arquivo é aplicado ao conjunto de dados. Quando modifiedDatetimeStart tem valor de data e hora, mas modifiedDatetimeEnd é nulo, isso significa que os arquivos cujo atributo de última modificação é maior ou igual ao valor de data e hora estão selecionados. Quando modifiedDatetimeEnd tem valor de data e hora, mas modifiedDatetimeStart é nulo, isso significa que os arquivos cujo atributo da última modificação é menor que o valor de data e hora são selecionados.
Essa propriedade não se aplica quando você configura fileListPath.
Não
modifiedDatetimeEnd Mesmo que acima. Não
enablePartitionDiscovery Para arquivos que são particionados, especifique se deseja analisar as partições do caminho do arquivo e adicioná-las como colunas de origem adicionais.
Os valores permitidos são false (padrão) e true.
No
partitionRootPath Quando a descoberta de partição estiver habilitada, especifique o caminho raiz absoluto para ler as pastas particionadas como colunas de dados.

Se não for especificado, será por padrão,
– Quando você usa o caminho do arquivo no conjunto de dados ou na lista de arquivos na origem, o caminho raiz da partição é o caminho configurado no conjunto de dados.
- Quando você utiliza o filtro da pasta curinga, o caminho raiz da partição é o subcaminho antes do primeiro curinga.

Por exemplo, supondo que você configure o caminho no conjunto de dados como "root/folder/year=2020/month=08/day=27":
- Se você especificar o caminho da raiz da partição como "root/folder/year=2020", a atividade de Cópia gerará mais duas colunas month e day com valor "08" e "27", respectivamente, além das colunas dentro dos arquivos.
- Se o caminho da raiz da partição não for especificado, nenhuma coluna extra será gerada.
Não
maxConcurrentConnections O limite superior de conexões simultâneas estabelecidas com o armazenamento de dados durante a execução da atividade. Especifique um valor somente quando desejar limitar as conexões simultâneas. Não

Exemplo:

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

Azure Data Lake Store como coletor

O Azure Data Factory é compatível com os formatos de arquivo a seguir. Confira cada artigo para obter configurações baseadas em formato.

As seguintes propriedades são compatíveis com o Azure Data Lake Storage Gen1 em configurações de storeSettings no coletor de dados baseado em formato:

Propriedade Descrição Obrigatório
type A propriedade type em storeSettings deve ser configurada com AzureDataLakeStoreWriteSettings. Sim
copyBehavior Define o comportamento de cópia quando a fonte for de arquivos de um armazenamento de dados baseado em arquivo.

Valores permitidos são:
– PreserveHierarchy (padrão): Preserva a hierarquia de arquivos na pasta de destino. O caminho relativo do arquivo de origem para a pasta de origem é idêntico ao caminho relativo do arquivo de destino para a pasta de destino.
– FlattenHierarchy: Todos os arquivos da pasta de origem estão no primeiro nível da pasta de destino. Os arquivos de destino têm os nomes gerados automaticamente.
– MergeFiles: Mescla todos os arquivos da pasta de origem em um arquivo. Se o nome do arquivo for especificado, o nome do arquivo mesclado será o nome especificado. Caso contrário, ele será um nome de arquivo gerado automaticamente.
Não
expiryDateTime Especifica a hora de expiração dos arquivos gravados. A hora é aplicada ao fuso horário de UTC no formato "2020-03-01T08:00:00Z". Por padrão, é NULO, o que significa que os arquivos gravados nunca expiram. Não
maxConcurrentConnections O limite superior de conexões simultâneas estabelecidas com o armazenamento de dados durante a execução da atividade. Especifique um valor somente quando desejar limitar as conexões simultâneas. Não

Exemplo:

"activities":[
    {
        "name": "CopyToADLSGen1",
        "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": "AzureDataLakeStoreWriteSettings",
                    "copyBehavior": "PreserveHierarchy"
                }
            }
        }
    }
]

Exemplos de filtro de intervalo de nome

Esta seção descreve o comportamento resultante de filtros de intervalo de nome.

Exemplo de estrutura de origem Configuração Resultado
root
    um
        file.csv
    ax
        file2.csv
    ax.csv
    b
        file3.csv
    bx.csv
    c
        file4.csv
    cx.csv
No conjunto de dados:
- Caminho da pasta: root

Na origem da atividade de cópia:
- Listar depois de: a
- Listar antes de: b
Em seguida, os seguintes arquivos serão copiados:

root
    ax
        file2.csv
    ax.csv
    b
        file3.csv

Exemplos de filtro de pasta e arquivo

Esta seção descreve o comportamento resultante do caminho da pasta e do nome de arquivo com filtros curinga.

folderPath fileName recursiva Estrutura da pasta de origem e resultado do filtro (os arquivos em negrito são recuperados)
Folder* (Vazio, usar padrão) false FolderA
    Arquivo1.csv
    File2.json
    Subpasta1
        File3.csv
        File4.json
        File5.csv
OutraPastaB
    Arquivo6.csv
Folder* (Vazio, usar padrão) true FolderA
    Arquivo1.csv
    File2.json
    Subpasta1
        File3.csv
        File4.json
        File5.csv
OutraPastaB
    Arquivo6.csv
Folder* *.csv false FolderA
    Arquivo1.csv
    Arquivo2.json
    Subpasta1
        File3.csv
        File4.json
        File5.csv
OutraPastaB
    Arquivo6.csv
Folder* *.csv true FolderA
    Arquivo1.csv
    Arquivo2.json
    Subpasta1
        File3.csv
        File4.json
        File5.csv
OutraPastaB
    Arquivo6.csv

Exemplos de lista de arquivos

Esta seção descreve o comportamento resultante do uso do caminho da lista de arquivos na origem da atividade de cópia.

Supondo que você tenha a seguinte estrutura de pasta de origem e queira copiar os arquivos em negrito:

Exemplo de estrutura de origem Conteúdo em FileListToCopy.txt Configuração
root
    FolderA
        Arquivo1.csv
        Arquivo2.json
        Subpasta1
            File3.csv
            File4.json
            File5.csv
    Metadados
        FileListToCopy.txt
File1.csv
Subfolder1/File3.csv
Subfolder1/File5.csv
No conjunto de dados:
- Caminho da pasta: root/FolderA

Na origem da atividade de cópia:
- Caminho da lista de arquivos: root/Metadata/FileListToCopy.txt

O caminho da lista de arquivos aponta para um arquivo de texto no mesmo armazenamento de dados que inclui a lista de arquivos que você deseja copiar, um arquivo por linha, com o caminho relativo do caminho configurado no conjunto de dados.

Exemplos de comportamento da operação de cópia

Esta seção descreve o comportamento resultante da operação de Cópia para diferentes combinações de valores recursive e copyBehavior.

recursiva copyBehavior Estrutura de pasta de origem Destino resultante
true preserveHierarchy Pasta1
    Arquivo1
    Arquivo2
    Subpasta1
        Arquivo3
        Arquivo4
        Arquivo5
A Pasta1 de destino é criada com a mesma estrutura da origem:

Pasta1
    Arquivo1
    Arquivo2
    Subpasta1
        Arquivo3
        Arquivo4
        Arquivo5.
true flattenHierarchy Pasta1
    Arquivo1
    Arquivo2
    Subpasta1
        Arquivo3
        Arquivo4
        Arquivo5
A Pasta1 de destino é criada com a seguinte estrutura:

Pasta1
    nome gerado automaticamente para o Arquivo1
    nome gerado automaticamente para o Arquivo2
    nome gerado automaticamente para o Arquivo3
    nome gerado automaticamente para o Arquivo4
    nome gerado automaticamente para o Arquivo5
true mergeFiles Pasta1
    Arquivo1
    Arquivo2
    Subpasta1
        Arquivo3
        Arquivo4
        Arquivo5
A Pasta1 de destino é criada com a seguinte estrutura:

Pasta1
    Os conteúdos de Arquivo1 + Arquivo2 + Arquivo3 + Arquivo4 + Arquivo5 são mesclados em um arquivo com um nome de arquivo gerado automaticamente.
false preserveHierarchy Pasta1
    Arquivo1
    Arquivo2
    Subpasta1
        Arquivo3
        Arquivo4
        Arquivo5
A Pasta1 de destino é criada com a seguinte estrutura:

Pasta1
    Arquivo1
    Arquivo2

Subpasta1 com Arquivo3, Arquivo4 e Arquivo5 não selecionada.
false flattenHierarchy Pasta1
    Arquivo1
    Arquivo2
    Subpasta1
        Arquivo3
        Arquivo4
        Arquivo5
A Pasta1 de destino é criada com a seguinte estrutura:

Pasta1
    nome gerado automaticamente para o Arquivo1
    nome gerado automaticamente para o Arquivo2

Subpasta1 com Arquivo3, Arquivo4 e Arquivo5 não selecionada.
false mergeFiles Pasta1
    Arquivo1
    Arquivo2
    Subpasta1
        Arquivo3
        Arquivo4
        Arquivo5
A Pasta1 de destino é criada com a seguinte estrutura:

Pasta1
    Os conteúdos de Arquivo1 + Arquivo2 são mesclados em um arquivo com um nome de arquivo gerado automaticamente. nome gerado automaticamente para o Arquivo1

Subpasta1 com Arquivo3, Arquivo4 e Arquivo5 não selecionada.

Preservar ACLs do Data Lake Storage Gen2

Dica

Para copiar dados do Azure Data Lake Storage Gen1 no Gen2 em geral, confira Copiar dados de Azure Data Lake Storage Gen1 no Gen2 para obter instruções detalhadas e melhores práticas.

Se você quiser replicar as ACLs (listas de controle de acesso) junto com os arquivos de dados ao atualizar do Data Lake Storage Gen1 para o Data Lake Storage Gen2, consulte Preservar ACLs do Data Lake Storage Gen1.

Propriedades do fluxo de dados de mapeamento

Ao transformar dados no fluxo de dados de mapeamento, você pode ler e gravar arquivos do Azure Data Lake Storage Gen1 nos seguintes formatos:

As configurações específicas de formato estão localizadas na documentação para esse formato. Para obter mais informações, consulte Transformação de origem em fluxo de dados de mapeamento e Transformação do coletor em fluxo de dados de mapeamento.

Transformação de origem

Na transformação de origem, você pode ler de um contêiner, pasta ou arquivo individual no Azure Data Lake Storage Gen1. A guia Opções de origem permite que você gerencie como os arquivos são lidos.

Screenshot of source options tab in mapping data flow source transformation.

Caminho curinga: O uso de um padrão curinga instruirá o serviço a executar um loop em cada pasta e arquivo correspondentes em uma única transformação de origem. Esse é um modo eficaz de processar vários arquivos dentro de um único fluxo. Adicione vários padrões de correspondência de curingas com o sinal de + que aparece ao passar o mouse sobre o padrão de curinga existente.

Em seu contêiner de origem, escolha uma série de arquivos que correspondem a um padrão. Somente o contêiner pode ser especificado no conjunto de dados. O caminho curinga, portanto, também precisa incluir o caminho da pasta raiz.

Exemplos de caracteres curinga:

  • * Representa qualquer conjunto de caracteres

  • ** Representa o aninhamento de diretório recursivo

  • ? Substitui um caractere

  • [] Corresponde a um ou mais caracteres entre colchetes

  • /data/sales/**/*.csv Obtém todos os arquivos CSV em /data/sales

  • /data/sales/20??/**/ Obtém todos os arquivos recursivamente em todas as pastas 20xx correspondentes

  • /data/sales/*/*/*.csv Obtém arquivos CSV dois níveis em /data/sales

  • /data/sales/2004/12/[XY]1?.csv Obtém todos os arquivos csv de dezembro de 2004 começando com X ou Y, seguidos por 1 e qualquer caractere único

Caminho raiz da partição: se você tiver pastas particionadas em sua fonte de arquivo com um formato key=value (por exemplo, year=2019), poderá atribuir o nível superior da árvore de pastas dessa partição a um nome de coluna no fluxo de dados.

Primeiro, defina um curinga para incluir todos os caminhos que são as pastas particionadas mais os arquivos folha que você deseja ler.

Screenshot of partition source file settings in mapping data flow source transformation.

Use a configuração do caminho raiz da partição para definir qual é o nível superior da estrutura de pastas. Ao exibir o conteúdo dos seus dados por meio de uma prévia de dados, você confere que o serviço adiciona as partições resolvidas encontradas em cada um dos níveis de pasta.

Partition root path

Lista de arquivos: é um conjunto de arquivos. Crie um arquivo de texto que inclui uma lista de arquivos do caminho relativo a serem processados. Aponte para este arquivo de texto.

Coluna para armazenar o nome do arquivo: armazene o nome do arquivo de origem em uma coluna em seus dados. Insira um novo nome de coluna para armazenar a cadeia de caracteres de nome de arquivo.

Após a conclusão: Opte por não fazer nada com o arquivo de origem após a execução de fluxo de dados, excluir o arquivo de origem ou mover o arquivo de origem. Os caminhos para movimentação são relativos.

Para mover os arquivos de origem para outro local após o processamento, primeiro selecione "Mover" para a operação de arquivo. Em seguida, defina o diretório "de". Se não estiver utilizando nenhum curinga no caminho, a configuração "de" será a mesma pasta da pasta de origem.

Se você tiver um caminho de origem com curinga, sua sintaxe será semelhante à seguinte:

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

Você pode especificar "de" como

/data/sales

E "para" como

/backup/priorSales

Nesse caso, todos os arquivos que foram originados em /data/sales são movidos para /backup/priorSales.

Observação

As operações do arquivo são executadas somente quando você inicia o fluxo de dados de uma execução de pipeline (depuração de pipeline ou realização da execução) que usa a atividade Executar Fluxo de Dados em um pipeline. As operações de arquivo não são executadas no modo de depuração do Fluxo de Dados.

Filtrar por última modificação: você pode filtrar quais arquivos são processados especificando um intervalo de datas de quando eles foram modificados pela última vez. Todos os datetimes estão em UTC.

Habilitar captura de dados de alterações: se verdadeiro, você receberá arquivos novos ou alterados somente a partir da última execução. O carregamento inicial de dados de instantâneo completo sempre será obtido na primeira execução, seguido pela captura de arquivos novos ou alterados apenas nas próximas execuções. Para obter mais detalhes, confira Captura de dados de alterações.

Screenshot showing Enable change data capture.

Propriedades do coletor

Na transformação do coletor, você pode gravar em um contêiner ou pasta no Azure Data Lake Storage Gen1. A guia Configurações permite que você gerencie como os arquivos são gravados.

sink options

Limpe a pasta: determina se a pasta de destino é limpa ou não antes de os dados serem gravados.

Opção do nome do arquivo: determina como os arquivos de destino são nomeados na pasta de destino. As opções de nome de arquivo são:

  • Padrão: permitir que o Spark nomeie arquivos com base nos padrões de PART.
  • Padrão: insira um padrão que enumere os arquivos de saída por partição. Por exemplo, loans[n].csv cria loans1.csv, loans2.csv e assim por diante.
  • Por partição: insira um nome de arquivo por partição.
  • Como dados na coluna: defina o arquivo de saída para o valor de uma coluna. O caminho é relativo ao contêiner de conjunto de dados, não à pasta de destino. Se você tiver um caminho de pasta no seu conjunto de dados, ele será substituído.
  • Saída para um único arquivo: combine os arquivos de saída particionados em um único arquivo nomeado. O caminho é relativo à pasta do conjunto de dados. Lembre-se de que a operação de mesclagem pode falhar com base no tamanho do nó. Essa opção não é recomendada para conjuntos de dados grandes.

Citar tudo: determina se todos os valores devem ser delimitados por aspas

Pesquisar propriedades de atividades

Para saber detalhes sobre as propriedades, verifique Atividade de pesquisa.

Propriedades de atividade GetMetadata

Para saber detalhes sobre as propriedades, verifique Atividade GetMetadata

Excluir propriedades da atividade

Para saber mais detalhes sobre as propriedades, marque Excluir atividade

Modelos herdados

Observação

Os modelos a seguir ainda têm suporte no estado em que se encontram, para compatibilidade com versões anteriores. É recomendável usar o novo modelo mencionado nas seções acima no futuro, e a interface do usuário de criação mudou para gerar o novo modelo.

Modelo de conjunto de dados herdado

Propriedade Descrição Obrigatório
type A propriedade type do conjunto de dados deve ser definida como AzureDataLakeStoreFile. Sim
folderPath Caminho para a pasta no Data Lake Store. Se não especificado, apontará para a raiz.

O filtro curinga tem suporte. Os curingas permitidos são * (corresponde a zero ou mais caracteres) e ? (corresponde a zero ou caractere único). Use ^ como escape se o nome real da pasta tiver curingas ou esse caractere de escape.

Por exemplo: rootfolder/subfolder/. Veja mais exemplos em Exemplos de filtro de pastas e arquivos.
Não
fileName Filtro de nome ou curinga para os arquivos no "folderPath" especificado. Se você não especificar um valor para essa propriedade, o conjunto de dados apontará para todos os arquivos na pasta.

Para filtro, os curingas permitidos são * (corresponde a zero ou mais caracteres) e ? (corresponde a zero ou caractere único).
– Exemplo 1: "fileName": "*.csv"
– Exemplo 2: "fileName": "???20180427.txt"
Use ^ como escape se seu nome de arquivo real tiver um curinga ou esse caractere de escape.

Quando fileName não for especificado para um conjunto de dados de saída e preserveHierarchy não for especificada no coletor de atividade, a atividade de cópia gerará automaticamente o nome do arquivo com o seguinte padrão: "Data.[GUID da ID de execução da atividade].[GUID se FlattenHierarchy].[formato se configurado].[compactação se configurada] ", por exemplo: "Data.0a405f8a-93ff-4c6f-b3be-f69616f1df7a.txt.gz". Se você copiar da fonte tabular usando o nome da tabela em vez da consulta, o nome padrão será " [nome da tabela].[formato].[compactação se configurada] ", por exemplo, "MyTable.csv".
Não
modifiedDatetimeStart Filtro de arquivos com base no atributo Última Modificação. Os arquivos são selecionados se a hora da última modificação é maior ou igual a modifiedDatetimeStart e menor que modifiedDatetimeEnd. A hora é aplicada ao fuso horário de UTC no formato "2018-12-01T05:00:00Z".

O desempenho geral da movimentação de dados será afetado ao habilitar essa configuração quando você desejar filtrar grandes quantidades de arquivos.

As propriedades podem ser NULL, o que significa que nenhum filtro de atributo de arquivo é aplicado ao conjunto de dados. Quando modifiedDatetimeStart tiver o valor de datetime, mas modifiedDatetimeEnd for NULL, isso significa que serão selecionados os arquivos cujo último atributo modificado é maior ou igual ao valor de datetime. Quando modifiedDatetimeEnd tiver o valor de datetime, mas modifiedDatetimeStart for NULL, isso significa que serão selecionados os arquivos cujo último atributo modificado é menor que o valor de datetime.
Não
modifiedDatetimeEnd Filtro de arquivos com base no atributo Última Modificação. Os arquivos são selecionados se a hora da última modificação é maior ou igual a modifiedDatetimeStart e menor que modifiedDatetimeEnd. A hora é aplicada ao fuso horário de UTC no formato "2018-12-01T05:00:00Z".

O desempenho geral da movimentação de dados será afetado ao habilitar essa configuração quando você desejar filtrar grandes quantidades de arquivos.

As propriedades podem ser NULL, o que significa que nenhum filtro de atributo de arquivo é aplicado ao conjunto de dados. Quando modifiedDatetimeStart tiver o valor de datetime, mas modifiedDatetimeEnd for NULL, isso significa que serão selecionados os arquivos cujo último atributo modificado é maior ou igual ao valor de datetime. Quando modifiedDatetimeEnd tiver o valor de datetime, mas modifiedDatetimeStart for NULL, isso significa que serão selecionados os arquivos cujo último atributo modificado é menor que o valor de datetime.
Não
format Se você quiser copiar arquivos no estado em que se encontram entre repositórios baseados em arquivo (cópia binária), ignore a seção de formato nas definições de conjunto de dados de entrada e de saída.

Se você quer analisar ou gerar arquivos com um formato específico, os seguintes tipos de formato de arquivo são compatíveis: TextFormat, JsonFormat, AvroFormat, OrcFormat e ParquetFormat. Defina a propriedade type sob format para um desses valores. Para saber mais, veja as seções Formato de texto, Formato JSON, Formato Avro, Formato Orc e Formato Parquet.
Não (somente para o cenário de cópia binária)
compactação Especifique o tipo e o nível de compactação para os dados. Para obter mais informações, consulte Formatos de arquivo e codecs de compactação com suporte.
Os tipos com suporte são: GZip, Deflate, BZip2 e ZipDeflate.
Os níveis de suporte são Ideal e Mais rápido.
Não

Dica

Para copiar todos os arquivos em uma pasta, especifique folderPath somente.
Para copiar um único arquivo com um nome em particular, especifique folderPath com uma parte da pasta e fileName com um nome de arquivo.
Para copiar um subconjunto de arquivos em uma pasta, especifique folderPath com uma parte da pasta e fileName com um filtro curinga.

Exemplo:

{
    "name": "ADLSDataset",
    "properties": {
        "type": "AzureDataLakeStoreFile",
        "linkedServiceName":{
            "referenceName": "<ADLS linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "folderPath": "datalake/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 origem de atividade de cópia herdado

Propriedade Descrição Obrigatório
type A propriedade type da fonte da atividade de cópia deve ser definida como AzureDataLakeStoreSource. Sim
recursiva Indica se os dados são lidos recursivamente das subpastas ou somente da pasta especificada. Quando recursive é definido como true e o coletor é um repositório baseado em arquivo, uma pasta vazia ou subpasta não é copiada ou criada no coletor. Os valores permitidos são true (padrão) e false. Não
maxConcurrentConnections O limite superior de conexões simultâneas estabelecidas com o armazenamento de dados durante a execução da atividade. Especifique um valor somente quando desejar limitar as conexões simultâneas. Não

Exemplo:

"activities":[
    {
        "name": "CopyFromADLSGen1",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<ADLS Gen1 input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "AzureDataLakeStoreSource",
                "recursive": true
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Modelo do coletor de atividade de cópia herdado

Propriedade Descrição Obrigatório
type A propriedade type do coletor da atividade de cópia deve ser definida como AzureDataLakeStoreSink. Sim
copyBehavior Define o comportamento de cópia quando a fonte for de arquivos de um armazenamento de dados baseado em arquivo.

Valores permitidos são:
– PreserveHierarchy (padrão): Preserva a hierarquia de arquivos na pasta de destino. O caminho relativo do arquivo de origem para a pasta de origem é idêntico ao caminho relativo do arquivo de destino para a pasta de destino.
– FlattenHierarchy: Todos os arquivos da pasta de origem estão no primeiro nível da pasta de destino. Os arquivos de destino têm os nomes gerados automaticamente.
– MergeFiles: Mescla todos os arquivos da pasta de origem em um arquivo. Se o nome do arquivo for especificado, o nome do arquivo mesclado será o nome especificado. Caso contrário, o nome do arquivo será gerado automaticamente.
Não
maxConcurrentConnections O limite superior de conexões simultâneas estabelecidas com o armazenamento de dados durante a execução da atividade. Especifique um valor somente quando desejar limitar as conexões simultâneas. Não

Exemplo:

"activities":[
    {
        "name": "CopyToADLSGen1",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<ADLS Gen1 output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "AzureDataLakeStoreSink",
                "copyBehavior": "PreserveHierarchy"
            }
        }
    }
]

Captura de dados de alterações (visualização)

O Azure Data Factory pode obter arquivos novos ou alterados somente do Azure Data Lake Storage Gen1 habilitando a opção Habilitar a captura de dados de alterações (versão prévia) na transformação de origem do fluxo de dados de mapeamento. Com essa opção de conector, você pode ler arquivos novos ou atualizados somente e aplicar transformações antes de carregar dados transformados nos conjuntos de dados de destino de sua escolha.

Confirme se mantém o pipeline e o nome da atividade inalterados, para que o ponto de verificação sempre possa ser gravado da última execução para se obterem as alterações a partir daí. Se você alterar o nome do pipeline ou o nome da atividade, o ponto de verificação será redefinido e você começará do início na próxima execução.

Quando você depura o pipeline, a opção Habilitar a captura de dados de alterações (visualização) também funciona. O ponto de verificação é redefinido quando você atualiza o navegador durante a execução de depuração. Quando estiver satisfeito com o resultado da execução de depuração, você poderá publicar e disparar o pipeline. Ele sempre começará do início, independentemente do ponto de verificação anterior registrado pela execução de depuração.

Na seção de monitoramento, sempre existe a possibilidade de reexecutar um pipeline. Ao fazer isso, as alterações são sempre obtidas do registro do ponto de verificação na execução do pipeline selecionado.

Para obter uma lista de armazenamentos de dados com suporte como coletores e fontes da atividade de cópia, confira os armazenamentos de dados com suporte.