Copiar e transformar dados no Azure Synapse Analytics usando os pipelines do Azure Data Factory ou do Synapse

  • Artigo

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 usar a Atividade de Cópia nos pipelines do Azure Data Factory ou do Synapse para copiar dados de e para o Azure Synapse Analytics e usar o Fluxo de Dados para transformar dados no Azure Data Lake Storage Gen2. Para saber mais sobre o Azure Data Factory, leia as artigo introdutório.

Funcionalidades com suporte

Este conector do Azure Synapse Analytics é compatível com as seguintes funcionalidades:

Funcionalidades com suporte IR Ponto de extremidade privado gerenciado
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 ✓
Atividade de Script 6/6 ✓
Stored procedure activity (Atividade de procedimento armazenado) 6/6 ✓

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

Para a atividade de cópia, este conector do Azure Synapse Analytics é compatível com estas funções:

  • Copie dados usando a autenticação SQL e a autenticação de token do aplicativo do Microsoft Entra com uma entidade de serviço ou identidades gerenciadas recursos do Azure.
  • Como uma fonte, recupere dados usando uma consulta SQL ou procedimento armazenado. Você também pode optar por fazer a cópia paralela de uma fonte do Azure Synapse Analytics. Confira os detalhes na seção Cópia paralela do Azure Synapse Analytics.
  • Como um coletor, carregue dados usando a instrução COPY ou PolyBase ou Bulk Insert. Recomendamos usar a instrução COPY ou PolyBase para ter um melhor desempenho de cópia. O conector também dá suporte à criação automática da tabela de destino com DISTRIBUTION = ROUND_ROBIN se não houver uma baseada no esquema de origem.

Importante

Se você copiar dados usando o Azure Integration Runtime, configure uma regra de firewall no nível do servidor para que os serviços do Azure possam acessar o SQL Server lógico. Se você copiar dados usando um runtime de integração auto-hospedada, configure o firewall para permitir o intervalo de IP apropriado. Esse intervalo inclui o IP do computador usado para se conectar ao Azure Synapse Analytics.

Introdução

Dica

Para ter o melhor desempenho, use o PolyBase ou a instrução COPY para carregar dados no Azure Synapse Analytics. As seções Usar o PolyBase para carregar dados no Azure Synapse Analytics e Usar a instrução COPY para carregar dados no Azure Synapse Analytics trazem detalhes. Para ver um passo a passo com um caso de uso, confira Carregar 1 TB no Azure Synapse Analytics em menos de 15 minutos com o Azure Data Factory.

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 do Azure Synapse Analytics usando a interface do usuário

Siga as etapas abaixo para criar um serviço vinculado do Azure Synapse Analytics na interface de usuário do portal do Azure.

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

  2. Pesquise Synapse e selecione o conector do Azure Synapse Analytics.

    Screenshot of the Azure Synapse Analytics connector.

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

    Screenshot of configuration for an Azure Synapse Analytics linked service.

Detalhes da configuração do conector

As seções a seguir fornecem detalhes sobre propriedades que definem entidades de pipeline do Data Factory e do Synapse específicas para um conector do Azure Synapse Analytics.

Propriedades do serviço vinculado

Estas propriedades genéricas são compatíveis com um serviço vinculado do Azure Synapse Analytics:

Propriedade Descrição Obrigatório
type A propriedade type deve ser definida como AzureSqlDW. Sim
connectionString Especifique as informações necessárias para conectar-se à instância do Azure Synapse Analytics para a propriedade connectionString.
Marque esse campo como SecureString para armazená-lo com segurança. Você também pode colocar uma senha/chave da entidade de serviço no Azure Key Vault e se sua autenticação do SQL efetua pull da configuração da password da cadeia de conexão. Veja o exemplo de JSON abaixo da tabela e o artigo Armazenar credenciais no Azure Key Vault que fornece mais detalhes.		 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, o data factory ou o ambiente de nuvem do pipeline do Synapse é usado.		 Não
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 localizado em uma rede privada). Se não for especificado, ele usa o Integration Runtime padrão do Azure. Não

Para diferentes tipos de autenticação, consulte as seguintes seções sobre propriedades específicas, pré-requisitos e amostras de JSON, respectivamente:

Dica

Ao criar um serviço vinculado para um pool de SQL sem servidor no Azure Synapse por meio do portal do Azure:

  1. Para o Método de Seleção de Conta, escolha Inserir manualmente.
  2. Cole o nome de domínio totalmente qualificado do ponto de extremidade sem servidor. Você pode encontrar isso na página de visão geral do portal do Azure do seu workspace do Synapse, nas propriedades em ponto de extremidade SQL sem servidor. Por exemplo, myserver-ondemand.sql-azuresynapse.net.
  3. Para o Nome do banco de dados, forneça o nome do banco de dados do pool de SQL sem servidor.

Dica

Se ocorrer erro com código de erro como "UserErrorFailedToConnectToSqlServer" e mensagem como "O limite da sessão para o banco de dados é XXX e foi atingido.", adicione Pooling=false à cadeia de conexão e tente novamente.

Autenticação SQL

Para usar o tipo de autenticação SQL, especifique as propriedades genéricas descritas na seção anterior.

