Copie e transforme dados no Azure Synapse Analytics utilizando pipelines do Azure Data Factory ou Synapse

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como usar a Copy Activity no Azure Data Factory ou em pipelines 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 Azure Data Factory, leia o artigo introdutório.

Capacidades suportadas

Este conector Azure Synapse Analytics é suportado para as seguintes capacidades:

(1) Runtime de integração Azure (2) Runtime de integração auto-hospedado

Para atividade Copy, este conector Azure Synapse Analytics suporta estas funções:

• Copie dados usando autenticação SQL Server e autenticação por token da aplicação Microsoft Entra com um principal de serviço ou identidades geridas para recursos da Azure.
• Como fonte, recupere dados usando uma consulta SQL ou um procedimento armazenado. Também pode optar por copiar paralelamente de uma fonte Azure Synapse Analytics, veja a secção Cópia paralela de Azure Synapse Analytics para mais detalhes.
• Como um destino de dados, carregue dados usando a instrução COPY ou PolyBase ou inserção em massa. Recomendamos a instrução COPY ou o PolyBase para um melhor desempenho de cópia. O conector também suporta a criação automática de uma tabela de destino com DISTRIBUTION = ROUND_ROBIN, caso não exista, com base no esquema de origem.

Introdução

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

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

Crie um serviço ligado ao Azure Synapse Analytics usando UI

Use os seguintes passos para criar um serviço ligado ao Azure Synapse Analytics na interface do portal Azure.

1. Navegue até ao separador Gerir no seu espaço de trabalho Azure Data Factory ou Synapse e selecione Serviços Ligados, depois clique em Novo:

   • Azure Data Factory
   • Azure Synapse

   

2. Procure por Synapse e selecione o conector Azure Synapse Analytics.

   

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

   

Detalhes de configuração do conector

As secções seguintes fornecem detalhes sobre as propriedades que definem as 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 do conector Azure Synapse Analytics Recommended suporta TLS 1.3. Consulte esta secção para atualizar a versão do seu conector Azure Synapse Analytics a partir do Legacy. Para obter os detalhes da propriedade, consulte as seções correspondentes.

• Versão recomendada
• Versão legacy

Versão recomendada

Estas propriedades genéricas são suportadas para um serviço ligado ao Azure Synapse Analytics ao aplicar a versão Recommended:

Para obter propriedades de conexão adicionais, consulte a tabela abaixo:

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:

Exemplo: usando a 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: palavra-passe em 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 do principal de serviço

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

Você também precisa seguir os passos abaixo:

1. Criar uma aplicação Microsoft Entra a partir do portal Azure. Anote o nome do aplicativo e os seguintes valores que definem o serviço vinculado:

   • ID da aplicação
   • Chave de aplicação
   • ID de Locatário

2. Provisiona um administrador de Microsoft Entra para o teu servidor no portal Azure, caso ainda não o tenhas feito. O administrador da Microsoft Entra pode ser um utilizador da Microsoft Entra ou um grupo da Microsoft Entra. Se você conceder ao grupo com identidade gerenciada uma função de administrador, ignore as etapas 3 e 4. O administrador terá acesso total à base de dados.

3. Crie utilizadores de base de dados contidos para o principal de serviço. Ligue-se ao armazém de dados de ou para o qual pretende copiar dados usando ferramentas como o SSMS, com uma identidade Microsoft Entra que tenha pelo menos a permissão de ALTERAR QUALQUER UTILIZADOR. Execute o seguinte T-SQL:

   CREATE USER [your_application_name] FROM EXTERNAL PROVIDER;
   

4. Conceda à entidade de serviço as permissões necessárias como normalmente faz para utilizadores SQL ou outros. Execute o código a seguir ou consulte mais opções aqui. Se quiseres usar o PolyBase para carregar os dados, informa-te sobre a permissão necessária de base de dados.

   EXEC sp_addrolemember db_owner, [your application name];
   

5. Configure um serviço Azure Synapse Analytics ligado num espaço de trabalho Azure Data Factory ou Synapse.

