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

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

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)	① ②	✓
Fluxo de dados de mapeamento (origem/coletor)	①	✓
Atividade de pesquisa	① ②	✓
Atividade GetMetadata	① ②	✓
Atividade de Script	① ②	✓
Stored procedure activity (Atividade de procedimento armazenado)	① ②	✓

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

Introdução

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

• A ferramenta Copiar Dados
• O portal do Azure
• O SDK do .NET
• O SDK do Python
• PowerShell do Azure
• A API REST
• O modelo do Azure Resource Manager

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:

   • Azure Data Factory
   • Azure Synapse

   

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

   

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

   

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

A versão Recomendada do conector Azure Synapse Analytics suporta TLS 1.3. Consulte essa secção para atualizar a sua versão do conector Azure Synapse Analytics de Legado. Para os detalhes da propriedade, veja as seções correspondentes.

• Versão recomendada
• Versão herdada

Versão recomendada

Essas propriedades genéricas têm suporte para um serviço vinculado do Azure Synapse Analytics quando você aplica a versão Recomendada:

Propriedade	Descrição	Obrigatório
type	A propriedade type deve ser definida como AzureSqlDW.	Yes
Servidor	O nome ou o endereço de rede da instância de servidor SQL à qual você deseja se conectar.	Yes
Banco de Dados	O nome do banco de dados.	Yes
authenticationType	O tipo usado para autenticação. Os valores permitidos são SQL (padrão), ServicePrincipal, SystemAssignedManagedIdentity, UserAssignedManagedIdentity. Acesse a seção de autenticação relevante em propriedades e pré-requisitos específicos.	Yes
criptografar	Indique se a criptografia TLS é necessária em todos os dados enviados entre o cliente e o servidor. Opções: obrigatória (para true, padrão)/opcional (para false)/strict.	Não
trustServerCertificate	Indica se o canal será criptografado ao passar pela cadeia de certificados para validar a confiança.	Não
hostNameInCertificate	O nome do host a ser usado ao validar o certificado do servidor para a conexão. Quando não é especificado, o nome do servidor é usado para validação de certificado.	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

Consulte a tabela abaixo para obter as propriedades de conexão adicionais:

Propriedade	Descrição	Obrigatório
applicationIntent	O tipo de carga de trabalho de aplicativo ao conectar-se a um servidor. Os valores permitidos são ReadOnly e ReadWrite.	Não
connectTimeout	O período time (em segundos) a aguardar para uma conexão ao servidor antes de terminar a tentativa e gerar um erro.	Não
connectRetryCount	O número de tentativas de reconexões após identificar uma falha por conexão ociosa. O valor deve ser um número inteiro entre 0 e 255.	Não
connectRetryInterval	O tempo (em segundos) entre cada tentativa de reconexão após identificar uma falha por conexão ociosa. O valor deve ser um número inteiro entre 1 e 60.	Não
loadBalanceTimeout	O tempo mínimo (em segundos) para que a conexão resida no pool de conexões antes da conexão ser destruída.	Não
commandTimeout	Define o tempo de espera (em segundos) antes de encerrar a tentativa de executar um comando e antes de gerar um erro.	Não
integratedSecurity	Os valores permitidos são true e false. Ao especificar false, indique se userName e password estão especificados na conexão. Ao especificar true, indica se as credenciais atuais da conta do Windows são usadas para autenticação.	Não
failoverPartner	O nome ou endereço do servidor parceiro ao qual se conectar se o servidor primário estiver inativo.	Não
maxPoolSize	O número máximo de conexões permitidas no pool de conexões para a conexão específica.	Não
minPoolSize	O número mínimo de conexões permitidas no pool de conexões para a conexão específica.	Não
multipleActiveResultSets	Os valores permitidos são true e false. Ao especificar true, um aplicativo pode manter vários conjuntos de resultados ativos múltiplos (MARS). Ao você especificar false, um aplicativo deve processar ou cancelar todos os conjuntos de resultados de um lote antes de poder executar outros lotes nessa conexão.	Não
multiSubnetFailover	Os valores permitidos são true e false. Se o aplicativo estiver se conectando a um AG (grupo de disponibilidade) AlwaysOn em diferentes sub-redes, definir true como true fornece uma detecção e uma conexão mais rápida ao servidor atualmente ativo.	Não
packetSize	Tamanho em bytes dos pacotes de rede usados para comunicar-se com uma instância de servidor.	Não
pooling	Os valores permitidos são true e false. Ao especificar true, a conexão será colocada em pool. Ao especificar false, a conexão será aberta explicitamente toda vez que a conexão for solicitada.	Não

Autenticação do SQL

Para usar a autenticação SQL, além das propriedades genéricas descritas na seção anterior, especifique as seguintes propriedades:

Propriedade	Descrição	Obrigatório
userName	O nome de usuário usado para se conectar ao servidor.	Yes
password	A senha do nome de usuário. Marque esse campo como SecureString para armazená-lo com segurança. Você também pode referenciar um segredo armazenado no Azure Key Vault.	Yes

