Copiar dados de e para o Salesforce usando o Azure Data Factory ou o Azure Synapse Analytics

Artigo
10/01/2024

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Gorjeta

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

Este artigo descreve como usar a Atividade de Cópia no Azure Data Factory e nos pipelines do Azure Synapse para copiar dados de e para o Salesforce. Ele se baseia no artigo Visão geral da atividade de cópia que apresenta uma visão geral da atividade de cópia.

Importante

O novo conector do Salesforce oferece suporte nativo aprimorado ao Salesforce. Se você estiver usando o Salesforce connector herdado em sua solução, atualize seu Salesforce connector antes de 11 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.

Capacidades suportadas

Este conector Salesforce é compatível com os seguintes recursos:

Capacidades suportadas	IR
Atividade de cópia (origem/coletor)	(1) (2)
Atividade de Pesquisa	(1) (2)

(1) Tempo de execução de integração do Azure (2) Tempo de execução de integração auto-hospedado

Para obter uma lista de armazenamentos de dados suportados como fontes ou coletores, consulte a tabela Armazenamentos de dados suportados.

Especificamente, esse conector do Salesforce é compatível:

Edições Salesforce Developer, Professional, Enterprise ou Unlimited.
Copiar dados de e para o domínio personalizado (o domínio personalizado pode ser configurado em ambientes de produção e sandbox).

Você pode definir explicitamente a versão da API usada para ler/gravar dados por meio apiVersion da propriedade no serviço vinculado. Quando você está copiando dados para o Salesforce, o conector usa BULK API 2.0.

Pré-requisitos

A permissão da API deve ser habilitada no Salesforce.
Você precisa configurar os aplicativos conectados no portal do Salesforce consultando este documento oficial ou nossa diretriz passo a passo na recomendação deste artigo.
Importante
- O usuário de execução deve ter a permissão Somente API.
- O tempo de expiração do Token de Acesso pode ser alterado por meio de políticas de sessão em vez do token de atualização.

Limites da API em massa do Salesforce 2.0

Usamos o Salesforce Bulk API 2.0 para consultar e ingerir dados. Na API em massa 2.0, os lotes são criados para você automaticamente. Você pode enviar até 15.000 lotes por período de 24 horas. Se os lotes excederem o limite, você encontrará falhas.

Na API em massa 2.0, apenas os trabalhos de ingestão consomem lotes. Os trabalhos de consulta não. Para obter detalhes, consulte Como as solicitações são processadas no Guia do desenvolvedor da API em massa 2.0.

Para obter mais informações, consulte a seção "Limites gerais" em Limites do desenvolvedor do Salesforce.

Começar agora

Para executar a atividade Copiar com um pipeline, você pode usar uma das seguintes ferramentas ou SDKs:

Criar um serviço vinculado ao Salesforce usando a interface do usuário

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

Navegue até a guia Gerenciar em seu espaço de trabalho do Azure Data Factory ou Synapse e selecione Serviços Vinculados e clique em Novo:
- Fábrica de Dados do Azure
- Azure Synapse
Pesquise o Salesforce e selecione o conector Salesforce.
Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

Detalhes de configuração do conector

As seções a seguir fornecem detalhes sobre as propriedades usadas para definir entidades específicas para o conector Salesforce.

Propriedades do serviço vinculado

As propriedades a seguir são suportadas para o serviço vinculado do Salesforce.

Property	Descrição	Obrigatório
tipo	A propriedade type deve ser definida como SalesforceV2.	Sim
environmentUrl	Especifique a URL da instância do Salesforce. Por exemplo, especifique `"https://<domainName>.my.salesforce.com"` para copiar dados do domínio personalizado. Saiba como configurar ou visualizar seu domínio personalizado referente a este artigo.	Sim
authenticationType	Tipo de autenticação usado para se conectar ao Salesforce. O valor permitido é OAuth2ClientCredentials.	Sim
clientId	Especifique a ID do cliente do aplicativo conectado Salesforce OAuth 2.0. Para obter mais informações, consulte este artigo	Sim
clientSecret	Especifique o segredo do cliente do aplicativo conectado Salesforce OAuth 2.0. Para obter mais informações, consulte este artigo	Sim
apiVersion	Especifique a versão 2.0 do Salesforce Bulk API a ser usada, por exemplo, `52.0`. A API em massa 2.0 suporta apenas a versão >da API = 47.0. Para saber mais sobre a versão 2.0 da API em massa, consulte o artigo. Ocorre uma falha se você usar uma versão inferior da API.	Sim
ConecteVia	O tempo de execução de integração a ser usado para se conectar ao armazenamento de dados. Se não for especificado, ele usará o Tempo de Execução de Integração do Azure padrão.	Não