Exemplo de serviço vinculado que usa a autenticação da entidade 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 geridas atribuídas pelo sistema para autenticação de recursos do Azure

Uma fábrica de dados ou um espaço de trabalho Synapse pode associar-se a uma identidade gerida atribuída pelo sistema para recursos do Azure que representa o recurso. Pode usar esta identidade gerida para 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 de Microsoft Entra para o seu servidor no portal Azure, caso ainda não o tenha feito. O administrador da Microsoft Entra pode ser um utilizador da Microsoft Entra ou um grupo da Microsoft Entra. Se você conceder ao grupo com identidade gerenciada atribuída pelo sistema uma função de administrador, ignore as etapas 3 e 4. O administrador terá acesso total à base de dados.

2. Crie usuários de banco de dados contidos para a identidade gerenciada atribuída ao sistema. Ligue-se ao armazém de dados a partir ou para onde pretende copiar os dados usando ferramentas como o SSMS, com uma identidade Microsoft Entra que tenha pelo menos ALTERAR QUALQUER PERMISSÃO DE UTILIZADOR. Execute o seguinte T-SQL.

   CREATE USER [your_resource_name] FROM EXTERNAL PROVIDER;
   

3. Conceda as permissões necessárias à identidade gerenciada atribuída ao sistema, como você normalmente faz para usuários SQL e outros. Execute o código a seguir ou consulte mais opções aqui. Se quiseres usar o PolyBase para carregar os dados, informa-te sobre a permissão necessária de base de dados.

   EXEC sp_addrolemember db_owner, [your_resource_name];
   

4. Configure um serviço Azure Synapse Analytics ligado.

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 espaço de trabalho Synapse pode ser associado a identidades geridas atribuídas pelo utilizador que representam o recurso. Pode usar esta identidade gerida para 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:

Você também precisa seguir os passos abaixo:

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

2. Crie usuários de banco de dados contidos para a identidade gerenciada atribuída pelo usuário. Ligue-se ao armazém de dados a partir ou para onde pretende copiar os dados usando ferramentas como o SSMS, com uma identidade Microsoft Entra que tenha pelo menos ALTERAR QUALQUER PERMISSÃO DE UTILIZADOR. 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 usuários SQL e outros. Execute o código a seguir ou consulte mais opções aqui. Se quiseres usar o PolyBase para carregar os dados, informa-te sobre a permissão necessária de base de dados.

   EXEC sp_addrolemember db_owner, [your_resource_name];
   

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

5. Configure um serviço Azure Synapse Analytics ligado.

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 antiga

Estas propriedades genéricas são suportadas para um serviço associado Azure Synapse Analytics quando se aplica a versão Legacy:

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 de service principal 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 do principal de serviço para a versão legada

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

Você também precisa seguir as etapas em 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 gerida atribuída pelo sistema, siga a mesma etapa para a versão recomendada em Autenticação de identidade gerida atribuída pelo sistema.

Autenticação de identidade gerida pelo usuário para versões antigas

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

Propriedades do conjunto de dados

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

As seguintes propriedades são suportadas para o conjunto de dados Azure Synapse Analytics:

Exemplo de propriedades de 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 de seções e propriedades disponíveis para definir atividades, consulte o artigo Pipelines . Esta secção fornece uma lista de propriedades suportadas pelo Azure Synapse Analytics source and sink.

Azure Synapse Analytics como fonte

Para copiar dados de Azure Synapse Analytics, defina a propriedade type na fonte Copy Activity para SqlDWSource. As seguintes propriedades são suportadas na seção fonte da Atividade de Cópia:

Observe o seguinte ponto:

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

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 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 destino

Os pipelines Azure Data Factory e Synapse suportam três formas de carregar dados no Azure Synapse Analytics.

• Utilizar a instrução COPY
• Utilizar o PolyBase
• Usar inserção em massa

A maneira mais rápida e escalável de carregar dados é através da instrução COPY ou do PolyBase.