Exemplo: uso de autenticação SQL

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "SQL",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo: senha no Azure Key Vault

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "SQL",
            "userName": "<user name>",
            "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.	Yes
servicePrincipalCredential	A credencial da entidade de serviço. 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.	Yes
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
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

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>",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<application 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": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "SystemAssignedManagedIdentity"
        },
        "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": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "UserAssignedManagedIdentity",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Versão herdada

Essas propriedades genéricas têm suporte para um serviço vinculado do Azure Synapse Analytics quando você aplica a versão Herdado:

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 a senha/chave principal do serviço no Azure Key Vault e, se for autenticação SQL, extrair a password configuração da cadeia de conexão. Veja o artigo Armazenar credenciais no Azure Key Vault com mais detalhes.	Yes
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 e pré-requisitos, respectivamente:

• Autenticação SQL para a versão herdada
• Autenticação da entidade de serviço para a versão herdada
• Autenticação de identidade gerenciada atribuída pelo sistema para a versão herdada
• Autenticação de identidade gerenciada atribuída pelo usuário para a versão herdada

Autenticação SQL para a versão herdada

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

Autenticação da entidade de serviço para a versão herdada

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, como nome de domínio ou ID do locatário, em que o aplicativo reside. Recupere-as passando o mouse no canto superior direito do Portal do Azure.	Sim
azureCloudType	Para autenticação da entidade de serviço, especifique o tipo de ambiente em nuvem do Azure em que seu aplicativo do Microsoft Entra está registrado. Os valores permitidos são AzurePublic, AzureChina, AzureUsGovernment e AzureGermany. Por padrão, o data factory ou o ambiente de nuvem do pipeline do Synapse é usado.	Não

Você também precisa seguir as etapas na autenticação da entidade de serviço para conceder a permissão correspondente.

Autenticação de identidade gerenciada atribuída pelo sistema para a versão herdada

Para usar a autenticação de identidade gerenciada atribuída pelo sistema, siga a mesma etapa para a versão recomendada na autenticação de identidade gerenciada atribuída pelo sistema.

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

Para usar a autenticação de identidade gerenciada atribuída pelo usuário, siga a mesma etapa para a versão recomendada na autenticação de identidade gerenciada atribuída pelo usuário.

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

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 ?DfDynamicRangePartitionCondition 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.

• Usar a instrução COPY
• Usar o PolyBase
• Usar Bulk Insert

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	O tempo de espera para que a operação de inserção, upsert e procedimento armazenado seja concluída antes de atingir o tempo limite. Os valores permitidos são para o timespan. Um exemplo é "00:30:00" por 30 minutos. Se nenhum valor for especificado, o tempo limite padrão será "00:30:00".	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 de 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 no Azure Synapse Analytics. 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.

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 ?DfDynamicRangePartitionCondition 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. 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 ?DfDynamicRangePartitionCondition 2. Consultar em uma tabela com seleção de coluna e filtros de cláusula "where" adicionais: SELECT <column_list> FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause> 3. Consultar com sub-consultas: SELECT <column_list> FROM (<your_sub_query>) AS T WHERE ?DfDynamicRangePartitionCondition 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 ?DfDynamicRangePartitionCondition) 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 ?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>"
    }
}

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.

Cópia direta usando a instrução COPY

A instrução COPY do Azure Synapse Analytics dá suporte diretamente ao Blob do Azure 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 Azure Synapse Analytics. 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.

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 de chave de conta, autenticação de assinatura de acesso compartilhado, autenticação de entidade de serviço (usando ServicePrincipalKey), autenticação de 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 de chave de conta, autenticação da entidade de serviço (usando ServicePrincipalKey), autenticação de assinatura de acesso compartilhado, autenticação de identidade gerenciada atribuída pelo sistema

   Importante

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

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.

"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 ou no Azure Data Lake Storage Gen2 e o formato for compatível com o PolyBase, você poderá usar a atividade Copy 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.

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 dá suporte diretamente ao Blob do Azure e ao 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.

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 Gen2	Autenticação da chave da conta, autenticação da identidade gerenciada atribuída pelo sistema

   Importante

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

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.

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

"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)

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.

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

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.

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

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.

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.

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[]

Atualize a versão do Azure Synapse Analytics

Para atualizar a versão do Azure Synapse Analytics, na página Editar serviço vinculado, selecione Recomendado em Versão e configure o serviço vinculado consultando Propriedades do serviço vinculado para a versão recomendada.

Diferenças entre a versão recomendada e a versão herdada

A tabela abaixo mostra as diferenças entre o Azure Synapse Analytics usando a versão recomendada e a versão herdada.

Versão recomendada	Versão herdada
Suporta TLS 1.3 via encrypt como strict.	TLS 1.3 não é compatível.

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.