Compartilhar via

Copiar e transformar dados no Lakehouse do Microsoft Fabric 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 completa 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 nova avaliação gratuitamente!

O Microsoft Fabric Lakehouse é uma plataforma de arquitetura de dados para armazenar, gerenciar e analisar dados estruturados e não estruturados em um único local. Para obter acesso contínuo a dados em todos os mecanismos de computação no Microsoft Fabric, acesse o Lakehouse e as Tabelas Delta para saber mais. Por padrão, os dados são gravados na Tabela Lakehouse em V-Order e você pode acessar a Otimização de tabela do Delta Lake e V-Order para mais informações.

Este artigo descreve como usar a atividade Copy para copiar dados de e para o Lakehouse do Microsoft Fabric e usar o Fluxo de Dados para transformar dados no Microsoft Fabric Lakehouse. Para saber mais, leia o artigo introdutório do Azure Data Factory ou do Azure Synapse Analytics.

Funcionalidades com suporte

Este conector do Lakehouse do Microsoft Fabric tem suporte para os seguintes recursos:

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

① Tempo de execução de integração do Azure ② Tempo de execução de integração auto-hospedado

Esse conector dá suporte à conexão com o Microsoft Fabric Lakehouse no espaço de trabalho com um link privado habilitado. Você pode configurar e usar um link privado no Microsoft Fabric referindo-se a este artigo.

Para dar suporte ao link privado no nível do workspace no runtime de integração auto-hospedada (versão 5.58.9377.1 ou superior), você precisa adicionar *.dfs.fabric.microsoft.com à lista de permitidos para garantir que o conector do Microsoft Fabric Lakehouse possa acessar as APIs do Onelake por meio da rede.

Introdução

Para executar a atividade de cópia com um pipeline, você pode usar uma das seguintes ferramentas ou SDKs:

Criar um serviço vinculado do Microsoft Fabric Lakehouse por meio da interface do usuário

Use as etapas a seguir para criar um serviço vinculado do Microsoft Fabric Lakehouse 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 o Microsoft Fabric Lakehouse e selecione o conector.

    Captura de tela mostrando Selecionar o conector do Microsoft Fabric Lakehouse.

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

    Captura de tela da configuração do serviço vinculado do Microsoft Fabric Lakehouse.

Detalhes da configuração do conector

As seções a seguir fornecem detalhes sobre as propriedades usadas para definir entidades do Data Factory específicas do Microsoft Fabric Lakehouse.

Propriedades do serviço vinculado

O conector do Microsoft Fabric Lakehouse dá suporte aos tipos de autenticação a seguir. Consulte as seções correspondentes para obter detalhes:

Autenticação de entidade de serviço

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

  1. Registrar um aplicativo com a plataforma Microsoft Identity e adicionar um de segredo do cliente. Em seguida, anote estes valores; ele são usados para definir o serviço vinculado:

    • ID do aplicativo (cliente), que é a ID da entidade de serviço no serviço vinculado.
    • Valor do segredo do cliente, que é a chave da entidade de serviço no serviço vinculado.
    • ID do locatário

  2. Conceda à entidade de serviço, pelo menos, a função Colaborador no workspace do Microsoft Fabric. Siga as etapas em Conceder permissões no workspace do Microsoft Fabric

Estas propriedades têm suporte para o serviço vinculado:

Propriedade Descrição Obrigatório
tipo A propriedade type precisa ser definida como Lakehouse. Sim
workspaceId A ID do workspace do Microsoft Fabric. Sim
artifactId A ID do objeto do Microsoft Fabric Lakehouse. Sim
locatário Especifique as informações de locatário (domínio nome ou ID do Locatário) em que o aplicativo reside. Recupere-as passando o mouse no canto superior direito do Portal do Azure. Sim
servicePrincipalId Especifique a ID do cliente do aplicativo. Sim
servicePrincipalCredentialType O tipo de credencial a ser usada para autenticação da entidade de serviço. Os valores permitidos são ServicePrincipalKey e ServicePrincipalCert. Sim
servicePrincipalCredential A credencial da entidade de serviço.
Ao usar ServicePrincipalKey como o tipo de credencial, especifique o valor do segredo do cliente do aplicativo. Marque este campo como um SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault.
Quando usar ServicePrincipalCert como credencial, faça referência a um certificado no Azure Key Vault e verifique se o tipo de conteúdo do certificado é PKCS nº 12.		 Sim
connectVia O runtime de integração a ser usado para se conectar ao armazenamento de dados. Você pode usar o Azure Integration Runtime ou um runtime de integração auto-hospedada se o seu armazenamento de dados estiver em uma rede privada. Se não especificado, o Azure Integration Runtime padrão será usado. Não

Exemplo: usar a autenticação de chave de entidade de serviço

Você também pode armazenar a chave de entidade de serviço no Azure Key Vault.