Para copiar dados para Azure Synapse Analytics, defina o tipo de sumidouro em Copy Activity para SqlDWSink. As seguintes propriedades são suportadas na seção sink da atividade de cópia:

Exemplo 1: Azure Synapse Analytics sink

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

Exemplo 2: Dados com inserção ou atualização (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 oferece particionamento de dados integrado para copiar dados em paralelo. Você pode encontrar opções de particionamento de dados na guia Origem da atividade de cópia.

Quando ativas a cópia particionada, a atividade de cópia executa consultas paralelas na tua fonte do Azure Synapse Analytics para carregar os dados por partições. O grau paralelo é controlado pela configuração parallelCopies na atividade de cópia. Por exemplo, se definir parallelCopies para quatro, o serviço gera e executa simultaneamente quatro consultas com base na opção de partição e definições especificadas, e cada consulta recupera uma parte dos dados do seu Azure Synapse Analytics.

Recomenda-se que permita a cópia paralela com partição de dados, especialmente quando carrega grandes quantidades de dados do seu Azure Synapse Analytics. A seguir estão sugeridas configurações para diferentes cenários. Ao copiar dados para o armazenamento de dados baseado em arquivo, é recomendável gravar em uma pasta como vários arquivos (especifique apenas o nome da pasta), caso em que o desempenho é melhor do que gravar em um único arquivo.

Práticas recomendadas para carregar dados com a opção de partição:

1. Escolha uma coluna distinta como coluna de partição (como chave primária ou chave exclusiva) para evitar distorção de dados.
2. Se a tabela tiver partição incorporada, use a opção de partição "Partições físicas da tabela" para obter um melhor desempenho.
3. Se usar Azure Integration Runtime para copiar dados, pode definir "Unidades de Integração de Dados (DIU)" (>4) maiores para utilizar mais recursos computacionais. Verifique os cenários aplicáveis lá.
4. "Grau de paralelismo de cópia controla os números de partição, estabelecer este número demasiado grande pode por vezes prejudicar o desempenho, recomenda-se definir este número como (DIU ou número de nós IR auto-hospedados) * (2 a 4)."
5. Nota: o Azure Synapse Analytics pode executar um máximo de 32 consultas ao mesmo tempo. Definir um "Grau de paralelismo de cópia" muito elevado pode causar um problema de estrangulamento do Synapse.

Exemplo: carga completa a partir de uma tabela grande com partições físicas

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

Exemplo: consulta com partição de 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 partição física, você verá "HasPartition" como "yes".

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

Usar a instrução COPY é uma forma simples e flexível de carregar dados em Azure Synapse Analytics com alto rendimento. Para saber mais detalhes, consulte Carregamento em massa de dados com o comando COPY

• Se os seus dados de origem estiverem em Azure Blob ou Azure Data Lake Storage Gen2, e o formato for compatível com a instrução COPY, pode usar a atividade de cópia para invocar diretamente a instrução COPY e permitir Azure Synapse Analytics extrair os dados da fonte. Para obter detalhes, consulte Cópia direta usando a instrução COPY.
• Se o armazenamento de dados de origem e o formato não forem originalmente suportados pela instrução COPY, use o recurso Cópia em etapas com a instrução COPY em vez disso. O recurso de cópia em fases também proporciona uma melhor taxa de transferência. Converte automaticamente os dados para o formato compatível com instruções COPY, armazena os dados no armazenamento Azure Blob e depois chama a instrução COPY para carregar os dados no Azure Synapse Analytics.

Cópia direta usando a instrução COPY

A instrução Azure Synapse Analytics COPY suporta diretamente o Azure Blob e o Azure Data Lake Storage Gen2. Se os seus dados de origem cumprirem os critérios descritos nesta secção, utilize a instrução COPY para copiar diretamente do armazenamento de dados de origem para o Azure Synapse Analytics. Caso contrário, use cópia em etapas através da 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 estão com os seguintes tipos e métodos de autenticação:

   Tipo de armazenamento de dados de origem suportado	Formato suportado	Tipo de autenticação de origem suportado
   Azure Blob	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 de entidade de serviço (usando ServicePrincipalKey), autenticação de assinatura de acesso compartilhado, autenticação de identidade gerenciada atribuída pelo sistema

   Importante

   • Quando usar autenticação de identidade gerida para o seu serviço ligado ao armazenamento, aprenda as configurações necessárias para Azure Blob e Azure Data Lake Storage Gen2 respetivamente.
   • Se a sua Conta de Armazenamento Azure estiver configurada com o endpoint de serviço VNet, deve usar autenticação de identidade gerida com "permitir serviços confiáveis da Microsoft" ativado no armazenamento, consulte Impacto de usar Endpoints de Serviço VNet com Armazenamento do Azure.

2. As configurações de formato são as seguintes:

   1. Para Parquet: compression pode ser sem compressão, Snappy ou GZip.
   2. Para ORC: compression pode ser sem compressão, zlibou Snappy.
   3. Para texto delimitado:
      1. rowDelimiter é explicitamente definido como caractere único ou "\r\n", o valor padrão não é suportado.
      2. nullValue é deixado como padrão ou definido como string vazia ("").
      3. encodingName é deixado como padrão ou definido como utf-8 ou utf-16.
      4. escapeChar deve ser igual a quoteChar, e não está vazio.
      5. skipLineCount é deixado como padrão ou definido como 0.
      6. compression pode ser sem compressão ou GZip.

3. Se a sua fonte for uma pasta, na atividade de cópia recursive deve estar definida como verdadeiro e wildcardFilename deve ser * ou *.*.

4. wildcardFolderPath, wildcardFilename (exceto *ou *.*), modifiedDateTimeStart, , modifiedDateTimeEndprefix, e enablePartitionDiscoveryadditionalColumns não são especificados.

As seguintes configurações de instrução COPY são suportadas sob allowCopyCommand na atividade de cópia:

"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 em etapas usando a instrução COPY

Quando os seus dados de origem não forem nativamente compatíveis com a instrução COPY, permita a cópia de dados através de um armazenamento temporário Azure Blob ou Azure Data Lake Storage Gen2 (não pode ser Azure Armazenamento Premium). Nesse caso, o serviço converte automaticamente os dados para atender aos requisitos de formato de dados da instrução COPY. Depois, invoca a instrução COPY para carregar dados no Azure Synapse Analytics. Finalmente, ele limpa seus dados temporários do armazenamento. Consulte Cópia por estágios para obter detalhes sobre como copiar dados por meio de staging.

Para usar esta funcionalidade, crie um serviço vinculado Armazenamento de Blobs do Azure ou serviço vinculado Azure Data Lake Storage Gen2 com autenticação por chave de conta ou identidade gerida pelo sistema que se refere à conta de armazenamento Azure como armazenamento interino.

"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"
                }
            }
        }
    }
]