Exemplo de serviço vinculado que usa autenticação SQL

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": "Server=tcp:<servername>.database.windows.net,1433;Database=<databasename>;User ID=<username>@<servername>;Password=<password>;Trusted_Connection=False;Encrypt=True;Connection Timeout=30"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Senha no Azure Key Vault:

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": "Server=tcp:<servername>.database.windows.net,1433;Database=<databasename>;User ID=<username>@<servername>;Trusted_Connection=False;Encrypt=True;Connection Timeout=30",
            "password": {
                "type": "AzureKeyVaultSecret",
                "store": {
                    "referenceName": "<Azure Key Vault linked service name>",
                    "type": "LinkedServiceReference"
                },
                "secretName": "<secretName>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Autenticação de entidade de serviço

Para usar a autenticação de entidade de serviço, além das propriedades genéricas descritas na seção anterior, especifique 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 um SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault. Sim
locatário Especifique as informações de locatário (domínio nome ou ID do Locatário) em que o aplicativo reside. É possível recuperá-lo focalizando o canto superior direito do portal do Azure. Yes

Você também precisa seguir as etapas abaixo:

  1. Crie um aplicativo do Microsoft Entra no portal do Azure. Anote o nome do aplicativo e os seguintes valores que definem o serviço vinculado:

    • ID do aplicativo
    • Chave do aplicativo
    • ID do locatário

  2. Provisione um administrador do Microsoft Entra para seu servidor no portal do Azure, caso ainda não tenha feito isso. O administrador do Microsoft Entra pode ser um usuário do Microsoft Entra ou um grupo do Microsoft Entra. Se você conceder uma função de administrador ao grupo com a identidade gerenciada, ignore as etapas 3 e 4. O administrador terá acesso completo ao banco de dados.

  3. Crie usuários de banco de dados contidos para o diretor de serviços. Conecte-se ao data warehouse de ou para o qual você deseja copiar dados usando ferramentas como SSMS, com uma identidade do Microsoft Entra que tenha pelo menos a permissão ALTER ANY USER. Execute o seguinte T-SQL:

    CREATE USER [your_application_name] FROM EXTERNAL PROVIDER;

  4. Conceda ao principal de serviço as permissões necessárias, como faria normalmente para usuários do SQL ou outros. Execute o código a seguir ou veja mais opções aqui. Se você quiser usar o PolyBase para carregar os dados, aprenda a permissão de banco de dados necessária.

    EXEC sp_addrolemember db_owner, [your application name];

  5. Configure um serviço vinculado do Azure Synapse Analytics em um espaço de trabalho do Azure Data Factory ou do Synapse.

Exemplo de serviço vinculado que usa autenticação principal de serviço

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": "Server=tcp:<servername>.database.windows.net,1433;Database=<databasename>;Connection Timeout=30",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Identidades gerenciadas atribuídas pelo sistema para autenticação de recursos do Azure

Um data factory ou workspace do Synapse pode ser associado a uma identidade gerenciada atribuída pelo sistema para recursos do Azure, que representa o recurso. Você pode usar essa identidade gerenciada para a autenticação do Azure Synapse Analytics. O recurso designado pode acessar e copiar dados de ou para seu data warehouse usando essa identidade.

Para usar a autenticação de identidade gerenciada atribuída pelo sistema, especifique as propriedades genéricas descritas na seção anterior e siga estas etapas.

  1. Provisione um administrador do Microsoft Entra para seu servidor no portal do Azure, caso ainda não tenha feito isso. O administrador do Microsoft Entra pode ser um usuário do Microsoft Entra ou um grupo do Microsoft Entra. Se você conceder uma função de administrador ao grupo com a identidade gerenciada atribuída pelo sistema, ignore as etapas 3 e 4. O administrador terá acesso completo ao banco de dados.

  2. Crie usuários de banco de dados contidos para a identidade gerenciada atribuída pelo sistema. Conecte-se ao data warehouse de ou para o qual você deseja copiar dados usando ferramentas como SSMS, com uma identidade do Microsoft Entra que tenha pelo menos a permissão ALTER ANY USER. Execute o seguinte T-SQL.

    CREATE USER [your_resource_name] FROM EXTERNAL PROVIDER;

  3. Conceda à identidade gerenciada atribuída pelo sistema as permissões necessárias como você faria normalmente para usuários de SQL e outros. Execute o código a seguir ou veja mais opções aqui. Se você quiser usar o PolyBase para carregar os dados, aprenda a permissão de banco de dados necessária.

    EXEC sp_addrolemember db_owner, [your_resource_name];

  4. Configurar um serviço vinculado do Azure Synapse Analytics.

Exemplo:

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": "Server=tcp:<servername>.database.windows.net,1433;Database=<databasename>;Connection Timeout=30"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Autenticação de identidade gerenciada atribuída pelo usuário

Um data factory ou workspace do Synapse pode ser associado a uma identidades gerenciadas atribuídas pelo usuário, que representa o recurso. Você pode usar essa identidade gerenciada para a autenticação do Azure Synapse Analytics. O recurso designado pode acessar e copiar dados de ou para seu data warehouse usando essa identidade.

Para usar a autenticação de identidade gerenciada atribuída pelo usuário, além das propriedades genéricas descritas na seção anterior, especifique as seguintes propriedades:

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

Você também precisa seguir as etapas abaixo:

  1. Provisione um administrador do Microsoft Entra para seu servidor no portal do Azure, caso ainda não tenha feito isso. O administrador do Microsoft Entra pode ser um usuário do Microsoft Entra ou um grupo do Microsoft Entra. Se você conceder uma função de administrador ao grupo com a identidade gerenciada atribuída pelo usuário, ignore a etapa 3. O administrador terá acesso completo ao banco de dados.

  2. Crie usuários de banco de dados contidos para a identidade gerenciada atribuída pelo usuário. Conecte-se ao data warehouse de ou para o qual você deseja copiar dados usando ferramentas como SSMS, com uma identidade do Microsoft Entra que tenha pelo menos a permissão ALTER ANY USER. Execute o seguinte T-SQL.

    CREATE USER [your_resource_name] FROM EXTERNAL PROVIDER;

  3. crie uma ou várias identidades gerenciadas atribuídas pelo usuário e conceda à identidade gerenciada atribuída pelo usuário as permissões necessárias como você normalmente faz para SQL usuários e outros. Execute o código a seguir ou veja mais opções aqui. Se você quiser usar o PolyBase para carregar os dados, aprenda a permissão de banco de dados necessária.

    EXEC sp_addrolemember db_owner, [your_resource_name];

  4. 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.

  5. Configurar um serviço vinculado do Azure Synapse Analytics.

Exemplo:

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": "Server=tcp:<servername>.database.windows.net,1433;Database=<databasename>;Connection Timeout=30",
            "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.

As seguintes propriedades são compatíveis com um conjunto de dados do Azure Synapse Analytics:

Propriedade Descrição Obrigatório
type A propriedade tipo do conjunto de dados deve ser definida como AzureSqlDWTable. Sim
esquema Nome do esquema. Não para fonte, Sim para o coletor
tabela Nome da tabela/exibição. Não para fonte, Sim para o coletor
tableName Nome da tabela/exibição com esquema. Essa propriedade é compatível com versões anteriores. Para uma nova carga de trabalho, use schema e table. Não para fonte, Sim para o coletor

Exemplo de propriedades do conjunto de dados

{
    "name": "AzureSQLDWDataset",
    "properties":
    {
        "type": "AzureSqlDWTable",
        "linkedServiceName": {
            "referenceName": "<Azure Synapse Analytics 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 das seções e propriedades disponíveis para definir atividades, confia o artigo Pipelines. Esta seção fornece uma lista de propriedades compatíveis com a origem e o coletor do Azure Synapse Analytics.

Azure Synapse Analytics como a origem

Dica

Para carregar dados do Azure Synapse Analytics com eficiência usando o particionamento de dados, saiba mais na seção Cópia paralela do Azure Synapse Analytics.

Para copiar dados do Azure Synapse Analytics, defina a propriedade type na origem da Atividade de Cópia para SqlDWSource. As seguintes propriedades são suportadas na seção source da atividade de cópia:

Propriedade Descrição Obrigatório
type A propriedade tipo da origem da Atividade de Cópia deve ser configurada para SqlDWSource. Sim
sqlReaderQuery Utiliza a consulta SQL personalizada para ler os dados. Exemplo: select * from MyTable. Não
sqlReaderStoredProcedureName O nome do procedimento armazenado que lê dados da tabela de origem. A última instrução SQL deve ser uma instrução SELECT no procedimento armazenado. Não
storedProcedureParameters Parâmetros para o procedimento armazenado.
Valores permitidos são pares de nome ou valor. Nomes e uso de maiúsculas e minúsculas de parâmetros devem corresponder aos nomes e o uso de maiúsculas e minúsculas dos parâmetros do procedimento armazenado.		 Não
isolationLevel Especifica o comportamento de bloqueio de transação para a origem do SQL. Os valores permitidos são: ReadCommitted, ReadUncommitted, RepeatableRead, Serializable, Snapshot. Se não for especificado, o nível de isolamento padrão do banco de dados será usado. Para obter mais informações, confira system.data.isolationlevel. Não
partitionOptions Especifica as opções de particionamento de dados usadas para carregar dados do Azure Synapse Analytics.
Os valores permitidos são: None (padrão), PhysicalPartitionsOfTable e DynamicRange.
Quando uma opção de partição está habilitada (ou seja, não None), o grau de paralelismo para carregar dados simultaneamente do Azure Synapse Analytics é controlado pela configuração parallelCopies na atividade de cópia.		 Não
partitionSettings Especifique o grupo de configurações para o particionamento de dados.
Aplicar quando a opção de partição não for None.		 No
Em partitionSettings:
partitionColumnName Especifique o nome da coluna de origem no tipo inteiro ou data/datetime (int, smallint, bigint, date, smalldatetime, datetime, datetime2 ou datetimeoffset) que será usado pelo particionamento de intervalo para cópia paralela. Se não for especificado, o índice ou a chave primária da tabela será detectada automaticamente e usada como coluna de partição.
Aplicar quando a opção de partição for DynamicRange. Se você usar uma consulta para recuperar os dados de origem, conecte ?AdfDynamicRangePartitionCondition na cláusula WHERE. Para ver um exemplo, confira a seção Cópia paralela do banco de dados SQL.		 Não
partitionUpperBound O valor máximo da coluna de partição para divisão do intervalo de partição. Esse valor é usado para decidir o stride da partição, e não para filtrar as linhas na tabela. Todas as linhas da tabela ou do resultado da consulta serão particionadas e copiadas. Se não for especificado, a atividade de cópia detectará o valor automaticamente.
Aplicar quando a opção de partição for DynamicRange. Para ver um exemplo, confira a seção Cópia paralela do banco de dados SQL.		 Não
partitionLowerBound O valor mínimo da coluna de partição para divisão do intervalo de partição. Esse valor é usado para decidir o stride da partição, e não para filtrar as linhas na tabela. Todas as linhas da tabela ou do resultado da consulta serão particionadas e copiadas. Se não for especificado, a atividade de cópia detectará o valor automaticamente.
Aplicar quando a opção de partição for DynamicRange. Para ver um exemplo, confira a seção Cópia paralela do banco de dados SQL.		 Não

Observe o seguinte aspecto:

  • ao usar um procedimento armazenado na origem para recuperar dados, observe que, se o procedimento armazenado for projetado para retornar um esquema diferente quando um valor de parâmetro diferente for passado, você poderá ter uma falha ou um resultado inesperado ao importar o esquema da interface do usuário ou ao copiar dados para o banco de dados SQL com a criação automática de tabela.

Exemplo: usando a consulta SQL

"activities":[
    {
        "name": "CopyFromAzureSQLDW",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure Synapse Analytics input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlDWSource",
                "sqlReaderQuery": "SELECT * FROM MyTable"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Exemplo: usando o procedimento armazenado

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

Exemplo de procedimento armazenado:

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

Azure Synapse Analytics como coletor

Os pipelines do Azure Data Factory e do Synapse dão suporte a três maneiras de carregar dados no Azure Synapse Analytics.

A maneira mais rápida e escalonável de carregar dados é por meio da instrução COPY ou PolyBase.

Para copiar dados para o Azure Synapse Analytics, defina o tipo de coletor em Atividade de Cópia como SqlDWSink. As seguintes propriedades são suportadas na seção Copy Activity sink:

Propriedade Descrição Obrigatório
type A propriedade tipo do coletor de Atividade de Cópia deve ser definida como SqlDWSink. Sim
allowPolyBase Indica se o PolyBase deve ser usado para carregar dados no Azure Synapse Analytics. allowCopyCommand e allowPolyBase não podem ser ambos verdadeiros.

Confira a seção Usar o PolyBase para carregar dados no Azure Synapse Analytics para ver os detalhes e as restrições.

Os valores permitidos são True e False (padrão).		 Não.
Aplicar ao usar o PolyBase.
polyBaseSettings Um grupo de propriedades que pode ser especificado quando a propriedade allowPolybase está definida como true. Não.
Aplicar ao usar o PolyBase.
allowCopyCommand Indica se a instrução COPY deve ser usada para carregar dados no Azure Synapse Analytics. allowCopyCommand e allowPolyBase não podem ser ambos verdadeiros.

Confira a seção Usar a instrução COPY para carregar dados no Azure Synapse Analytics para ver os detalhes e as restrições.

Os valores permitidos são True e False (padrão).		 Não.
Aplicar ao usar a instrução COPY.
copyCommandSettings Um grupo de propriedades que pode ser especificado quando a propriedade allowCopyCommand está definida como TRUE. Não.
Aplicar ao usar a instrução COPY.
writeBatchSize Número de linhas a serem inseridas na tabela SQL por lote.

O valor permitido é inteiro (número de linhas). Por padrão, o serviço determina dinamicamente o tamanho do lote apropriado com base no tamanho da linha.		 Não.
Aplicar ao usar Bulk Insert.
writeBatchTimeout Tempo de espera para a operação de inserção em lote ser concluída antes de expirar.

O valor permitido é timespan. Exemplo: "00:30:00" (30 minutos).		 Não.
Aplicar ao usar Bulk Insert.
preCopyScript Especifique uma consulta SQL para que a Atividade de Cópia seja executada antes de gravar dados no Azure Synapse Analytics em cada execução. Use essa propriedade para limpar os dados pré-carregados. Não
tableOption Especifica se a tabela do coletor deve ser criada automaticamente caso ela não exista com base no esquema de origem. Os valores permitidos são none (padrão) e autoCreate. Não
disableMetricsCollection O serviço coleta métricas como DWUs do Azure Synapse Analytics para otimização e recomendações de desempenho de cópia, que introduzem acesso de BD mestre adicional. Se você estiver preocupado com esse comportamento, especifique true para desativá-lo. Não (o padrão é false)
 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.  Nenhum
WriteBehavior Especifique o comportamento de gravação da atividade de cópia para carregar dados Banco de Dados SQL do Azure.
O valor permitido é insert e upsert. Por padrão, o serviço usa insert para carregar dados.		 Não
upsertSettings Especifique o grupo de configurações para comportamento de gravação.
Aplicar quando a opção WriteBehavior for Upsert.		 Não
Em upsertSettings:
chaves Especifique os nomes de coluna para identificação de linha exclusiva. Uma única chave ou uma série de chaves pode ser usada. Se não for especificada, a chave primária será usada. Não
interimSchemaName Especifique o esquema provisório para criar uma tabela intermediária. Observação: o usuário precisa ter a permissão para criar e excluir a tabela. Por padrão, a tabela provisória compartilhará o mesmo esquema que a tabela de coletor. Não

Exemplo 1: coletor do Azure Synapse Analytics

"sink": {
    "type": "SqlDWSink",
    "allowPolyBase": true,
    "polyBaseSettings":
    {
        "rejectType": "percentage",
        "rejectValue": 10.0,
        "rejectSampleValue": 100,
        "useTypeDefault": true
    }
}

Exemplo 2: Dados upsert

"sink": {
    "type": "SqlDWSink",
    "writeBehavior": "Upsert",
    "upsertSettings": {
        "keys": [
             "<column name>"
        ],
        "interimSchemaName": "<interim schema name>"
    },
}

Cópia paralela do Azure Synapse Analytics

O conector do Azure Synapse Analytics 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.

Screenshot of partition options

Quando você habilita a cópia particionada, a atividade de cópia executa consultas paralelas com relação à sua origem do Azure Synapse Analytics para carregar dados por partições. O grau paralelo é controlado pela configuração do parallelCopies na atividade de cópia. Por exemplo, ao definir parallelCopies como quatro, o serviço gera e executa simultaneamente quatro consultas com base na opção de partição especificada e nas configurações, e cada consulta recupera uma parte dos dados do Azure Synapse Analytics.

É recomendável habilitar a cópia paralela com o particionamento de dados, especialmente quando você carrega grandes quantidades de dados do Azure Synapse Analytics. 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.

Cenário Configurações sugeridas
Carregamento completo de uma tabela grande com partições físicas. Opção de partição: partições físicas da tabela.

Durante a execução, o serviço detecta automaticamente as partições físicas e copia os dados por partição.

Para verificar se a tabela tem partição física, confira esta consulta.
Carregamento completo de uma tabela grande, sem partições físicas e com uma coluna de inteiro ou de datetime para o particionamento de dados. Opções de partição: partição de intervalo dinâmico.
Coluna de partição (opcional): especifique a coluna usada para particionar dados. Se não for especificada, a coluna de chave primária ou de índice será usada.
Limite superior da partição e limite inferior da partição (opcional): especifique se deseja determinar o stride da partição. A finalidade não é filtrar as linhas na tabela, todas as linhas da tabela serão particionadas e copiadas. Se não for especificado, a atividade Copy detectará os valores automaticamente.

Por exemplo, se a “ID” da coluna de partição tiver valores no intervalo de 1 a 100 e você definir o limite inferior como 20 e o limite superior como 80, com a cópia paralela definida como 4, o serviço recuperará dados por 4 IDs de partição no intervalo <=20, [21, 50], [51, 80], e >=81, respectivamente.
Carregar uma grande quantidade de dados usando uma consulta personalizada, sem partições físicas, com uma coluna de inteiro ou data/datetime para o particionamento de dados. Opções de partição: partição de intervalo dinâmico.
Consulta: SELECT * FROM <TableName> WHERE ?AdfDynamicRangePartitionCondition AND <your_additional_where_clause>.
Coluna de partição: especifique a coluna usada para particionar dados.
Limite superior da partição e limite inferior da partição (opcional): especifique se deseja determinar o stride da partição. A finalidade não é filtrar as linhas na tabela, todas as linhas na consulta serão particionadas e copiadas. Se não for especificado, a atividade de cópia detectará o valor automaticamente.

Durante a execução, o serviço substitui ?AdfRangePartitionColumnName pelo nome real da coluna e os intervalos de valores para cada partição e envia para o Azure Synapse Analytics.
Por exemplo, se a “ID” da coluna de partição tiver valores no intervalo de 1 a 100 e você definir o limite inferior como 20 e o limite superior como 80, com a cópia paralela definida como 4, o serviço recuperará dados por 4 IDs de partição no intervalo <=20, [21, 50], [51, 80], e >=81, respectivamente.

Veja mais exemplos de consultas para diferentes cenários:
1. Consultar a tabela inteira:
SELECT * FROM <TableName> WHERE ?AdfDynamicRangePartitionCondition
2. Consultar em uma tabela com seleção de coluna e filtros de cláusula "where" adicionais:
SELECT <column_list> FROM <TableName> WHERE ?AdfDynamicRangePartitionCondition AND <your_additional_where_clause>
3. Consultar com sub-consultas:
SELECT <column_list> FROM (<your_sub_query>) AS T WHERE ?AdfDynamicRangePartitionCondition AND <your_additional_where_clause>
4. Consultar com partição na sub-consulta:
SELECT <column_list> FROM (SELECT <your_sub_query_column_list> FROM <TableName> WHERE ?AdfDynamicRangePartitionCondition) AS T

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

  1. Escolha a coluna distinta como coluna de partição (como chave primária ou chave exclusiva) para evitar a distorção de dados.
  2. Se a tabela tiver uma partição interna, use a opção de partição "Partições físicas da tabela" para ter um melhor desempenho.
  3. 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.
  4. 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).
  5. Observe que o Azure Synapse Analytics pode executar no máximo 32 consultas por vez. Definir um valor muito alto de “grau de paralelismo de cópia” pode causar um problema de limitação do Synapse.

Exemplo: carregamento completo de uma tabela grande com partições físicas

"source": {
    "type": "SqlDWSource",
    "partitionOption": "PhysicalPartitionsOfTable"
}

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

"source": {
    "type": "SqlDWSource",
    "query": "SELECT * FROM <TableName> WHERE ?AdfDynamicRangePartitionCondition 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>"
    }
}

Exemplo de consulta para verificar a partição física

SELECT DISTINCT s.name AS SchemaName, t.name AS TableName, c.name AS ColumnName, CASE WHEN c.name IS NULL THEN 'no' ELSE 'yes' END AS HasPartition
FROM sys.tables AS t
LEFT JOIN sys.objects AS o ON t.object_id = o.object_id
LEFT JOIN sys.schemas AS s ON o.schema_id = s.schema_id
LEFT JOIN sys.indexes AS i ON t.object_id = i.object_id
LEFT JOIN sys.index_columns AS ic ON ic.partition_ordinal > 0 AND ic.index_id = i.index_id AND ic.object_id = t.object_id
LEFT JOIN sys.columns AS c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
LEFT JOIN sys.types AS y ON c.system_type_id = y.system_type_id
WHERE s.name='[your schema]' AND t.name = '[your table name]'

Se a tabela tiver uma partição física, você verá "HasPartition" como "yes".

Usar a instrução COPY para carregar dados no Azure Synapse Analytics

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

  • Se seus dados de fonte estão no Azure Blob ou no Azure Data Lake Storage Gen2 e o formato é compatível com a instrução COPY, você pode usar a atividade de cópia para invocar a instrução COPY diretamente para permitir que o Azure Synapse Analytics extraia dados da fonte. 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 preparada também oferece melhor rendimento. Ele converte automaticamente os dados no formato compatível com instrução COPY, armazena os dados no Armazenamento de Blobs do Azure e chama a instrução COPY para carregar dados no Azure Synapse Analytics.

Dica

Ao usar a instrução COPY com o Azure Integration Runtime, as DIUs (unidades de integração de dados) efetivas são sempre 2. O ajuste de DIUs não afeta o desempenho, uma vez que o carregamento de dados do armazenamento é realizado pelo mecanismo do Azure Synapse.

Cópia direta usando a instrução COPY

A instrução COPY do Azure Synapse Analytics é diretamente compatível com o Blob do Azure, o Azure Data Lake Storage Gen1 e o 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 Azure Synapse Analytics. Caso contrário, use Cópia preparada usando a instrução COPY. O serviço verificará as configurações e falhará na execução da atividade de cópia se os critérios não forem atendidos.

  1. 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 da chave da conta, autenticação de assinatura de acesso compartilhado, autenticação da entidade de serviço, autenticação da identidade gerenciada atribuída pelo sistema
      Parquet Autenticação de chave de conta, autenticação de assinatura de acesso compartilhado
      ORC Autenticação de chave de conta, autenticação de assinatura de acesso compartilhado
    Azure Data Lake Storage Gen2 Texto delimitado
    Parquet
    ORC    		 Autenticação da chave da conta, autenticação da entidade de serviço, autenticação da identidade gerenciada atribuída pelo sistema

    Importante

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

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

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

  4. 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:

Propriedade Descrição Obrigatório
defaultValues Especifica os valores padrão para cada coluna de destino no Azure Synapse Analytics. Os valores padrão na propriedade substituem a restrição DEFAULT definida no data warehouse e a coluna de identidade não pode ter um valor padrão. Não
additionalOptions Opções adicionais que serão passadas para a instrução COPY do Azure Synapse Analytics diretamente na cláusula "With" na instrução COPY. Coloque o valor entre aspas conforme necessário para alinhar com os requisitos da instrução COPY. Não 
"activities":[
    {
        "name": "CopyFromAzureBlobToSQLDataWarehouseViaCOPY",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "ParquetDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ParquetSource",
                "storeSettings":{
                    "type": "AzureBlobStorageReadSettings",
                    "recursive": true
                }
            },
            "sink": {
                "type": "SqlDWSink",
                "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 Azure Synapse Analytics. 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 autenticação de identidade gerenciada pelo sistema ou chave de conta que se refere à conta de armazenamento do Azure como armazenamento provisório.

Importante

Importante

Se o Armazenamento do Azure de preparo estiver configurado com o Ponto de Extremidade Privado gerenciado e tiver o firewall de armazenamento habilitado, use a autenticação de identidade gerenciada e conceda permissões de Leitor de Dados de Blob do Armazenamento para o SQL Server do Synapse para garantir que ele possa acessar os arquivos preparados durante o carregamento da instrução COPY.

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

Usar o PolyBase para carregar dados no Azure Synapse Analytics

Usar o PolyBase é uma forma eficiente de carregar uma grande quantidade de dados no Azure Synapse Analytics com taxa de transferência alta. Você verá um grande ganho na taxa de transferência usando PolyBase em vez do mecanismo BULKINSERT padrão.

  • Se os dados de origem estiverem no Blob do Azure, no Azure Data Lake Storage Gen1 ou no Azure Data Lake Storage Gen2 e o formato for compatível com o PolyBase, você poderá usar a atividade de cópia para invocar diretamente o PolyBase para permitir que o Azure Synapse Analytics efetue pull dos dados da origem. Para detalhes, veja Cópia direta usando PolyBase .
  • Se o armazenamento e o formato de dados de origem não forem originalmente suportados pelo PolyBase, use a cópia Staged usando o recurso PolyBase . O recurso de cópia preparada também oferece melhor rendimento. Ele converte automaticamente os dados no formato compatível com o PolyBase, armazena os dados no Armazenamento de Blobs do Azure e chama o PolyBase para carregar dados no Azure Synapse Analytics.

Dica

Saiba mais sobre as Melhores práticas para usar o PolyBase. Ao usar o PolyBase com o Azure Integration Runtime, o valor de DIUs (unidades de integração de dados) em vigor para o armazenamento direto ou preparado para o Synapse é sempre 2. O ajuste de DIUs não afeta o desempenho, uma vez que o carregamento de dados do armazenamento é realizado pelo mecanismo do Synapse.

As seguintes configurações do PolyBase são compatíveis em polyBaseSettings na atividade de cópia:

Propriedade Descrição Obrigatório
rejectValue Especifica o número ou o percentual de linhas que podem ser rejeitadas antes de a consulta falhar.

Saiba mais sobre as opções de rejeição do PolyBase na seção Argumentos de CREATE EXTERNAL TABLE (Transact-SQL).

Os valores permitidos são 0 (padrão), 1, 2 etc.		 Não
rejectType Especifica se a opção rejectValue é um valor literal ou uma porcentagem.

Os valores permitidos são Valor (padrão) e Porcentagem.		 Não
rejectSampleValue Determina o número de linhas a serem recuperadas antes que o PolyBase recalcule a porcentagem de linhas rejeitadas.

Os valores permitidos são 1, 2 etc.		 Sim, se o rejectType for porcentagem.
useTypeDefault Especifica como tratar valores ausentes em arquivos de texto delimitados quando o PolyBase recuperar dados do arquivo de texto.

Saiba mais sobre essa propriedade na seção Argumentos em CRIAR FORMATO DE ARQUIVO EXTERNO (Transact-SQL).

Os valores permitidos são True e False (padrão).

 Não

Cópia direta usando PolyBase

O PolyBase do Azure Synapse Analytics é diretamente compatível com o Blob do Azure, o Azure Data Lake Storage Gen1 e o Azure Data Lake Storage Gen2. Se os dados de origem atenderem aos critérios descritos nesta seção, use o PolyBase para copiar diretamente do armazenamento de dados de origem para o Azure Synapse Analytics. Caso contrário, use cópia Staged usando PolyBase.

Dica

Para copiar dados de maneira eficiente para o Azure Synapse Analytics, saiba mais em O Azure Data Factory torna ainda mais fácil e conveniente descobrir percepções dos dados ao usar o Data Lake Storage com o Azure Synapse Analytics.

Se os requisitos não forem atendidos, o serviço verificará as configurações e retornará automaticamente ao mecanismo BULKINSERT para a movimentação de dados.

  1. O serviço vinculado de origem acompanha os seguintes tipos e métodos de autenticação:

    Tipo de armazenamento de dados de origem compatíveis Tipos de autenticação de origem compatíveis
    Blob do Azure Autenticação da chave da conta, autenticação da identidade gerenciada atribuída pelo sistema
    Azure Data Lake Storage Gen1 Autenticação de entidade de serviço
    Azure Data Lake Storage Gen2 Autenticação da chave da conta, autenticação da identidade gerenciada atribuída pelo sistema

    Importante

  2. O formato de dados de origem é de Parquet, ORC ou Texto delimitado, com as seguintes configurações:

    1. O caminho da pasta não contém o filtro curinga.
    2. O nome do arquivo está vazio ou aponta para apenas um arquivo. Se você especificar o nome de arquivo curinga na atividade de cópia, ele só poderá ser * ou *.*.
    3. rowDelimiter é padrão, \n, \r\n ou \r.
    4. nullValue é deixado como padrão ou definido como cadeia de caracteres vazia ("") e treatEmptyAsNull é deixado como padrão ou definido como true.
    5. encodingName é deixado como padrão ou definido como utf-8.
    6. quoteChar, escapeChar e skipLineCount não são especificadas. O PolyBase é compatível com a opção de ignorar a linha de cabeçalho, que pode ser configurada como firstRowAsHeader.
    7. compression pode ser nenhuma compactação, GZip, ouDesinflar.

  3. Se a sua origem for uma pasta, recursive na atividade de cópia precisará ser definida como true.

  4. wildcardFolderPath, wildcardFilename, modifiedDateTimeStart, modifiedDateTimeEnd, prefix, enablePartitionDiscovery e additionalColumns não são especificados.

Observação

Se a sua origem for uma pasta, o PolyBase recuperará arquivos da pasta e de todas as respectivas subpastas e não recuperará dados de arquivos para os quais o nome do arquivo começa com um sublinhado (_) ou um ponto final (.), conforme documentado aqui – argumento LOCATION.

"activities":[
    {
        "name": "CopyFromAzureBlobToSQLDataWarehouseViaPolyBase",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "ParquetDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ParquetSource",
                "storeSettings":{
                    "type": "AzureBlobStorageReadSettings",
                    "recursive": true
                }
            },
            "sink": {
                "type": "SqlDWSink",
                "allowPolyBase": true
            }
        }
    }
]

Cópia organizada usando PolyBase

Quando os dados de origem não são nativamente compatíveis com o PolyBase, 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 do PolyBase. Em seguida, ele invoca o PolyBase para carregar dados no Azure Synapse Analytics. 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 autenticação de identidade gerenciada ou chave de conta que se refere à conta de armazenamento do Azure como armazenamento provisório.

Importante

Importante

Se o Armazenamento do Azure de preparo estiver configurado com o Ponto de Extremidade Privado gerenciado e tiver o firewall de armazenamento habilitado, use a autenticação de identidade gerenciada e conceda permissões de Leitor de Dados de Blob do Armazenamento para o SQL Server do Synapse para garantir que ele possa acessar os arquivos preparados durante o carregamento do PolyBase.

"activities":[
    {
        "name": "CopyFromSQLServerToSQLDataWarehouseViaPolyBase",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "SQLServerDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlSource",
            },
            "sink": {
                "type": "SqlDWSink",
                "allowPolyBase": true
            },
            "enableStaging": true,
            "stagingSettings": {
                "linkedServiceName": {
                    "referenceName": "MyStagingStorage",
                    "type": "LinkedServiceReference"
                }
            }
        }
    }
]

Práticas recomendadas para usar o PolyBase

As seções a seguir fornecem melhores práticas além daquelas mencionadas em Melhores práticas para o Azure Synapse Analytics.

Permissão de banco de dados obrigatória

Para usar o PolyBase, o usuário que carrega dados no Azure Synapse Analytics deve ter a permissão "CONTROLE" no banco de dados de destino. Uma maneira de conseguir isso é adicionar o usuário como membro da função db_owner. Saiba como fazer isso na Visão geral do Azure Synapse Analytics.

Limites de tamanho de linha e tipo de dados

As cargas do PolyBase são limitadas a linhas menores que 1 MB. Ele não pode ser usado para carregar para VARCHR (MAX), NVARCHAR (MAX) ou VARBINARY (MAX). Para saber mais, confira Limites de capacidade de serviço do Azure Synapse Analytics.

Quando os dados de origem tiverem linhas maiores que 1 MB, talvez você queira dividir verticalmente as tabelas de origem em várias pequenas. Certifique-se de que o maior tamanho de cada linha não exceda o limite. As tabelas menores podem ser carregadas por meio de PolyBase e mescladas no Azure Synapse Analytics.

Como alternativa, para dados com colunas tão largas assim, você pode carregar os dados sem o PolyBase, desativando a configuração “permitir PolyBase”.

Classe de recurso do Azure Synapse Analytics

Para obter a melhor taxa de transferência possível, atribua uma classe de recurso maior ao usuário que carrega dados No Azure Synapse Analytics por meio do PolyBase.

Solucionando problemas do PolyBase

Carregando na coluna Decimal

Se os dados de origem estiverem em formato de texto ou em outros repositórios compatíveis que não sejam o PolyBase (usando a cópia preparada e o PolyBase) e contiverem um valor vazio a ser carregado na coluna Decimal do Azure Synapse Analytics, você poderá encontrar o seguinte erro:

ErrorCode=FailedDbOperation, ......HadoopSqlException: Error converting data type VARCHAR to DECIMAL.....Detailed Message=Empty string can't be converted to DECIMAL.....

A solução é desmarcar a opção "Usar o tipo padrão" (como false) no coletor da atividade de cópia -> configurações do PolyBase. "USE_TYPE_DEFAULT" é uma configuração nativa do PolyBase, que especifica como tratar valores ausentes em arquivos de texto delimitados quando o PolyBase recupera dados do arquivo de texto.

Verificar a propriedade tableName no Azure Synapse Analytics

A tabela a seguir fornece exemplos de como especificar o tableName propriedade no conjunto de dados JSON. Ele mostra as várias combinações de nomes de esquema e tabela.

Esquema do BD Nome da tabela tableName propriedade JSON
dbo MyTable MyTable ou dbo.MyTable ou [dbo].[MyTable]
dbo1 MyTable dbo1.MyTable ou [dbo1].[MyTable]
dbo My.Table [My.Table] ou [dbo].[My.Table]
dbo1 My.Table [dbo1]. [My.Table]

Se você vir o erro a seguir, o problema pode ser o valor especificado para o tableName propriedade. Consulte a tabela anterior para a maneira correta especificar valores para o tableName propriedade JSON.

Type=System.Data.SqlClient.SqlException,Message=Invalid object name 'stg.Account_test'.,Source=.Net SqlClient Data Provider

Colunas com valores padrão

No momento, o recurso PolyBase aceita apenas o mesmo número de colunas da tabela de destino. Um exemplo é uma tabela com quatro colunas em que uma delas é definida com um valor padrão. Os dados de entrada ainda precisam ter quatro colunas. Um conjunto de dados de entrada de três colunas produz um erro semelhante à seguinte mensagem:

All columns of the table must be specified in the INSERT BULK statement.

O valor NULL é uma forma especial do valor padrão. Se a coluna permite valor nulo, os dados de entrada no blob para essa coluna podem estar vazios. Mas não pode estar ausente do conjunto de dados de entrada. O PolyBase insere NULL para valores ausentes no Azure Synapse Analytics.

Falha no acesso ao arquivo externo

Se receber o erro a seguir, verifique se você está usando a autenticação de identidade gerenciada e concedeu permissões de Leitor de Dados de Blob de Armazenamento à identidade gerenciada do workspace do Azure Synapse.

Job failed due to reason: at Sink '[SinkName]': shaded.msdataflow.com.microsoft.sqlserver.jdbc.SQLServerException: External file access failed due to internal error: 'Error occurred while accessing HDFS: Java exception raised on call to HdfsBridge_IsDirExist. Java exception message:\r\nHdfsBridge::isDirExist

Para saber mais, confira Conceder permissões à identidade gerenciada após a criação do workspace.

Mapeamento de propriedades de fluxo de dados

Ao transformar dados no fluxo de dados de mapeamento, você pode ler e gravar em tabelas do Azure Synapse Analytics. Para obter mais informações, confira transformação de origem e transformação do coletor nos fluxos de dados de mapeamento.

Transformação de origem

Configurações específicas para o Azure Synapse Analytics estão disponíveis na guia Opções de Origem da transformação de origem.

Entrada Selecione se você deseja apontar a origem para uma tabela (equivalente a Select * from <table-name>) ou inserir uma consulta SQL personalizada.

Habilitar preparo É altamente recomendável que você use essa opção em cargas de trabalho de produção com as fontes do Azure Synapse Analytics. Ao executar uma atividade de fluxo de dados com fontes do Azure Synapse Analytics de um pipeline, você será solicitado a fornecer uma conta de armazenamento de um local de preparo e a usará para o carregamento de dados preparados. Trata-se do mecanismo mais rápido para carregar dados do Azure Synapse Analytics.

  • Ao usar a autenticação de identidade gerenciada para o serviço vinculado de armazenamento, conheça as configurações necessárias para o Blob do Azure e o Azure Data Lake Storage Gen2 respectivamente.
  • Se o Armazenamento do Azure estiver configurado com o ponto de extremidade de serviço de VNet, você precisará usar a autenticação de identidade gerenciada com a opção "permitir serviço confiável da Microsoft" habilitada na conta de armazenamento. Confira Impacto de usar pontos de extremidade de serviço de VNet com Armazenamento do Azure.
  • Quando você usa o pool de SQL sem servidor do Azure Synapse como fonte, não há suporte para habilitar o preparo.

Consulta: se você selecionar Consulta no campo de entrada, insira uma consulta SQL para sua origem. Essa configuração substitui qualquer tabela que você tenha escolhido no conjunto de dados. Cláusulas Order By não são compatíveis aqui, mas você pode definir uma instrução SELECT FROM completa. Também pode usar funções de tabela definidas pelo usuário. select * from udfGetData() é um UDF no SQL que retorna uma tabela. Essa consulta produzirá uma tabela de origem que você pode usar em seu fluxo de dados. O uso de consultas também é uma ótima maneira de reduzir linhas para testes ou pesquisas.

Exemplo do SQL: Select * from MyTable where customerId > 1000 and customerId < 2000

Tamanho do lote: insira um tamanho de lote para dividir dados grandes em leituras. Em fluxos de dados, essa configuração será usada para definir o cache de coluna do Spark. Este é um campo opcional que usará padrões do Spark se ele for deixado em branco.

Nível de isolamento: o padrão para as origens SQL no fluxo de dados de mapeamento é leitura não confirmada. Você pode alterar o nível de isolamento aqui para um destes valores:

  • Leitura Confirmada
  • Leitura Não Confirmada
  • Leitura repetida
  • Serializável
  • Nenhum (ignorar o nível de isolamento)

Isolation Level

Transformação de coletor

Configurações específicas para o Azure Synapse Analytics estão disponíveis na guia Configurações da transformação de coletor.

Método Update: determina quais operações são permitidas no destino do banco de dados. O padrão é permitir apenas inserções. Para atualizar, fazer upsert ou excluir linhas, uma transformação alter-row é necessária para marcar as linhas para essas ações. Para atualizações, upserts e exclusões, é necessário selecionar uma coluna de chave ou colunas para determinar qual linha alterar.

Ação de tabela: determina se deve-se recriar ou remover todas as linhas da tabela de destino antes da gravação.

  • Nenhuma: nenhuma ação será feita na tabela.
  • Recriar: a tabela será descartada e recriada. Necessário ao criar uma tabela dinamicamente.
  • Truncar: todas as linhas da tabela de destino serão removidas.

Habilitar preparo: permite o carregamento em Pools de SQL do Azure Synapse Analytics usando o comando de cópia e é recomendado para a maioria dos coletores do Synapse. O armazenamento de preparo é configurado na atividade Executar Fluxo de Dados.

Tamanho do lote: controla quantas linhas estão sendo gravadas em cada bucket. Tamanhos de lote maiores aprimoram a compactação e a otimização de memória, mas geram risco de exceções de memória insuficiente ao armazenar dados em cache.

Usar esquema de coletor: por padrão, uma tabela temporária será criada no esquema do coletor como processo de preparo. Como alternativa, você pode desmarcar a opção Usar esquema de coletor e, em vez disso, em Selecionar esquema de banco de dados de usuário, especificar um nome de esquema em que o Data Factory criará uma tabela de preparo para carregar dados upstream e limpá-los automaticamente após a conclusão. Crie a permissão de tabela no banco de dados e altere a permissão no esquema.

Screenshot showing the data flow 'Use sink schema'.

Scripts SQL prévios e posteriores: Insira scripts SQL de várias linhas que serão executados antes (pré-processamento) e após (pós-processamento) os dados serem gravados no banco de dados do coletor

Screenshot showing pre and post SQL processing scripts in Azure Synapse Analytics data flow.

Dica

  1. É recomendável quebrar scripts de lote únicos com vários comandos em vários lotes.
  2. Apenas as instruções DDL (linguagem de definição de dados) e DML (linguagem de manipulação de dados) que retornam uma contagem de atualização simples podem ser executadas como parte de um lote. Saiba mais sobre Executando operações em lote

Tratamento da linha de erros

Ao gravar no Azure Synapse Analytics, determinadas linhas de dados podem falhar devido a restrições definidas pelo destino. Alguns erros comuns incluem:

  • Cadeia de caracteres ou dados de binário seriam truncados na tabela
  • Não é possível inserir o valor NULL na coluna
  • Falha ao converter o valor para o tipo de dado

Por padrão, uma execução de fluxo de dados falhará no primeiro erro obtido. É possível optar por continuar se houver erro que permite que o fluxo de dados seja concluído mesmo se as linhas individuais tiverem erros. O serviço fornece opções diferentes para você identificar essas linhas de erro.

Confirmação de transação: escolha se os dados sã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.

Dados rejeitados na saída: se esta opção estiver habilitada, você poderá gerar as linhas de erro em um arquivo CSV no Armazenamento de Blobs do Azure ou em uma conta do Azure Data Lake Storage Gen2 de 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 no erro: se esta opção estiver habilitada, o fluxo de dados será marcado como sucesso, mesmo que linhas de erro sejam encontradas.

Diagram that shows the error row handling in mapping data flow sink transformation.

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 do tipo de dados para o Azure Synapse Analytics

Quando você copia dados de ou para o Azure Synapse Analytics, os mapeamentos a seguir são usados dos tipos de dados do Azure Synapse Analytics para os tipos de dados temporários do Azure Data Factory. Esses mapeamentos também são usados ao copiar dados de ou para o Azure Synapse Analytics usando pipelines do Synapse, já que os pipelines também implementam o Azure Data Factory no Azure Synapse. Consulte mapeamentos de tipo de esquema e dados para saber como a atividade de cópia mapeia o tipo de esquema e os dados de origem para o coletor.

Dica

Confira o artigo Tipos de dados de tabela no Azure Synapse Analytics sobre os tipos de dados compatíveis com o Azure Synapse Analytics e as soluções alternativas para os incompatíveis.

Tipo de dados do Azure Synapse Analytics Tipo de dados provisório do Data Factory
BIGINT Int64
binary Byte[]
bit Boolean
char String, Char[]
date Datetime
Datetime Datetime
datetime2 Datetime
Datetimeoffset DateTimeOffset
Decimal Decimal
FILESTREAM attribute (varbinary(max)) Byte[]
Float Double
image Byte[]
INT Int32
money Decimal
NCHAR String, Char[]
numeric Decimal
NVARCHAR String, Char[]
real Single
rowversion Byte[]
smalldatetime Datetime
SMALLINT Int16
SMALLMONEY Decimal
time TimeSpan
TINYINT Byte
UNIQUEIDENTIFIER Guid
varbinary Byte[]
varchar String, Char[]

Conteúdo relacionado

Para obter uma lista de repositórios de dados com suporte como fontes e repositórios por Atividade Copy, confira armazenamentos e formatos de dados compatíveis.