{
    "name": "MicrosoftFabricLakehouseLinkedService",
    "properties": {
        "type": "Lakehouse",
        "typeProperties": {
            "workspaceId": "<Microsoft Fabric workspace ID>",
            "artifactId": "<Microsoft Fabric Lakehouse object ID>",
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<service principal key>"
            }   
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Autenticação de identidade gerenciada atribuída pelo sistema

Um pipeline do data factory ou do Synapse pode ser associado a uma identidade gerenciada atribuída pelo sistema para recursos do Azure, que representa esse recurso para autenticação em outros serviços do Azure. Você pode usar diretamente essa identidade gerenciada atribuída pelo sistema para autenticação do Microsoft Fabric Lakehouse, que é semelhante ao uso de sua própria entidade de serviço. Ele permite que esse recurso designado acesse e copie dados de ou para o Microsoft Fabric Lakehouse. Para saber mais sobre as identidades gerenciadas para recursos do Azure, confira Identidades gerenciadas para recursos do Azure.

Para usar identidades gerenciadas para autenticação de recursos do Azure, siga estas etapas:

  1. Recuperar identidade gerenciada atribuída pelo sistema copiando o valor da ID de objeto de identidade gerenciada atribuída pelo sistema gerado com o workspace do Factory ou do Synapse.

  2. Conceda à identidade gerenciada atribuída pelo sistema pelo menos a função Colaborador no workspace do Microsoft Fabric. Siga as etapas em Conceder permissões no workspace do Microsoft Fabric

Essas propriedades têm suporte para um serviço vinculado do Microsoft Fabric Lakehouse:

Propriedade Descrição Obrigatório
tipo A propriedade type deve ser definida como Lakehouse. Sim
workspaceId A ID do workspace do Microsoft Fabric. Sim
artifactId A ID do objeto do Microsoft Fabric Lakehouse. Sim
connectVia O runtime de integração a ser usado para se conectar ao armazenamento de dados. Você pode usar o Azure Integration Runtime ou um runtime de integração auto-hospedada se o seu armazenamento de dados estiver em uma rede privada. Se não especificado, o Azure Integration Runtime padrão será usado. Não

Exemplo:

{
    "name": "MicrosoftFabricLakehouseLinkedService",
    "properties": {
        "type": "Lakehouse",
        "typeProperties": {            
            "workspaceId": "<Microsoft Fabric workspace ID>",
            "artifactId": "<Microsoft Fabric Lakehouse object ID>",
            "authenticationType": "SystemAssignedManagedIdentity"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Observação

Não há suporte para esse tipo de autenticação no runtime de integração auto-hospedada.

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 a autenticação do Microsoft Fabric Lakehouse, que permite acessar e copiar dados de ou para o Microsoft Fabric Lakehouse. Para saber mais sobre as identidades gerenciadas para recursos do Azure, confira 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 pelo usuário.

  2. Conceda à identidade gerenciada atribuída pelo usuário pelo menos a função Colaborador no workspace do Microsoft Fabric. Siga as etapas em Conceder permissões no workspace do Microsoft Fabric.

  3. Atribua uma ou várias identidades gerenciadas atribuídas pelo usuário ao data factory e crie credenciais para cada identidade gerenciada atribuída pelo usuário.

Essas propriedades têm suporte para um serviço vinculado do Microsoft Fabric Lakehouse:

Propriedade Descrição Obrigatório
tipo A propriedade type deve ser definida como Lakehouse. Sim
workspaceId A ID do workspace do Microsoft Fabric. Sim
artifactId A ID do objeto do Microsoft Fabric Lakehouse. Sim
credenciais Especifique a identidade gerenciada atribuída pelo usuário como o objeto da credencial. Sim
connectVia O runtime de integração a ser usado para se conectar ao armazenamento de dados. Use o Azure Integration Runtime ou o runtime de integração auto-hospedada (se o seu armazenamento de dados estiver em uma rede privada). Se essa propriedade não for especificada, o serviço usará o Azure Integration Runtime padrão. Não

Exemplo:

{
    "name": "MicrosoftFabricLakehouseLinkedService",
    "properties": {
        "type": "Lakehouse",
        "typeProperties": {            
            "workspaceId": "<Microsoft Fabric workspace ID>",
            "artifactId": "<Microsoft Fabric Lakehouse object ID>",
            "authenticationType": "UserAssignedManagedIdentity",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Conceder permissões no workspace do Microsoft Fabric

Você precisa conceder à entidade de serviço/identidade gerenciada atribuída pelo sistema/identidade gerenciada atribuída pelo usuário pelo menos a função Colaborador no workspace do Microsoft Fabric. Siga estas etapas:

  1. Acesse o workspace do Microsoft Fabric e selecione Gerenciar acesso na barra superior. Em seguida, selecione Adicionar pessoas ou grupos.

    Captura de tela mostrando a seleção de Gerenciar acesso do workspace do Fabric. Captura de tela mostrando o painel Gerenciar acesso do workspace do Fabric.

  2. No painel Adicionar pessoas, insira sua entidade de serviço/identidade gerenciada atribuída pelo sistema/nome de identidade gerenciada atribuída pelo usuário e selecione-a na lista suspensa.

  3. Especifique a função como Colaborador ou superior (administrador, membro) e escolha Adicionar.

    Captura de tela mostrando a adição da função do workspace do Fabric.

  4. Sua entidade de serviço/identidade gerenciada atribuída pelo sistema/gerenciada atribuída pelo usuário é exibida no painel Gerenciar acesso.

Propriedades do conjunto de dados

O conector do Lakehouse do Microsoft Fabric dá suporte a dois tipos de conjuntos de dados, que são o Conjunto de dados de arquivos do Lakehouse do Microsoft Fabric e o Conjunto de dados de tabelas do Lakehouse do Microsoft Fabric. Consulte as seções correspondentes para obter detalhes.

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

Conjunto de dados de arquivos do Lakehouse do Microsoft Fabric

O conector do Lakehouse do Microsoft Fabric dá suporte aos formatos de arquivo a seguir. Confira cada artigo para obter configurações baseadas em formato.

Há suporte para as seguintes propriedades nas configurações de location no Conjunto de dados de arquivos do Lakehouse do Microsoft Fabric baseado em formato:

Propriedade Descrição Obrigatório
tipo A propriedade type em location no conjunto de dados precisa ser definida como LakehouseLocation. 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": "<Microsoft Fabric Lakehouse linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "location": {
                "type": "LakehouseLocation",
                "fileName": "<file name>",
                "folderPath": "<folder name>"
            },
            "columnDelimiter": ",",
            "compressionCodec": "gzip",
            "escapeChar": "\\",
            "firstRowAsHeader": true,
            "quoteChar": "\""
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ]
    }
}

Conjunto de dados de tabelas do Lakehouse do Microsoft Fabric

As propriedades a seguir têm suporte para o conjunto de dados de tabela do Microsoft Fabric Lakehouse:

Propriedade Descrição Obrigatório
tipo A propriedade type do conjunto de dados deve ser definida como LakehouseTable. Sim
esquema Nome do esquema. Se esse campo não for especificado, o valor padrão será dbo. Não
tabela O nome da sua tabela. O nome da tabela deve ter pelo menos um caractere, sem '/' ou '\', sem ponto à direita e sem espaços à esquerda ou à direita. Sim

Exemplo:

{ 
    "name": "LakehouseTableDataset", 
    "properties": {
        "type": "LakehouseTable",
        "linkedServiceName": { 
            "referenceName": "<Microsoft Fabric Lakehouse linked service name>", 
            "type": "LinkedServiceReference" 
        }, 
        "typeProperties": { 
            "schema": "<schema_name>",
            "table": "<table_name>"   
        },
        "schema": [< physical schema, optional, retrievable during authoring >]
    } 
}

Propriedades da atividade de cópia

As propriedades de atividade de cópia para o Conjunto de dados de arquivos do Lakehouse do Microsoft Fabric e o Conjunto de dados de tabelas do Lakehouse do Microsoft Fabric são diferentes. Consulte as seções correspondentes para obter detalhes.

Para obter uma lista completa de seções e propriedades disponíveis para definir atividades, confira Copiar configurações de atividade e Pipelines e atividades.

Arquivos do Lakehouse do Microsoft Fabric na atividade Copy

Para usar o tipo de Conjunto de dados de arquivos do Lakehouse do Microsoft Fabric como uma origem ou coletor na atividade Copy, acesse as seções a seguir para obter as configurações detalhadas.

Arquivos do Microsoft Fabric Lakehouse como um tipo de origem

O conector do Lakehouse do Microsoft Fabric dá suporte aos formatos de arquivo a seguir. Confira cada artigo para obter configurações baseadas em formato.

Você tem várias opções para copiar dados do Lakehouse do Microsoft Fabric usando o Conjunto de dados de arquivos do Lakehouse do Microsoft Fabric:

  • Copiar do caminho especificado no conjunto de dados.
  • Para filtrar usando caracteres curinga em relação ao caminho da pasta ou nome do arquivo, confira wildcardFolderPath e wildcardFileName.
  • Copie os arquivos definidos em um determinado arquivo de texto como conjunto de arquivos, confira fileListPath.

As propriedades a seguir estão nas configurações de storeSettings na origem de cópia baseada em formato ao usar o Conjunto de dados de arquivos do Lakehouse do Microsoft Fabric:

Propriedade Descrição Obrigatório
tipo A propriedade type em storeSettings precisa ser definida como LakehouseReadSettings. 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: 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 2: 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 3: 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 armazenamento de origem após serem movidos com êxito para o armazenamento de destino. A exclusão do arquivo é feita por arquivo, portanto, quando a atividade Copy falhar, você observa que alguns arquivos já foram copiados para o destino e excluídos da origem, enquanto outros ainda permanecem no repositório 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 serã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 o valor de data e hora, mas modifiedDatetimeEnd for NULL, isso significa que serão selecionados os arquivos cujo último atributo modificado é maior ou igual ao valor de data e hora. Quando modifiedDatetimeEnd tem o valor de data e hora, mas modifiedDatetimeStart for NULL, isso significa que serão selecionados os arquivos cujo último atributo modificado é menor que o valor de data e hora.
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 incluí-las como outras colunas de origem.
Os valores permitidos são false (padrão) e true.		 Não
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, 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 Copy 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 para 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": "CopyFromLakehouseFiles",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Delimited text input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "DelimitedTextSource",
                "storeSettings": {
                    "type": "LakehouseReadSettings",
                    "recursive": true,
                    "enablePartitionDiscovery": false
                },
                "formatSettings": {
                    "type": "DelimitedTextReadSettings"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Arquivos do Microsoft Fabric Lakehouse como um tipo de coletor

O conector do Lakehouse do Microsoft Fabric dá suporte aos formatos de arquivo a seguir. Confira cada artigo para obter configurações baseadas em formato.

Há suporte para as seguintes propriedades nos Arquivos do Lakehouse do Microsoft Fabric nas configurações de storeSettings no coletor de cópia baseado em formato:

Propriedade Descrição Obrigatório
tipo A propriedade type em storeSettings precisa ser definida como LakehouseWriteSettings. 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
blockSizeInMB Especifique o tamanho do bloco em MB usado para gravar dados no Lakehouse do Microsoft Fabric. Saiba mais sobre Blobs de Blocos.
O valor permitido é entre 4 MB e 100 MB.
Por padrão, o ADF determina automaticamente o tamanho do bloco com base no tipo de armazenamento de origem e nos dados. Para cópia não binária no Lakehouse do Microsoft Fabric, o tamanho do bloco padrão é de 100 MB, de modo a ajustar no máximo 4,75 TB de dados. Talvez não seja ideal quando os dados não forem grandes, especialmente ao usar o runtime de integração auto-hospedada com rede deficiente, resultando em tempo limite de operação ou problema de desempenho. É possível especificar explicitamente um tamanho de bloco, verificando se blockSizeInMB*50000 está grande o suficiente para armazenar os dados, caso contrário, haverá falha na execução da atividade de cópia.		 Não
maxConcurrentConnections O limite superior de conexões simultâneas estabelecidas para o armazenamento de dados durante a execução da atividade. Especifique um valor somente quando desejar limitar as conexões simultâneas. Não
metadados Defina metadados personalizados ao copiar para o coletor. Cada objeto sob a matriz metadata representa uma coluna extra. O name define o nome chave dos metadados e value indica o valor de dados dessa chave. Se o recurso preservar atributos for usado, os metadados especificados serão unificados/substituídos pelos metadados do arquivo de origem.

Os valores de dados permitidos são:
- $$LASTMODIFIED: uma variável reservada indica que se deve armazenar a hora da última modificação dos arquivos de origem. Aplicar à fonte baseada em arquivo somente com formato binário.
- Expressão
- Valor estático		 Não

Exemplo:

"activities": [
    {
        "name": "CopyToLakehouseFiles",
        "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": "LakehouseWriteSettings",
                    "copyBehavior": "PreserveHierarchy",
                    "metadata": [
                        {
                            "name": "testKey1",
                            "value": "value1"
                        },
                        {
                            "name": "testKey2",
                            "value": "value2"
                        }
                    ]
                },
                "formatSettings": {
                    "type": "ParquetWriteSettings"
                }
            }
        }
    }
]

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
     File1.csv
     File2.json
    Subfolder1
        Arquivo3.csv
        Arquivo4.json
        Arquivo5.csv
OutraPastaB
    File6.csv
Folder* (Vazio, usar padrão) true FolderA
     File1.csv
     File2.json
    Subfolder1
         File3.csv
         File4.json
         File5.csv
OutraPastaB
    File6.csv
Folder* *.csv false FolderA
     File1.csv
    File2.json
    Subfolder1
        Arquivo3.csv
        Arquivo4.json
        Arquivo5.csv
OutraPastaB
    File6.csv
Folder* *.csv true FolderA
     File1.csv
    File2.json
    Subfolder1
         File3.csv
        Arquivo4.json
         File5.csv
OutraPastaB
    File6.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 ADF
filesystem
    FolderA
         File1.csv
        File2.json
        Subfolder1
             File3.csv
            Arquivo4.json
             File5.csv
    Metadados
        FileListToCopy.txt		 File1.csv
Subfolder1/File3.csv
Subfolder1/File5.csv		 No conjunto de dados:
- Caminho da pasta: FolderA

Na origem da atividade de cópia:
- Caminho da lista de arquivos: 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.

Alguns exemplos de recursive e copyBehavior

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 Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5		 A Pasta1 de destino é criada com a mesma estrutura da origem:

Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5
true flattenHierarchy Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5		 A Pasta1 de destino é criada com a seguinte estrutura:

Folder1
    nome gerado automaticamente para o Arquivo1
    nome gerado automaticamente para File2
    nome gerado automaticamente para File3
    nome gerado automaticamente para File4
    nome gerado automaticamente para File5
true mergeFiles Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5		 A Pasta1 de destino é criada com a seguinte estrutura:

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

Folder1
    File1
    File2

A Subpasta1 com Arquivo3, Arquivo4 e Arquivo5 não é selecionada.
false flattenHierarchy Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5		 A Pasta1 de destino é criada com a seguinte estrutura:

Folder1
    nome gerado automaticamente para o Arquivo1
    nome gerado automaticamente para File2

A Subpasta1 com Arquivo3, Arquivo4 e Arquivo5 não é selecionada.
false mergeFiles Folder1
    File1
    File2
    Subfolder1
        File3
        File4
        File5		 A Pasta1 de destino é criada com a seguinte estrutura:

Folder1
    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

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

Tabela do Lakehouse do Microsoft Fabric na atividade Copy

Para usar o Conjunto de dados de tabelas do Lakehouse Microsoft Fabric como um conjunto de dados de origem ou coletor na atividade Copy, acesse as seções a seguir para obter as configurações detalhadas.

Tabela do Microsoft Fabric Lakehouse como um tipo de origem

Para copiar dados do Lakehouse do Microsoft Fabric usando o Conjunto de dados de tabelas do Lakehouse Microsoft Fabric, defina o tipo de propriedade na origem da atividade Copy como LakehouseTableSource. As propriedades a seguir têm suporte na seção de origem da atividade Copy:

Propriedade Descrição Obrigatório
tipo A propriedade type da origem da atividade Copy deve ser definida como LakehouseTableSource. Sim
timestampAsOf O carimbo de data/hora para consultar um instantâneo mais antigo. Não
versionAsOf A versão para consultar um instantâneo mais antigo. Não

Exemplo:

"activities":[
    {
        "name": "CopyFromLakehouseTable",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Microsoft Fabric Lakehouse Table input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "LakehouseTableSource",
                "timestampAsOf": "2023-09-23T00:00:00.000Z",
                "versionAsOf": 2
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Tabela do Microsoft Fabric Lakehouse como um tipo de coletor

Para copiar dados para o Lakehouse do Microsoft Fabric usando o Conjunto de dados de tabelas do Lakehouse Microsoft Fabric, defina a tipo de propriedade no coletor da atividade Copy como LakehouseTableSink. As seguintes propriedades têm suporte na seção coletor da atividade Copy:

Propriedade Descrição Obrigatório
tipo A propriedade type da origem da atividade Copy deve ser definida como LakehouseTableSink. Sim

Observação

Os dados são gravados na Tabela Lakehouse em V-Order por padrão. Para mais informações, acesse Otimização de tabela do Delta Lake e V-Order.

Para obter mais detalhes sobre a interoperabilidade do Delta Lake e os comportamentos compatíveis em pipelines, acesse a Interoperabilidade de formato de tabela delta lake.

Exemplo:

"activities":[
    {
        "name": "CopyToLakehouseTable",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Microsoft Fabric Lakehouse Table output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "LakehouseTableSink",
                "tableActionOption ": "Append"
            }
        }
    }
]

Mapeamento de tipo de dados para a tabela Microsoft Fabric Lakehouse

Ao copiar dados da tabela Microsoft Fabric Lakehouse, os mapeamentos a seguir são usados dos tipos de dados de tabela do Microsoft Fabric Lakehouse para tipos de dados provisórios usados pelo serviço internamente. Consulte Mapeamentos de tipo de dados e esquema para saber mais sobre como a atividade de cópia mapeia o tipo de dados e esquema de origem para o coletor.

Tipo de dados de tabela do Microsoft Fabric Lakehouse Tipo de dados provisório do serviço
cadeia String
long Int64
inteiro Int32
short Int16
byte SByte
derivar Solteiro
double Double
decimal Decimal
boolean booleano
binário Matriz de bytes
date Date
carimbo de data/hora DateTime

Ao copiar dados para a tabela Microsoft Fabric Lakehouse, os mapeamentos a seguir são usados de tipos de dados provisórios usados pelo serviço internamente para tipos de dados de coletor delta com suporte.

Tipo de dados provisório do serviço Tipo de coletor delta com suporte
booleano boolean
SByte byte
Byte short
Int16 short
UInt16 inteiro
Int32 inteiro
UInt32 long
Int64 long
UInt64 decimal (20,0)
Solteiro derivar
Double double
GUID cadeia
Date date
TimeSpan Sem suporte
DateTime carimbo de data/hora
DateTimeOffset carimbo de data/hora
String cadeia
Matriz de bytes binário
Decimal decimal

Suporte para tabela Delta Lake

Nas seções abaixo, você encontrará informações detalhadas sobre o suporte às tabelas do Delta Lake tanto para a fonte quanto para o destino.

Source

Há suporte para o Mapeamento de coluna Delta quando você aplica o leitor versão 2 ou o leitor versão 3 com columnMapping em readerFeatures na sua Tabela do Microsoft Fabric Lakehouse.

A funcionalidade de mapeamento de colunas da tabela Delta permite uma evolução de esquema mais flexível, garantindo que as alterações na estrutura da tabela não interrompam os fluxos de trabalho de dados. Com o mapeamento de colunas, você pode ler dados de uma tabela do Delta Lake existente com delta.columnMapping.mode definido como name ou id.

Há suporte para os Vetores de exclusão quando você aplica o leitor versão 3 com deletionVectors em readerFeatures na sua Tabela do Microsoft Fabric Lakehouse. As linhas que são excluídas suavemente são marcadas em arquivos de vetor de exclusão e ignoradas ao ler a tabela do Delta Lake.

Há suporte para o Feed de Dados de Alteração .

Coletor

Há suporte para mapeamento de coluna delta. Essa funcionalidade permite uma evolução de esquema mais flexível, garantindo que as alterações na estrutura da tabela não interrompam os fluxos de trabalho de dados. Com o mapeamento de coluna, você pode:

  • Gravar dados em uma tabela delta lake existente com delta.columnMapping.mode definido como name.
  • Criar automaticamente uma tabela com delta.columnMapping.mode definido como name quando a tabela de destino não existir e as colunas de origem incluírem caracteres especiais e espaços em branco.
  • Criar automaticamente uma tabela com delta.columnMapping.mode definido como name quando a ação da tabela for substituir e as colunas do conjunto de dados de origem incluírem caracteres especiais e espaços em branco.

Há suporte para vetores de exclusão .

Há suporte para o Feed de Dados de Alteração .

Propriedades do fluxo de dados de mapeamento

Ao transformar dados no fluxo de dados de mapeamento, é possível ler e gravar em arquivos ou tabelas no Lakehouse do Microsoft Fabric. Consulte as seções correspondentes para obter detalhes.

Para obter mais informações, confira transformação de origem e transformação do coletor nos fluxos de dados de mapeamento.

Arquivos do Lakehouse do Microsoft Fabric no fluxo de dados de mapeamento

Para usar o Conjunto de dados de arquivos do Lakehouse do Microsoft Fabric como um conjunto de dados de origem ou coletor no fluxo de dados de mapeamento, acesse as seções a seguir para obter as configurações detalhadas.

Arquivos do Microsoft Fabric Lakehouse como um tipo de origem do coletor

O conector do Lakehouse do Microsoft Fabric dá suporte aos formatos de arquivo a seguir. Confira cada artigo para obter configurações baseadas em formato.

Para usar o conector baseado em arquivo do Fabric Lakehouse no tipo de conjunto de dados embutido, você precisa escolher o tipo de conjunto de dados embutido correto para seus dados. Você pode usar DelimitedText, Avro, JSON, ORC ou Parquet dependendo do formato de dados.

Tabela do Lakehouse do Microsoft Fabric no fluxo de dados de mapeamento

Para usar o Conjunto de dados de tabelas do Lakehouse do Microsoft Fabric como um conjunto de dados de origem ou coletor no fluxo de dados de mapeamento, acesse as seções a seguir para obter as configurações detalhadas.

Tabela do Microsoft Fabric Lakehouse como um tipo de origem

Não há propriedades configuráveis nas opções de origem.

Observação

No momento, o suporte à CDA para a origem da tabela do Lakehouse não está disponível.

Tabela do Microsoft Fabric Lakehouse como um tipo de coletor

As seguintes propriedades têm suporte na seção de coletor dos Fluxos de Dados de Mapeamento:

Nome Descrição Obrigatório Valores permitidos Propriedade do script do fluxo de dados
Método update Ao selecionar "Permitir inserção" sozinho ou gravar em uma nova tabela delta, o destino recebe todas as linhas de entrada, independentemente das políticas de linha definidas. Se seus dados contiverem linhas de outras políticas de linha, elas precisarão ser excluídas usando uma transformação de filtro anterior.

Quando todos os métodos de atualização são selecionados, uma mesclagem é executada, na qual as linhas são inseridas/excluídas/upserted/atualizadas de acordo com o conjunto de políticas de linha usando uma transformação de Alterar Linha.		 sim true ou false insertable
deletable
upsertable
Pode ser atualizado
Gravação otimizada Obtenha uma taxa de transferência mais alta para a operação de gravação por meio da otimização do modo aleatório interno em executores do Spark. Como resultado, é possível notar menos partições e arquivos de tamanho maior não true ou false optimizedWrite: true
Compactar automaticamente Após a conclusão de qualquer operação de gravação, o Spark executará automaticamente o comando OPTIMIZE para reorganizar os dados, resultando em mais partições, se necessário, para melhor leitura do desempenho no futuro não true ou false autoCompact: true
Esquema de mesclagem A opção Mesclar esquema permite a evolução do esquema, ou seja, todas as colunas presentes no fluxo de entrada atual, mas não na tabela Delta de destino, são automaticamente adicionadas ao seu esquema. Essa opção tem suporte em todos os métodos de atualização. não true ou false mergeSchema: true

Exemplo: coletor de tabela do Microsoft Fabric Lakehouse

sink(allowSchemaDrift: true, 
    validateSchema: false, 
    input( 
        CustomerID as string,
        NameStyle as string, 
        Title as string, 
        FirstName as string, 
        MiddleName as string,
        LastName as string, 
        Suffix as string, 
        CompanyName as string,
        SalesPerson as string, 
        EmailAddress as string, 
        Phone as string, 
        PasswordHash as string, 
        PasswordSalt as string, 
        rowguid as string, 
        ModifiedDate as string 
    ), 
    deletable:false, 
    insertable:true, 
    updateable:false, 
    upsertable:false, 
    optimizedWrite: true, 
    mergeSchema: true, 
    autoCompact: true, 
    skipDuplicateMapInputs: true, 
    skipDuplicateMapOutputs: true) ~> CustomerTable

Para o conector baseado em tabela do Fabric Lakehouse no tipo de conjunto de dados embutido, você só precisa usar o Delta como tipo de conjunto de dados. Isso permitirá que você leia e escreva dados de tabelas do Fabric Lakehouse.

Pesquisar propriedades de atividade

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

Conteúdo relacionado

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

  • Last updated on