Use o PolyBase para carregar dados no Azure Synapse Analytics

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

• Se os seus dados de origem estiverem em Azure Blob ou Azure Data Lake Storage Gen2, e o formato for compatível com PolyBase, pode usar a atividade de cópia para invocar diretamente o PolyBase e permitir Azure Synapse Analytics extrair os dados da fonte. Para obter detalhes, consulte Cópia direta usando PolyBase.
• Se a sua origem de dados e o respetivo formato não forem suportados originalmente pelo PolyBase, utilize a funcionalidade Cópia em Estágios com PolyBase. O recurso de cópia em fases também proporciona uma melhor taxa de transferência. Converte automaticamente os dados para o formato compatível com PolyBase, armazena-os no armazenamento Azure Blob e depois chama o PolyBase para carregar os dados no Azure Synapse Analytics.

As seguintes configurações do PolyBase são suportadas na polyBaseSettings atividade de cópia:

Cópia direta usando o PolyBase

Azure Synapse Analytics PolyBase suporta diretamente Azure Blob e Azure Data Lake Storage Gen2. Se os seus dados de origem cumprirem os critérios descritos nesta secção, utilize o PolyBase para copiar diretamente do armazenamento de dados de origem para o Azure Synapse Analytics. Caso contrário, use Cópia em etapas 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 é com os seguintes tipos e métodos de autenticação:

   Tipo de armazenamento de dados de origem suportado	Tipo de autenticação de origem suportado
   Azure Blob	Autenticação de chave de conta, autenticação de identidade gerenciada atribuída pelo sistema
   Azure Data Lake Storage Gen2	Autenticação de chave de conta, autenticação de identidade gerenciada atribuída pelo sistema

   Importante

   • Quando usar autenticação de identidade gerida para o seu serviço ligado ao armazenamento, aprenda as configurações necessárias para Azure Blob e Azure Data Lake Storage Gen2 respetivamente.
   • Se a sua Conta de Armazenamento Azure estiver configurada com o endpoint de serviço VNet, deve usar autenticação de identidade gerida com "permitir serviços confiáveis da Microsoft" ativado no armazenamento, consulte Impacto de usar Endpoints de Serviço 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 filtro curinga ("wildcard").
   2. O nome do arquivo está vazio ou aponta para um único arquivo. Se você especificar o nome do 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 string vazia (""), e treatEmptyAsNull é deixado como padrão ou definido como true.
   5. encodingName é deixado como padrão ou definido como utf-8.
   6. quoteChar, escapeChare skipLineCount não são especificados. O PolyBase suporta pular linha de cabeçalho, que pode ser configurada como firstRowAsHeader.
   7. compression pode ser sem compressão, GZipou Esvaziar.

