Copiar e transformar dados no Microsoft Fabric Warehouse usando o Azure Data Factory ou o Azure Synapse Analytics

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como usar a Atividade de Cópia para copiar dados de e para o Microsoft Fabric Warehouse. Para saber mais, leia o artigo introdutório do Azure Data Factory ou do Azure Synapse Analytics.

Funcionalidades com suporte

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

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

Introdução

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

• Ferramenta Copiar Dados
• Portal do Azure
• SDK do .NET
• SDK do Python
• PowerShell do Azure
• REST API
• Modelo do Azure Resource Manager

Propriedades do serviço vinculado

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

• Autenticação de entidade de serviço
• Autenticação de identidade gerenciada atribuída pelo sistema
• Autenticação de identidade gerenciada atribuída pelo usuário

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:

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": "MicrosoftFabricWarehouseLinkedService",
    "properties": {
        "type": "Warehouse",
        "typeProperties": {
            "endpoint": "<Microsoft Fabric Warehouse server endpoint>",
            "workspaceId": "<Microsoft Fabric workspace ID>",
            "artifactId": "<Microsoft Fabric Warehouse 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 Warehouse, que é semelhante ao uso de sua própria entidade de serviço. Ela permite que esse recurso designado acesse e copie dados de ou para o Microsoft Fabric Warehouse. 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 Warehouse:

Example:

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

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 Warehouse, que permite acessar e copiar dados de ou para o Microsoft Fabric Warehouse. 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 Warehouse:

Example:

{
    "name": "MicrosoftFabricWarehouseLinkedService",
    "properties": {
        "type": "Warehouse",
        "typeProperties": {
            "endpoint": "<Microsoft Fabric Warehouse server endpoint>",            
            "workspaceId": "<Microsoft Fabric workspace ID>",
            "artifactId": "<Microsoft Fabric Warehouse 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.

   

2. No painel Adicionar pessoas, insira sua entidade de serviço/identidade gerenciada atribuída pelo sistema/nome da 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.

   

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

Criar um serviço vinculado do Microsoft Fabric Warehouse usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado do Microsoft Fabric Warehouse 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:

   • Fábrica de dados do Azure
   • Azure Synapse

   

2. Pesquise por Warehouse e selecione o conector.

   

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

   

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.

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

Exemplo de propriedades do conjunto de dados

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

Propriedades da atividade de cópia

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. Esta seção fornece uma lista de propriedades compatíveis com a origem e o coletor do Microsoft Fabric Warehouse.

Microsoft Fabric Warehouse como a origem

Para copiar dados do Microsoft Fabric Warehouse, defina a propriedade type na origem da Atividade de Cópia como WarehouseSource. As seguintes propriedades são suportadas na seção source da atividade de cópia:

Exemplo: usar consulta SQL

"activities":[
    {
        "name": "CopyFromMicrosoftFabricWarehouse",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Microsoft Fabric Warehouse input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "WarehouseSource",
                "sqlReaderQuery": "SELECT * FROM MyTable"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Exemplo: usar procedimento armazenado

"activities":[
    {
        "name": "CopyFromMicrosoftFabricWarehouse",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Microsoft Fabric Warehouse input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "WarehouseSource",
                "sqlReaderStoredProcedureName": "CopyTestSrcStoredProcedureWithParameters",
                "storedProcedureParameters": {
                    "stringData": { "value": "str3" },
                    "identifier": { "value": "$$Text.Format('{0:yyyy}', <datetime parameter>)", "type": "Int"}
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Procedimento armazenado de exemplo:

CREATE PROCEDURE CopyTestSrcStoredProcedureWithParameters
(
    @stringData varchar(20),
    @identifier int
)
AS
SET NOCOUNT ON;
BEGIN
    select *
    from dbo.UnitTestSrcTable
    where dbo.UnitTestSrcTable.stringData != stringData
    and dbo.UnitTestSrcTable.identifier != identifier
END
GO

Microsoft Fabric Warehouse como um tipo de coletor

Os pipelines do Azure Data Factory e do Synapse dão suporte ao Uso da instrução COPY para carregar dados no Microsoft Fabric Warehouse.

Para copiar dados para o Microsoft Fabric Warehouse, defina o tipo de coletor em Atividade de Cópia para WarehouseSink. As seguintes propriedades são suportadas na seção Copy Activity sink:

Exemplo: coletor do Microsoft Fabric Warehouse

"activities":[
    {
        "name": "CopyToMicrosoftFabricWarehouse",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Microsoft Fabric Warehouse output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "WarehouseSink",
                "allowCopyCommand": true,
                "tableOption": "autoCreate",
                "disableMetricsCollection": false
            }
        }
    }
]

Cópia paralela do Microsoft Fabric Warehouse

O conector do Microsoft Fabric Warehouse na atividade de cópia fornece particionamento de dados interno para copiar dados em paralelo. Você pode encontrar opções de particionamento de dados na guia Origem da atividade de cópia.

Quando você habilita a cópia particionada, a atividade de cópia executa consultas paralelas em sua fonte do Microsoft Fabric Warehouse para carregar dados por partições. O grau paralelo é controlado pela configuração do parallelCopies na atividade de cópia. Por exemplo, se você definir parallelCopies como quatro, o serviço gerará e executará simultaneamente quatro consultas com base na opção de partição e nas configurações especificadas, e cada consulta recuperará uma parte dos dados do Microsoft Fabric Warehouse.

Você é sugerido para habilitar a cópia paralela com o particionamento de dados, especialmente quando você carrega uma grande quantidade de dados do Microsoft Fabric Warehouse. Veja a seguir as configurações sugeridas para cenários diferentes. Ao copiar dados para o armazenamento de dados baseado em arquivo, recomendamos gravá-los em uma pasta como vários arquivos (apenas especifique o nome da pasta) para ter um desempenho melhor do que gravar em um arquivo.

Melhores práticas para carregar dados com a opção de partição:

• Escolha a coluna distinta como coluna de partição (como chave primária ou chave exclusiva) para evitar a distorção de dados.
• Se você usa o Azure Integration Runtime para copiar dados, pode definir "DIUs (unidades de integração de dados)" maiores (>4) para utilizar mais recursos de computação. Verifique os cenários aplicáveis.
• O "grau de paralelismo de cópia" controla os números de partições. Às vezes, definir um número muito grande afeta o desempenho; é recomendável definir esse número como (DIU ou número de nós de IR auto-hospedados) * (2 a 4).
• Observe que o Microsoft Fabric Warehouse pode executar no máximo 32 consultas por momento, definir "Grau de paralelismo de cópia" muito grande pode causar um problema de limitação do Warehouse.

Exemplo: consulta com a partição do intervalo dinâmico

"source": {
    "type": "WarehouseSource",
    "query": "SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>",
    "partitionOption": "DynamicRange",
    "partitionSettings": {
        "partitionColumnName": "<partition_column_name>",
        "partitionUpperBound": "<upper_value_of_partition_column (optional) to decide the partition stride, not as data filter>",
        "partitionLowerBound": "<lower_value_of_partition_column (optional) to decide the partition stride, not as data filter>"
    }
}

Usar a instrução COPY para carregar dados no Microsoft Fabric Warehouse

Usar a instrução COPY é uma maneira simples e flexível de carregar dados no Microsoft Fabric Warehouse com alta taxa de transferência. Para saber mais detalhes, confira Dados de carregamento em massa usando a instrução COPY

• Se os dados de origem estiverem no Blob do Azure ou no Azure Data Lake Storage Gen2 e o formato for compatível com a instrução COPY, você poderá usar a atividade de cópia para invocar diretamente a instrução COPY para permitir que o Microsoft Fabric Warehouse efetue pull dos dados da origem. Para obter mais detalhes, confira Cópia direta usando a instrução COPY.
• Se o armazenamento e o formato de dados de origem não forem originalmente suportados pela instrução COPY, use o recurso Cópia preparada usando a instrução COPY. O recurso de cópia em etapas também proporciona melhor taxa de transferência. Ele converte automaticamente os dados em formato compatível com a instrução COPY, armazena os dados no Armazenamento de Blobs do Azure e, em seguida, chama a instrução COPY para carregar dados no Microsoft Fabric Warehouse.

Cópia direta usando a instrução COPY

A instrução COPY do Microsoft Fabric Warehouse dá suporte diretamente ao Blob do Azure, ao Azure Data Lake Storage Gen1 e ao Azure Data Lake Storage Gen2. Se os dados de origem atenderem aos critérios descritos nesta seção, use a instrução COPY para copiar diretamente do armazenamento de dados de origem para o Microsoft Fabric Warehouse. Caso contrário, use Cópia preparada usando a instrução COPY. O serviço verifica as configurações e falha na execução da atividade de cópia se os critérios não forem atendidos.

• O serviço vinculado de origem e o formato acompanham os seguintes tipos e métodos de autenticação:

  Tipo de armazenamento de dados de origem compatíveis	Formato compatível	Tipos de autenticação de origem compatíveis
  Blob do Azure	Texto delimitado	Autenticação de chave de conta, autenticação de assinatura de acesso compartilhado
  	Parquete	Autenticação de chave de conta, autenticação de assinatura de acesso compartilhado
  Azure Data Lake Storage Gen2	Texto delimitado Parquete	Autenticação de chave de conta, autenticação de assinatura de acesso compartilhado

• As configurações de formato têm as seguintes particularidades:

  • Para Parquet: compression pode ser sem compactação, Snappy ou GZip.
  • Para Texto delimitado:
    • rowDelimiter é definido explicitamente como caractere único ou "\r\n", o valor padrão não é compatível.
    • nullValue é deixado como padrão ou definido como cadeia de caracteres vazia ("").
    • encodingName é deixado como padrão ou definido como utf-8 ou utf-16.
    • escapeChar precisa ser o mesmo que quoteChar e não está vazio.
    • skipLineCount é deixado como padrão ou definido como 0.
    • compression pode ser nenhuma compactação ou GZip.

• Se sua fonte for uma pasta, recursive na atividade de cópia precisará ser definida como true e wildcardFilename precisará ser * ou *.*.

• wildcardFolderPath , wildcardFilename (além de *ou *.*), modifiedDateTimeStart, modifiedDateTimeEnd, prefix, enablePartitionDiscovery e additionalColumns não são especificados.

As seguintes configurações da instrução COPY são compatíveis em allowCopyCommand na atividade de cópia:

"activities":[
    {
        "name": "CopyFromAzureBlobToMicrosoftFabricWarehouseViaCOPY",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "ParquetDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "MicrosoftFabricWarehouseDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ParquetSource",
                "storeSettings":{
                    "type": "AzureBlobStorageReadSettings",
                    "recursive": true
                }
            },
            "sink": {
                "type": "WarehouseSink",
                "allowCopyCommand": true,
                "copyCommandSettings": {
                    "defaultValues": [
                        {
                            "columnName": "col_string",
                            "defaultValue": "DefaultStringValue"
                        }
                    ],
                    "additionalOptions": {
                        "MAXERRORS": "10000",
                        "DATEFORMAT": "'ymd'"
                    }
                }
            },
            "enableSkipIncompatibleRow": true
        }
    }
]

Cópia preparada usando a instrução COPY

Quando os dados de origem não são nativamente compatíveis com a instrução COPY, habilite a cópia de dados por meio de uma instância provisória do Blob do Azure ou do Azure Data Lake Storage Gen2 (não pode ser o Armazenamento Premium do Azure). Nesse caso, o serviço converte automaticamente os dados para atender aos requisitos de formato de dados da instrução COPY. Em seguida, ele invoca a instrução COPY para carregar dados no Microsoft Fabric Warehouse. Por fim, ele limpa os dados temporários do armazenamento. Confira Cópia de preparo para obter detalhes sobre a cópia de dados por meio do preparo.

Para usar esse recurso, crie um serviço vinculado do Armazenamento de Blobs do Azure ou um serviço vinculado do Azure Data Lake Storage Gen2 com Assinatura de acesso compartilhado, autenticação anônima ou de chave de conta que se refere à conta de armazenamento do Azure como armazenamento provisório.

"activities":[
    {
        "name": "CopyFromSQLServerToMicrosoftFabricWarehouseViaCOPYstatement",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "SQLServerDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "MicrosoftFabricWarehouseDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlSource",
            },
            "sink": {
                "type": "WarehouseSink",
                "allowCopyCommand": true
            },
            "stagingSettings": {
                "linkedServiceName": {
                    "referenceName": "MyStagingStorage",
                    "type": "LinkedServiceReference"
                }
            }
        }
    }
]

Propriedades do fluxo de dados de mapeamento

Ao transformar dados no fluxo de dados de mapeamento, é possível ler e gravar em tabelas do Warehouse do Microsoft Fabric. Para obter mais informações, confira transformação de origem e transformação do coletor nos fluxos de dados de mapeamento.

Microsoft Fabric Warehouse como a origem

As configurações específicas do Warehouse do Microsoft Fabric estão disponíveis na guia Opções de Origem da transformação de origem.

Warehouse do Microsoft Fabric como o coletor

As configurações específicas do Warehouse do Microsoft Fabric estão disponíveis na guia Configurações da transformação do coletor.

Usando o Fabric Warehouse como coletor com o preparo habilitado

Se o local de armazenamento de preparo tiver um firewall habilitado, poderá ocorrer problemas de acesso.

Soluções alternativas

• Regiões diferentes:
  Se a capacidade do Fabric e o armazenamento de preparo estiverem em regiões diferentes, verifique se os endereços IP necessários são permitidos no firewall do local de armazenamento para habilitar a conectividade.

• Mesma região:
  Se a capacidade do Fabric e o armazenamento temporário estiverem na mesma região e os problemas de acesso persistirem, escolha uma alternativa de armazenamento temporário em uma região diferente da capacidade do Fabric.

Tratamento da linha de erros

Por padrão, uma execução de fluxo de dados falhará no primeiro erro obtido. Você pode optar por Continuar em caso de erro, o que permite que o fluxo de dados seja concluído mesmo que linhas individuais apresentem erros. O serviço fornece opções diferentes para você identificar essas linhas de erro.

Commit da transação: escolha se os dados serão gravados em uma única transação ou em lotes. Uma única transação proporciona um desempenho melhor, e os dados gravados não ficarão visíveis para outras pessoas até que a transação seja concluída. As transações em lote têm um desempenho pior, mas podem funcionar para grandes conjuntos de dados.

Saída de dados rejeitados: se ativado, você poderá enviar as linhas de erro para um arquivo CSV no Armazenamento de Blobs do Azure ou em uma conta do Azure Data Lake Storage Gen2 à sua escolha. Isso gravará as linhas de erro com três colunas adicionais: a operação SQL como INSERT ou UPDATE, o código de erro do fluxo de dados e a mensagem de erro na linha.

Relatar sucesso em caso de erro: se ativado, o fluxo de dados será marcado como bem-sucedido mesmo que sejam encontradas linhas de erro.

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

Mapeamento de tipo de dados para o Microsoft Fabric Warehouse

Quando você copia dados do Microsoft Fabric Warehouse, os mapeamentos a seguir são usados dos tipos de dados do Microsoft Fabric Warehouse para tipos de dados provisórios dentro do serviço internamente. Para saber mais sobre como a atividade de cópia mapeia o tipo de dados e esquema de origem para o coletor, consulte Mapeamentos de tipo de dados e esquema.

Próximas etapas

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.