Copiar dados do PostgreSQL usando o Azure Data Factory ou o Synapse Analytics

Artigo
11/27/2024

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma avaliação gratuita!

Este artigo descreve como usar a atividade de cópia nos pipelines do Azure Data Factory e do Azure Synapse Analytics para copiar dados de um banco de dados do PostgreSQL. Ele amplia o artigo Visão geral da atividade de cópia que apresenta uma visão geral da atividade de cópia.

Importante

O novo conector PostgreSQL oferece suporte aprimorado ao PostgreSQL nativo. Se você estiver usando o conector PostgreSQL herdado em sua solução, atualize o conector do PostgreSQL antes de 31 de outubro de 2024. Consulte esta seção para obter detalhes sobre a diferença entre a versão herdada e a versão mais recente.

Funcionalidades com suporte

Esse conector do PostgreSQL é compatível com as seguintes funcionalidades:

Funcionalidades com suporte	IR
Atividade de cópia (origem/-)	① ②
Atividade de pesquisa	① ②

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

Para obter uma lista de armazenamentos de dados com suporte como origens/coletores da atividade de cópia, confira a tabela Armazenamentos de dados com suporte.

Especificamente, esse conector PostgreSQL tem suporte para o PostgreSQL versão 12 e superior.

Pré-requisitos

Se o armazenamento de dados estiver localizado dentro de uma rede local, em uma rede virtual do Azure ou na Amazon Virtual Private Cloud, você precisará configurar um runtime de integração auto-hospedada para se conectar a ele.

Se o armazenamento de dados for um serviço de dados de nuvem gerenciado, você poderá usar o Azure Integration Runtime. Se o acesso for restrito aos IPs que estão aprovados nas regras de firewall, você poderá adicionar IPs do Azure Integration Runtime à lista de permissões.

Você também pode usar o recurso de runtime de integração da rede virtual gerenciada no Azure Data Factory para acessar a rede local sem instalar e configurar um runtime de integração auto-hospedada.

Para obter mais informações sobre os mecanismos de segurança de rede e as opções compatíveis com o Data Factory, consulte Estratégias de acesso a dados.

O Integration Runtime fornece um driver PostgreSQL interno a partir da versão 3.7, portanto, não é necessário instalar nenhum driver manualmente.

Introdução

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

Criar um serviço vinculado para PostgreSQL usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado ao PostgreSQL na interface do usuário do portal do Azure.

Navegue até a guia Gerenciar em seu workspace do Azure Data Factory ou do Synapse, selecione Serviços Vinculados e clique em Novo:
- Azure Data Factory
- Azure Synapse
Procure por PostgreSQL e selecione o conector do PostgreSQL.
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 que se seguem fornecem detalhes sobre as propriedades que são usadas para definir entidades do Data Factory específicas ao conector do PostgreSQL.

Propriedades do serviço vinculado

As propriedades a seguir têm suporte para o serviço vinculado do PostgreSQL:

Propriedade	Descrição	Obrigatório
tipo	A propriedade type deve ser definida como: PostgreSqlV2	Yes
Servidor	Especifica o nome do host e, opcionalmente, a porta, na qual o PostgreSQL está em execução.	Yes
porta	A porta TCP do servidor PostgreSQL.	Não
Banco de Dados	O banco de dados PostgreSQL ao qual se conectar.	Yes
Nome de Usuário	O nome de usuário usado para se conectar. Não é necessário se estiver usando o IntegratedSecurity.	Yes
password	A senha para se conectar. Não é necessário se estiver usando o IntegratedSecurity.	Yes
sslMode	Controla se o SSL é usado, dependendo do suporte ao servidor. - Desabilitar: o SSL é desabilitado. Se o servidor exigir SSL, a conexão falhará. - Permitir: prefere conexões sem SSL se o servidor permitir, mas aceita conexões SSL. - Preferir: prefere conexões SSL se o servidor permitir, mas aceita conexões sem SSL. - Exigir: a conexão falha se o servidor não oferecer suporte ao SSL. - Verify-ca: a conexão falha se o servidor não oferecer suporte ao SSL. Também verifica o certificado do servidor. - Verify-full: a conexão falha se o servidor não oferecer suporte ao SSL. Também verifica o certificado do servidor com o nome do host. Opções: Desabilitar (0)/Permitir (1)/Preferir (2) (Padrão)/Exigir (3)/Verify-ca (4)/Verify-full (5)	Não
authenticationType	Tipo de autenticação para se conectar ao banco de dados. Só dá suporte ao Básico.	Yes
connectVia	O Integration Runtime a ser usado para se conectar ao armazenamento de dados. Saiba mais na seção Pré-requisitos. Se não for especificado, ele usa o Integration Runtime padrão do Azure.	Não
Propriedades de conexão adicionais:
esquema	Define o caminho de pesquisa do esquema.	Não
pooling	Indica se o pooling de conexões deve ser utilizado.	Não
connectionTimeout	O tempo de espera (em segundos) para tentar estabelecer uma conexão antes de encerrar a tentativa e gerar um erro.	Não
commandTimeout	O tempo de espera (em segundos) para tentar executar um comando antes de encerrar a tentativa e gerar um erro. Definido como zero para infinito.	Não
trustServerCertificate	Indica se o certificado do servidor deve ser considerado confiável sem validação.	Não
sslCertificate	Local de um certificado de cliente que será enviado ao servidor.	Não
sslKey	Local de uma chave de cliente para um certificado de cliente que será enviado ao servidor.	Não
sslPassword	Senha de uma chave para um certificado de cliente.	Não
readBufferSize	Determina o tamanho do buffer interno que o Npgsql usa durante a leitura. Aumentar pode melhorar o desempenho ao transferir valores grandes do banco de dados.	Não
logParameters	Quando habilitado, os valores do parâmetro são registrados no momento da execução dos comandos.	Não
timezone	Obtém ou define o fuso horário da sessão.	Não
encoding	Obtém ou define a codificação .NET que será usada para codificar/decodificar dados de cadeia de caracteres do PostgreSQL.	Não

Observação

Para ter uma verificação SSL completa por meio da conexão ODBC ao usar o Integration Runtime auto-hospedado, você deve usar uma conexão de tipo ODBC em vez do conector PostgreSQL explicitamente e realizar a seguinte configuração:

Configure o DSN em todos os servidores SHIR.
Coloque o certificado adequado para PostgreSQL em C:\Windows\ServiceProfiles\DIAHostService\AppData\Roaming\postgresql\root.crt nos servidores SHIR. É aqui que o driver ODBC procura > o certificado SSL para verificar quando ele se conecta com o banco de dados.
Na conexão do seu data factory, use uma conexão de tipo ODBC, com a sua cadeia de conexão apontando para o DSN criado nos seus servidores SHIR.

Exemplo:

{
    "name": "PostgreSqlLinkedService",
    "properties": {
        "type": "PostgreSqlV2",
        "typeProperties": {
            "server": "<server>",
            "port": 5432,
            "database": "<database>",
            "username": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            },
            "sslmode": <sslmode>,
            "authenticationType": "Basic"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo: armazenar a senha no Azure Key Vault

{
    "name": "PostgreSqlLinkedService",
    "properties": {
        "type": "PostgreSqlV2",
        "typeProperties": {
            "server": "<server>",
            "port": 5432,
            "database": "<database>",
            "username": "<username>",
            "password": {
                "type": "AzureKeyVaultSecret",
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>",
                    "type": "LinkedServiceReference"
                },
                "secretName": "<secretName>"
            }
            "sslmode": <sslmode>,
            "authenticationType": "Basic"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Propriedades do conjunto de dados

Para obter uma lista completa das seções e propriedades disponíveis para definir os conjuntos de dados, confira o artigo sobre conjuntos de dados. Esta seção fornece uma lista das propriedades com suporte pelo conjunto de dados do PostgreSQL.

Para copiar dados do PostgreSQL, as seguintes propriedades são compatíveis:

Propriedade	Descrição	Obrigatório
tipo	A propriedade Type do conjunto de dados deve ser definida como: PostgreSqlV2Table.	Yes
esquema	Nome do esquema.	Não (se "query" na fonte da atividade for especificada)
tabela	Nome da tabela.	Não (se "query" na fonte da atividade for especificada)

Exemplo

{
    "name": "PostgreSQLDataset",
    "properties":
    {
        "type": "PostgreSqlV2Table",
        "linkedServiceName": {
            "referenceName": "<PostgreSQL linked service name>",
            "type": "LinkedServiceReference"
        },
        "annotations": [],
        "schema": [],
        "typeProperties": {
            "schema": "<schema name>",
            "table": "<table name>"
        }
    }
}

Se você estava usando o conjunto de dados com tipos RelationalTable, ele ainda tem suporte como está, mas é recomendável usar o novo de agora em diante.

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 das propriedades com suporte pela fonte do PostgreSQL.

PostgreSQL como fonte

Para a cópia de dados do PostgreSQL, as propriedades a seguir têm suporte na seção de origem da atividade de cópia:

Propriedade	Descrição	Obrigatório
tipo	A propriedade type da fonte da atividade de cópia deve ser definida como: PostgreSqlV2Source	Yes
Consulta	Utiliza a consulta SQL personalizada para ler os dados. Por exemplo: `"query": "SELECT * FROM \"MySchema\".\"MyTable\""`.	Não (se "tableName" no conjunto de dados for especificado)
queryTimeout	O tempo de espera antes de encerrar a tentativa de executar um comando ou gerar um erro. O padrão é 120 minutos. Se um parâmetro for definido para essa propriedade, os valores permitidos são o intervalo de tempo, como "02:00:00" (120 minutos). Para obter mais informações, confira CommandTimeout. Se `commandTimeout` e `queryTimeout` estiverem configurados, `queryTimeout` terá precedência.	Não

Observação

Os nomes de esquema e tabela diferenciam maiúsculas de minúsculas. Coloque-os em "" (aspas duplas) na consulta.

Exemplo:

"activities":[
    {
        "name": "CopyFromPostgreSQL",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<PostgreSQL input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "PostgreSqlV2Source",
                "query": "SELECT * FROM \"MySchema\".\"MyTable\"",
                "queryTimeout": "00:10:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Se você estava usando a fonte com tipos RelationalSource, ela ainda tem suporte como está, mas é recomendável usar a nova no futuro.

Mapeamento de tipo de dados para PostgreSQL

Ao copiar dados do PostgreSQL, os seguintes mapeamentos são usados de tipos de dados do PostgreSQL para tipos de dados provisórios usados internamente com o serviço. Consulte Mapeamentos de tipo de dados e esquema para saber mais sobre como a atividade de cópia mapeia o tipo de dados e esquema de origem para o coletor.

Tipo de dados do PostgreSQL	Tipo de dados provisório do serviço	Tipo de dados de serviço provisório para PostgreSQL (herdado)
`SmallInt`	`Int16`	`Int16`
`Integer`	`Int32`	`Int32`
`BigInt`	`Int64`	`Int64`
`Decimal` (Precisão <= 28)	`Decimal`	`Decimal`
`Decimal` (Precisão > 28)	Sem suporte	`String`
`Numeric`	`Decimal`	`Decimal`
`Real`	`Single`	`Single`
`Double`	`Double`	`Double`
`SmallSerial`	`Int16`	`Int16`
`Serial`	`Int32`	`Int32`
`BigSerial`	`Int64`	`Int64`
`Money`	`Decimal`	`String`
`Char`	`String`	`String`
`Varchar`	`String`	`String`
`Text`	`String`	`String`
`Bytea`	`Byte[]`	`Byte[]`
`Timestamp`	`DateTime`	`DateTime`
`Timestamp with time zone`	`DateTime`	`String`
`Date`	`DateTime`	`DateTime`
`Time`	`TimeSpan`	`TimeSpan`
`Time with time zone`	`DateTimeOffset`	`String`
`Interval`	`TimeSpan`	`String`
`Boolean`	`Boolean`	`Boolean`
`Point`	`String`	`String`
`Line`	`String`	`String`
`Iseg`	`String`	`String`
`Box`	`String`	`String`
`Path`	`String`	`String`
`Polygon`	`String`	`String`
`Circle`	`String`	`String`
`Cidr`	`String`	`String`
`Inet`	`String`	`String`
`Macaddr`	`String`	`String`
`Macaddr8`	`String`	`String`
`Tsvector`	`String`	`String`
`Tsquery`	`String`	`String`
`UUID`	`Guid`	`Guid`
`Json`	`String`	`String`
`Jsonb`	`String`	`String`
`Array`	`String`	`String`
`Bit`	`Byte[]`	`Byte[]`
`Bit varying`	`Byte[]`	`Byte[]`
`XML`	`String`	`String`
`IntArray`	`String`	`String`
`TextArray`	`String`	`String`
`NumericArray`	`String`	`String`
`DateArray`	`String`	`String`
`Range`	`String`	`String`
`Bpchar`	`String`	`String`

Pesquisar propriedades de atividade

Para saber detalhes sobre as propriedades, verifique Pesquisar atividade.

Atualizar o conector do PostgreSQL

Estas são as etapas que ajudarão você a atualizar o conector do PostgreSQL:

Crie um novo serviço vinculado do PostgreSQL e o configure consultando as Propriedades do serviço vinculado.
O mapeamento de tipo de dados para o serviço vinculado mais recente do PostgreSQL é diferente do da versão herdada. Para saber qual é o mapeamento de tipo de dados mais recente, confira Mapeamento de tipo de dados para PostgreSQL.

Diferenças entre o PostgreSQL e o PostgreSQL (herdado)

A tabela a seguir mostra as diferenças de mapeamento de tipo de dados entre o PostgreSQL e o PostgreSQL (herdado).

Tipo de dados do PostgreSQL	Tipo de dados de serviço provisório para PostgreSQL	Tipo de dados de serviço provisório para PostgreSQL (herdado)
Quantia	Decimal	String
Carimbo de data/hora com fuso horário	Datetime	String
Hora com fuso horário	DateTimeOffset	String
Intervalo	TimeSpan	String
BigDecimal	Sem suporte. Como alternativa, use a função `to_char()` para converter BigDecimal em String.	String

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

Compartilhar via

Copiar dados do PostgreSQL usando o Azure Data Factory ou o Synapse Analytics

Funcionalidades com suporte

Pré-requisitos

Introdução

Criar um serviço vinculado para PostgreSQL usando a interface do usuário

Detalhes da configuração do conector

Propriedades do serviço vinculado

Propriedades do conjunto de dados

Propriedades da atividade de cópia

PostgreSQL como fonte

Mapeamento de tipo de dados para PostgreSQL

Pesquisar propriedades de atividade

Atualizar o conector do PostgreSQL

Diferenças entre o PostgreSQL e o PostgreSQL (herdado)

Comentários

Recursos adicionais

Compartilhar via

Copiar dados do PostgreSQL usando o Azure Data Factory ou o Synapse Analytics

Funcionalidades com suporte

Pré-requisitos

Introdução

Criar um serviço vinculado para PostgreSQL usando a interface do usuário

Detalhes da configuração do conector

Propriedades do serviço vinculado

Propriedades do conjunto de dados

Propriedades da atividade de cópia

PostgreSQL como fonte

Mapeamento de tipo de dados para PostgreSQL

Pesquisar propriedades de atividade

Atualizar o conector do PostgreSQL

Diferenças entre o PostgreSQL e o PostgreSQL (herdado)

Conteúdo relacionado

Comentários

Recursos adicionais