3. Se a origem for uma pasta, recursive deve estar definido como true na atividade de cópia.

4. wildcardFolderPath , wildcardFilename, , modifiedDateTimeStart, modifiedDateTimeEnd, prefix, enablePartitionDiscoverye 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 em etapas usando o PolyBase

Quando os seus dados de origem não forem nativamente compatíveis com o PolyBase, ative a cópia de dados através do staging intermédio do Azure Blob ou Azure Data Lake Storage Gen2 (não pode ser o Azure Armazenamento Premium). Nesse caso, o serviço converte automaticamente os dados para atender aos requisitos de formato de dados do PolyBase. Depois, invoca o PolyBase para carregar dados no Azure Synapse Analytics. Finalmente, ele limpa seus dados temporários do armazenamento. Consulte Cópia por estágios para obter detalhes sobre como copiar dados por meio de staging.

Para utilizar esta funcionalidade, crie um serviço ligado Armazenamento de Blobs do Azure ou serviço ligado Azure Data Lake Storage Gen2 com chave de conta ou autenticação de identidade gerida referente à conta de armazenamento Azure como armazenamento intermédio.

"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 secções seguintes fornecem boas práticas para além das mencionadas em Boas práticas para Azure Synapse Analytics.

Permissão de banco de dados necessária

Para usar o PolyBase, o utilizador que carrega os dados na Azure Synapse Analytics deve ter permissão "CONTROL" na base de dados de destino. Uma maneira de conseguir isso é adicionar o usuário como membro da função db_owner . Aprenda a fazer isso na visão geral Azure Synapse Analytics.

Tamanho da linha e limites de 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 mais informações, consulte Azure Synapse Analytics limites de capacidade de serviço.

Quando os dados de origem tiverem linhas maiores que 1 MB, convém 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 mais pequenas podem então ser carregadas usando PolyBase e fundidas no Azure Synapse Analytics.

Como alternativa, para dados com colunas tão largas, você pode usar não-PolyBase para carregar os dados desativando a configuração "permitir PolyBase".

Azure Synapse Analytics classe de recurso

Para alcançar o melhor rendimento possível, atribua ao utilizador uma classe de recurso maior que carrega os dados no Azure Synapse Analytics via PolyBase.

Solução de problemas do PolyBase

Carregando para coluna decimal