Exemplo: armazenar credenciais

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "SalesforceV2",
        "typeProperties": {
            "environmentUrl": "<environment URL>",
            "authenticationType": "OAuth2ClientCredentials",
            "clientId": "<client ID>",
            "clientSecret": {
                "type": "SecureString",
                "value": "<client secret>"
            },
            "apiVersion": "<API Version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo: Armazenar credenciais no Cofre da Chave

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "SalesforceV2",
        "typeProperties": {
            "environmentUrl": "<environment URL>",
            "authenticationType": "OAuth2ClientCredentials",
            "clientId": "<client ID>",
            "clientSecret": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of client secret in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "apiVersion": "<API Version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo: Armazenar credenciais no Cofre da Chave, bem como environmentUrl e clientId

Ao fazer o armazenamento de credenciais no Cofre da Chave, bem como environmentUrl e clientId, você pode usar mais a interface do usuário para editar as configurações. A caixa de seleção Especificar conteúdo dinâmico no formato JSON deve ser marcada e essa configuração deve ser feita manualmente. A vantagem desse cenário é que você pode derivar todas as definições de configuração do Cofre da Chave em vez de parametrizar qualquer coisa aqui.

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "SalesforceV2",
        "typeProperties": {
            "environmentUrl": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of environment URL in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "authenticationType": "OAuth2ClientCredentials",
            "clientId": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of client ID in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "clientSecret": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of client secret in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "apiVersion": "<API Version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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. Esta seção fornece uma lista de propriedades suportadas pelo conjunto de dados do Salesforce.

Para copiar dados de e para o Salesforce, defina a propriedade type do conjunto de dados como SalesforceV2Object. As seguintes propriedades são suportadas.

Property	Descrição	Obrigatório
tipo	A propriedade type deve ser definida como SalesforceV2Object.	Sim
objectApiName	O nome do objeto Salesforce do qual recuperar dados. A versão de tempo de execução de integração auto-hospedada aplicável é 5.44.8984.1 ou superior.	Não para fonte (se "consulta" na fonte for especificado), Sim para coletor
reportId	A ID do relatório do Salesforce do qual recuperar dados. Não é suportado na pia. Há limitações quando você usa relatórios. A versão de tempo de execução de integração auto-hospedada aplicável é 5.44.8984.1 ou superior.	Não para origem (se "consulta" na fonte for especificado), não suporta coletor

Importante

A parte "__c" do Nome da API é necessária para qualquer objeto personalizado.

Nome da API de conexão do Salesforce

Exemplo:

{
    "name": "SalesforceDataset",
    "properties": {
        "type": "SalesforceV2Object",
        "typeProperties": {
            "objectApiName": "MyTable__c"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Salesforce linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

Propriedades da atividade Copy

Para obter uma lista completa de seções e propriedades disponíveis para definir atividades, consulte o artigo Pipelines . Esta seção fornece uma lista de propriedades compatíveis com a origem e o coletor do Salesforce.

Salesforce como tipo de origem

Para copiar dados do Salesforce, defina o tipo de origem na atividade de cópia como SalesforceV2Source. As propriedades a seguir são suportadas na seção copiar fonte de atividade.

Property	Descrição	Obrigatório
tipo	A propriedade type da fonte de atividade de cópia deve ser definida como SalesforceV2Source.	Sim
query	Use a consulta personalizada para ler dados. Você só pode usar a consulta SOQL (Salesforce Object Query Language) com limitações. Para limitações de SOQL, consulte este artigo. Se a consulta não for especificada, todos os dados do objeto Salesforce especificado em "objectApiName/reportId" no conjunto de dados serão recuperados.	Não (se "objectApiName/reportId" no conjunto de dados for especificado)
includeDeletedObjects	Indica se os registros existentes devem ser consultados ou consultados todos os registros, incluindo os excluídos. Se não for especificado, o comportamento padrão será false. Valores permitidos: false (padrão), true.	Não

Importante

A parte "__c" do Nome da API é necessária para qualquer objeto personalizado.

Lista de nomes da API de conexão do Salesforce

Exemplo:

"activities":[
    {
        "name": "CopyFromSalesforce",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Salesforce input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SalesforceV2Source",
                "query": "SELECT Col_Currency__c, Col_Date__c, Col_Email__c FROM AllDataType__c",
                "includeDeletedObjects": false
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Salesforce como um tipo de coletor

Para copiar dados para o Salesforce, defina o tipo de coletor na atividade de cópia como SalesforceV2Sink. As propriedades a seguir são suportadas na seção coletor de atividade de cópia.

Property	Descrição	Obrigatório
tipo	A propriedade type do coletor de atividade de cópia deve ser definida como SalesforceV2Sink.	Sim
writeBehavior	O comportamento de gravação para a operação. Os valores permitidos são Insert e Upsert.	Não (o padrão é Inserir)
externalIdFieldName	O nome do campo ID externo para a operação de upsert. O campo especificado deve ser definido como "Campo de ID externo" no objeto Salesforce. Ele não pode ter valores NULL nos dados de entrada correspondentes.	Sim para "Upsert"
writeBatchSize	A contagem de linhas de dados gravados no Salesforce em cada lote. Sugira definir esse valor de 10.000 a 200.000. Poucas linhas em cada lote reduzem o desempenho da cópia. Muitas linhas em cada lote podem causar o tempo limite da API.	Não (o padrão é 100.000)
ignoreNullValues	Indica se os valores NULL devem ser ignorados dos dados de entrada durante uma operação de gravação. Os valores permitidos são true e false. - True: Deixe os dados no objeto de destino inalterados quando você fizer uma operação de upsert ou atualização. Insira um valor padrão definido quando você fizer uma operação de inserção. - False: atualize os dados no objeto de destino para NULL quando você fizer uma operação de upsert ou atualização. Insira um valor NULL quando você fizer uma operação de inserção.	Não (o padrão é false)
maxConcurrentConnections	O limite superior de conexões simultâneas estabelecidas para o armazenamento de dados durante a execução da atividade. Especifique um valor somente quando quiser limitar conexões simultâneas.	Não

Exemplo: coletor do Salesforce em uma atividade de cópia

"activities":[
    {
        "name": "CopyToSalesforce",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Salesforce output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "SalesforceV2Sink",
                "writeBehavior": "Upsert",
                "externalIdFieldName": "CustomerId__c",
                "writeBatchSize": 10000,
                "ignoreNullValues": true
            }
        }
    }
]

Mapeamento de tipo de dados para Salesforce

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

Tipo de dados do Salesforce	Tipo de dados provisórios de serviço
Número automático	String
Caixa de verificação	Boolean
Moeda	Decimal
Date	DateTime
Data/Hora	DateTime
Correio Eletrónico	String
ID	String
Relação de pesquisa	String
Lista de opções de seleção múltipla	String
Número	Decimal
Percentagem	Decimal
Telefone	String
Picklist	String
Texto	String
Área de Texto	String
Área de texto (longa)	String
Área de texto (Rich)	String
Texto (encriptado)	String
URL	String

Nota

O tipo Número do Salesforce está mapeando para o tipo Decimal nos pipelines do Azure Data Factory e do Azure Synapse como um tipo de dados provisório de serviço. O tipo decimal honra a precisão e a escala definidas. Para dados cujas casas decimais excedem a escala definida, seu valor é arredondado em dados de visualização e cópia. Para evitar essa perda de precisão nos pipelines do Azure Data Factory e do Azure Synapse, considere aumentar as casas decimais para um valor razoavelmente grande na página Edição de Definição de Campo Personalizado do Salesforce.

Propriedades da atividade de pesquisa

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

Atualizar o serviço vinculado do Salesforce

Aqui estão as etapas que ajudam você a atualizar seu serviço vinculado e consultas relacionadas:

Configure os aplicativos conectados no portal do Salesforce consultando Pré-requisitos.
Crie um novo serviço vinculado do Salesforce e configure-o consultando as propriedades do serviço vinculado. Você também precisa atualizar manualmente os conjuntos de dados existentes que dependem do antigo serviço vinculado, editando cada conjunto de dados para usar o novo serviço vinculado.
Se você usar a consulta SQL na fonte de atividade de cópia ou na atividade de pesquisa que se refere ao serviço vinculado herdado, será necessário convertê-las para a consulta SOQL. Saiba mais sobre a consulta SOQL do Salesforce como um tipo de origem e a Salesforce Object Query Language (SOQL).
readBehavior é substituído por includeDeletedObjects na fonte da atividade de cópia ou na atividade de pesquisa. Para obter a configuração detalhada, consulte Salesforce como um tipo de origem.

Diferenças entre Salesforce e Salesforce (legado)

O conector Salesforce oferece novas funcionalidades e é compatível com a maioria dos recursos do conector Salesforce (legado). A tabela a seguir mostra as diferenças de recursos entre o Salesforce e o Salesforce (legado).

Salesforce	Salesforce (legado)
Ofereça suporte ao SOQL no Salesforce Bulk API 2.0. Para consultas SOQL: • As cláusulas GROUP BY, LIMIT, ORDER BY, OFFSET ou TYPEOF não são suportadas. • Funções agregadas como COUNT() não são suportadas, você pode usar relatórios do Salesforce para implementá-las. • As funções de data nas cláusulas GROUP BY não são suportadas, mas são suportadas na cláusula WHERE. • Não há suporte para campos de endereço compostos ou campos compostos de geolocalização. Como alternativa, consulte os componentes individuais dos campos compostos. • As consultas de relacionamento entre pais não são suportadas, enquanto as consultas de relacionamento entre pais são suportadas.	Suporta sintaxe SQL e SOQL.
Não há suporte para objetos que contêm campos binários ao especificar consultas.	Objetos que contêm campos binários são suportados ao especificar consulta.
Ofereça suporte a objetos dentro da API em massa ao especificar consulta.	Ofereça suporte a objetos que não são suportados com a API em massa ao especificar a consulta.
Relatório de suporte selecionando um ID de relatório.	Ofereça suporte à sintaxe de consulta de relatório, como `{call "<report name>"}`.

Para obter uma lista de armazenamentos de dados suportados como fontes e coletores pela atividade de cópia, consulte Armazenamentos de dados suportados.

Partilhar via

Copiar dados de e para o Salesforce usando o Azure Data Factory ou o Azure Synapse Analytics

Capacidades suportadas

Pré-requisitos

Limites da API em massa do Salesforce 2.0

Começar agora

Criar um serviço vinculado ao Salesforce usando a interface do usuário

Detalhes de configuração do conector

Propriedades do serviço vinculado

Propriedades do conjunto de dados

Propriedades da atividade Copy

Salesforce como tipo de origem

Salesforce como um tipo de coletor

Mapeamento de tipo de dados para Salesforce

Propriedades da atividade de pesquisa

Atualizar o serviço vinculado do Salesforce

Diferenças entre Salesforce e Salesforce (legado)

Comentários

Recursos adicionais

Partilhar via

Copiar dados de e para o Salesforce usando o Azure Data Factory ou o Azure Synapse Analytics

Capacidades suportadas

Pré-requisitos

Limites da API em massa do Salesforce 2.0

Começar agora

Criar um serviço vinculado ao Salesforce usando a interface do usuário

Detalhes de configuração do conector

Propriedades do serviço vinculado

Propriedades do conjunto de dados

Propriedades da atividade Copy

Salesforce como tipo de origem

Salesforce como um tipo de coletor

Mapeamento de tipo de dados para Salesforce

Propriedades da atividade de pesquisa

Atualizar o serviço vinculado do Salesforce

Diferenças entre Salesforce e Salesforce (legado)

Conteúdos relacionados

Comentários

Recursos adicionais