Se os seus dados de origem estiverem em formato de texto ou noutros repositórios não compatíveis com PolyBase (usando cópia encenada e PolyBase), e contiver valor vazio para ser carregado na coluna Decimal do Azure Synapse Analytics, pode obter 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 tipo padrão" (como false) no destino da atividade de cópia nas configurações do PolyBase. "USE_TYPE_DEFAULT" é uma configuração nativa do PolyBase, que especifica como lidar com valores ausentes em arquivos de texto delimitados quando o PolyBase recupera dados do arquivo de texto.

Verifique a propriedade "tableName" no Azure Synapse Analytics

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

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

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

Colunas com valores padrão

Atualmente, o recurso PolyBase aceita apenas o mesmo número de colunas que na tabela de destino. Um exemplo é uma tabela com quatro colunas onde 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 for anulável, os dados de entrada no blob dessa coluna podem estar vazios. Mas isso não pode faltar no conjunto de dados de entrada. O PolyBase insere NULL para valores em falta no Azure Synapse Analytics.

Falha no acesso a arquivos externos

Caso receba o seguinte erro, certifique-se de que está a usar a autenticação de identidade gerida e de que concedeu permissões de Leitor de Dados de Blob de Armazenamento à identidade gerida do espaço de trabalho 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 obter mais informações, consulte Conceder permissões à identidade gerenciada após a criação do espaço de trabalho.

Mapeando propriedades de fluxo de dados

Ao transformar dados no mapeamento do fluxo de dados, pode ler e escrever em tabelas do Azure Synapse Analytics. Para obter mais informações, consulte a transformação de origem e a transformação de coletor no mapeamento de fluxos de dados.

Transformação da fonte

Definições específicas para Azure Synapse Analytics estão disponíveis no separador Opções de Origem da transformação de origem.

Entrada Selecione se você aponta sua fonte para uma tabela (equivalente a Select * from <table-name>) ou insere uma consulta SQL personalizada.

Enable Staging É altamente recomendado que utilize esta opção em cargas de trabalho de produção com fontes do Azure Synapse Analytics. Quando executa uma atividade de fluxo de dados com fontes do Azure Synapse Analytics a partir de um pipeline, ser-lhe-á solicitado um armazenamento de localização staging e irá usá-lo para carregar dados em staging. É o mecanismo mais rápido para carregar dados do Azure Synapse Analytics.

• Quando usar autenticação de identidade gerida para o seu serviço ligado ao armazenamento, aprenda as configurações necessárias para Azure Blob e Azure Data Lake Storage Gen2 respetivamente.
• Se a sua Conta de Armazenamento Azure estiver configurada com o endpoint de serviço VNet, deve usar autenticação de identidade gerida com "permitir serviços confiáveis da Microsoft" ativado no armazenamento, consulte Impacto de usar Endpoints de Serviço VNet com Armazenamento do Azure.
• Quando usas o pool SQL Azure Synapse serverless como fonte, a ativação de staging não é suportada.

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

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

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

Nível de isolamento: O padrão para fontes SQL no mapeamento do fluxo de dados é ler sem confirmação. Você pode alterar o nível de isolamento aqui para um destes valores:

• Leia Comprometido
• Ler Não Comprometido
• Leitura repetível
• Serializável
• Nenhum (ignorar o nível de isolamento)

Transformação do lavatório

Definições específicas para Azure Synapse Analytics estão disponíveis no separador Settings da transformação do lavadoiro.

Método de atualização: determina quais operações são permitidas no destino do banco de dados. O padrão é permitir apenas inserções. Para realizar a atualização, inserção ou eliminação de linhas, é necessário uma transformação de alteração de linha para marcar as linhas para essas ações. Para atualizações, upserts e exclusões, uma coluna ou colunas de chave devem ser definidas para determinar qual linha alterar.

Ação da tabela: Determina se devem ser recriadas ou removidas todas as linhas da tabela de destino antes da gravação.

• Nenhuma: Nenhuma ação será realizada na tabela.
• Recriar: A tabela será descartada e recriada. Necessário apenas ao criar uma nova tabela dinamicamente.
• Truncate: Todas as linhas da tabela de destino serão removidas.

Enable staging: Isto permite carregar em Azure Synapse Analytics SQL Pools usando o comando copy e é recomendado para a maioria dos sinks do Synapse. O armazenamento temporário está configurado na atividade Executar Fluxo de Dados.

• Quando usar autenticação de identidade gerida para o seu serviço ligado ao armazenamento, aprenda as configurações necessárias para Azure Blob e Azure Data Lake Storage Gen2 respetivamente.
• Se a sua Conta de Armazenamento Azure estiver configurada com o endpoint de serviço VNet, deve usar autenticação de identidade gerida com "permitir serviços confiáveis da Microsoft" ativado no armazenamento, consulte Impacto de usar Endpoints de Serviço VNet com Armazenamento do Azure.

Tamanho do lote: Controla quantas linhas são escritas em cada bucket. Lotes maiores melhoram a compactação e a otimização da memória, mas correm o risco de exceções de falta de memória ao armazenar dados em cache.

Usar esquema de destino: Por padrão, uma tabela temporária será criada sob o esquema de destino como etapa de preparação. Como alternativa, pode desmarcar a opção Usar esquema de sink e, em vez disso, em Selecionar esquema de banco de dados do utilizador, especificar um nome de esquema onde o Data Factory criará uma tabela de preparação para carregar dados upstream e limpá-los automaticamente após a conclusão. Verifique se você tem permissão para criar tabela no banco de dados e alterar permissão no esquema.

Scripts SQL Pre e Post: Insira scripts SQL de várias linhas que serão executados antes (pré-processamento) e depois (pós-processamento), quando os dados forem gravados no seu banco de dados Sink.

Processamento da linha de erro

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

• Dados binários ou de cadeia de caracteres seriam truncados na tabela
• Não é possível inserir o valor NULL na coluna
• Falha na conversão ao converter o valor em tipo de dados

Por padrão, uma execução de fluxo de dados falhará no primeiro erro que receber. Você pode escolher Ignorar erros, permitindo que o fluxo de dados seja concluído mesmo que linhas individuais tenham erros. O serviço fornece diferentes opções para você lidar com essas linhas de erro.

Confirmação de transação: escolha se seus dados são gravados em uma única transação ou em lotes. Uma única transação proporcionará um melhor desempenho e nenhum dado gravado será visível para outras pessoas até que a transação seja concluída. As transações em lote têm pior desempenho, mas podem funcionar para grandes conjuntos de dados.

Output rejected data: Se estiver ativado, pode exportar as linhas de erro para um ficheiro CSV no Armazenamento de Blobs do Azure ou numa conta Azure Data Lake Storage Gen2 à sua escolha. Isso gravará as linhas de erro com três colunas adicionais: a operação SQL como INSERT ou UPDATE, o código de erro de fluxo de dados e a mensagem de erro na linha.

Relatar sucesso em caso de erro: Se ativado, o fluxo de dados será marcado como um sucesso, mesmo se forem encontradas linhas de erro.

Propriedades da atividade de consulta

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

Propriedades de atividade GetMetadata

Para saber detalhes sobre as propriedades, verifique a atividade GetMetadata

Mapeamento de tipos de dados para Azure Synapse Analytics

Quando copia dados de ou para o Azure Synapse Analytics, os seguintes mapeamentos são usados dos tipos de dados do Azure Synapse Analytics para os tipos de dados temporários do Azure Data Factory. Estes mapeamentos também são usados ao copiar dados do ou para o Azure Synapse Analytics usando pipelines Synapse, uma vez que os pipelines também implementam o Azure Data Factory dentro do Azure Synapse. Consulte Mapeamentos de esquema e tipos de dados para saber como Copiar Atividade mapeia o esquema de origem e o tipo de dados para o destino.

Atualizar a versão do Azure Synapse Analytics

Para atualizar a versão do Azure Synapse Analytics, na página Edit linked service, selecione Recommended em Version e configure o serviço associado consultando as propriedades do Linked service 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 legada.

Conteúdos relacionados

Para obter uma lista de repositórios de dados suportados como fontes e destinos pela atividade de cópia, consulte repositórios e formatos de dados suportados.