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

Artigo
10/15/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 conector Salesforce V2 oferece suporte nativo aprimorado ao Salesforce. Se você estiver usando o conector Salesforce V1 em sua solução, é recomendável atualizar seu conector Salesforce o mais rápido possível. Consulte esta seção para obter detalhes sobre a diferença entre V2 e V1.

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 a produção, área restrita e domínio personalizado do Salesforce.

Nota

Esta função suporta a cópia de qualquer esquema dos ambientes Salesforce mencionados acima, incluindo o NPSP ( Nonprofit Success Pack ).

O conector Salesforce é criado com base na API REST/Bulk do Salesforce. Ao copiar dados do Salesforce, o conector escolhe automaticamente entre APIs REST e em massa com base no tamanho dos dados - quando o conjunto de resultados é grande, a API em massa é usada para melhor desempenho; Você pode definir explicitamente a versão da API usada para ler/gravar dados por meio apiVersion da propriedade no serviço vinculado. Ao copiar dados para o Salesforce, o conector usa a API BULK v1.

Nota

O conector não define mais a versão padrão para a API do Salesforce. Para compatibilidade com versões anteriores, se uma versão padrão da API foi definida antes, ela continua funcionando. O valor padrão é 45.0 para origem e 40.0 para coletor.

Pré-requisitos

A permissão da API deve ser habilitada no Salesforce.

Limites de solicitação do Salesforce

O Salesforce tem limites para o total de solicitações de API e solicitações de API simultâneas. Tenha em conta os seguintes pontos:

Se o número de solicitações simultâneas exceder o limite, a limitação ocorrerá e você verá falhas aleatórias.
Se o número total de solicitações exceder o limite, a conta do Salesforce será bloqueada por 24 horas.

Você também pode receber a mensagem de erro "REQUEST_LIMIT_EXCEEDED" em ambos os cenários. Para obter mais informações, consulte a seção "Limites de solicitação de API" 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 Salesforce.	Sim
environmentUrl	Especifique a URL da instância do Salesforce. - O padrão é `"https://login.salesforce.com"`. - Para copiar dados da sandbox, especifique `"https://test.salesforce.com"`. - Para copiar dados de domínio personalizado, especifique, por exemplo, `"https://[domain].my.salesforce.com"`.	Não
nome de utilizador	Especifique um nome de usuário para a conta de usuário.	Sim
password	Especifique uma senha para a conta de usuário. Marque este campo como um SecureString para armazená-lo com segurança ou faça referência a um segredo armazenado no Cofre de Chaves do Azure.	Sim
securityToken	Especifique um token de segurança para a conta de usuário. Para saber mais sobre tokens de segurança em geral, consulte Segurança e a API. O token de segurança só pode ser ignorado se você adicionar o IP do Integration Runtime à lista de endereços IP confiáveis no Salesforce. Ao usar o IR do Azure, consulte Endereços IP do Azure Integration Runtime. Para obter instruções sobre como obter e redefinir um token de segurança, consulte Obter um token de segurança. Marque este campo como um SecureString para armazená-lo com segurança ou faça referência a um segredo armazenado no Cofre de Chaves do Azure.	Não
apiVersion	Especifique a versão REST/Bulk API do Salesforce a ser usada, por exemplo, `52.0`.	Não
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": "Salesforce",
        "typeProperties": {
            "username": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            },
            "securityToken": {
                "type": "SecureString",
                "value": "<security token>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo: Armazenar credenciais no Cofre da Chave

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "username": "<username>",
            "password": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of password in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "securityToken": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of security token in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo: Armazenar credenciais no Cofre da Chave, bem como environmentUrl e nome de usuário

Observe que, ao fazer isso, você não poderá mais usar a interface do usuário para editar as configurações. A caixa de seleção Especificar conteúdo dinâmico no formato JSON será marcada, e você terá que editar essa configuração inteiramente manualmente. A vantagem é que você pode derivar TODAS as definições de configuração do Cofre de Chaves em vez de parametrizar qualquer coisa aqui.

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "environmentUrl": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of environment URL in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "username": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of username in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "password": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of password in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "securityToken": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of security token in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            }
        },
        "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 SalesforceObject. As seguintes propriedades são suportadas.

Property	Descrição	Obrigatório
tipo	A propriedade type deve ser definida como SalesforceObject.	Sim
objectApiName	O nome do objeto Salesforce do qual recuperar dados.	Não para a fonte, Sim para o lavatório

Importante

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

Captura de tela mostrando o nome da API de conexão do Salesforce.

Exemplo:

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

Nota

Para compatibilidade com versões anteriores: quando você copia dados do Salesforce, se você usar o conjunto de dados do tipo "RelationalTable" anterior, ele continuará funcionando enquanto você vê uma sugestão para alternar para o novo tipo "SalesforceObject".

Property	Descrição	Obrigatório
tipo	A propriedade type do conjunto de dados deve ser definida como RelationalTable.	Sim
tableName	Nome da tabela no Salesforce.	Não (se "consulta" na fonte da atividade for especificado)

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 SalesforceSource. 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 SalesforceSource.	Sim
query	Use a consulta personalizada para ler dados. Você pode usar a consulta SOQL (Salesforce Object Query Language) ou a consulta SQL-92. Veja mais dicas na seção de dicas de consulta. Se a consulta não for especificada, todos os dados do objeto Salesforce especificado em "objectApiName" no conjunto de dados serão recuperados.	Não (se "objectApiName" no conjunto de dados for especificado)
readBehavior	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á o primeiro. Valores permitidos: query (default), queryAll.	Não

Importante

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

Captura de tela mostrando a lista Nome 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": "SalesforceSource",
                "query": "SELECT Col_Currency__c, Col_Date__c, Col_Email__c FROM AllDataType__c"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Nota

Para compatibilidade com versões anteriores: quando você copia dados do Salesforce, se você usar a cópia anterior do tipo "RelationalSource", a fonte continuará funcionando enquanto você vê uma sugestão para alternar para o novo tipo "SalesforceSource".

Nota

A origem do Salesforce não oferece suporte a configurações de proxy no tempo de execução de integração auto-hospedado, mas o coletor sim.

Salesforce como um tipo de coletor

Para copiar dados para o Salesforce, defina o tipo de coletor na atividade de cópia como SalesforceSink. 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 SalesforceSink.	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.	Não (o padrão é 5.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": "SalesforceSink",
                "writeBehavior": "Upsert",
                "externalIdFieldName": "CustomerId__c",
                "writeBatchSize": 10000,
                "ignoreNullValues": true
            }
        }
    }
]

Dicas de consulta

Recuperar dados de um relatório do Salesforce

Você pode recuperar dados de relatórios do Salesforce especificando uma consulta como {call "<report name>"}. Um exemplo é "query": "{call \"TestReport\"}".

Recuperar registros excluídos da Lixeira do Salesforce

Para consultar os registros excluídos suavemente da Lixeira do Salesforce, você pode especificar readBehavior como queryAll.

Diferença entre a sintaxe de consulta SOQL e SQL

Ao copiar dados do Salesforce, você pode usar a consulta SOQL ou a consulta SQL. Observe que esses dois têm sintaxe e funcionalidade diferentes, não misture. Sugere-se que você use a consulta SOQL, que é suportada nativamente pelo Salesforce. A tabela a seguir lista as principais diferenças:

Sintaxe	Modo SOQL	Modo SQL
Seleção de colunas	Necessidade de enumerar os campos a serem copiados na consulta, por exemplo, `SELECT field1, filed2 FROM objectname`	`SELECT *` é suportado além da seleção de colunas.
Aspas	Nomes de arquivos/objetos não podem ser citados.	Nomes de campos/objetos podem ser citados, por exemplo: `SELECT "id" FROM "Account"`
Formato datetime	Consulte os detalhes aqui e exemplos na próxima seção.	Consulte os detalhes aqui e exemplos na próxima seção.
Valores booleanos	Representado como `False` e `True`, por exemplo, `SELECT … WHERE IsDeleted=True`.	Representado como 0 ou 1, por exemplo. `SELECT … WHERE IsDeleted=1`
Renomeação de coluna	Não suportado.	Suportado, por exemplo: `SELECT a AS b FROM …`.
Relação	Suportado, por exemplo. `Account_vod__r.nvs_Country__c`	Não suportado.

Recuperar dados usando uma cláusula where na coluna DateTime

Ao especificar a consulta SOQL ou SQL, preste atenção à diferença de formato DateTime. Por exemplo:

Amostra SOQL: SELECT Id, Name, BillingCity FROM Account WHERE LastModifiedDate >= @{formatDateTime(pipeline().parameters.StartTime,'yyyy-MM-ddTHH:mm:ssZ')} AND LastModifiedDate < @{formatDateTime(pipeline().parameters.EndTime,'yyyy-MM-ddTHH:mm:ssZ')}
Exemplo de SQL: SELECT * FROM Account WHERE LastModifiedDate >= {ts'@{formatDateTime(pipeline().parameters.StartTime,'yyyy-MM-dd HH:mm:ss')}'} AND LastModifiedDate < {ts'@{formatDateTime(pipeline().parameters.EndTime,'yyyy-MM-dd HH:mm:ss')}'}

Erro de MALFORMED_QUERY: truncado

Se você clicar no erro "MALFORMED_QUERY: truncado", normalmente é devido a você ter a coluna do tipo JunctionIdList nos dados e o Salesforce tem limitação no suporte a esses dados com grande número de linhas. Para atenuar, tente excluir a coluna JunctionIdList ou limitar o número de linhas a serem copiadas (você pode particionar para várias execuções de atividade de cópia).

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 excedam a escala definida, seu valor será 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.

Próximos passos

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 V1 usando o Azure Data Factory ou o Azure Synapse Analytics

Capacidades suportadas

Pré-requisitos

Limites de solicitação do Salesforce

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

Dicas de consulta

Recuperar dados de um relatório do Salesforce

Recuperar registros excluídos da Lixeira do Salesforce

Diferença entre a sintaxe de consulta SOQL e SQL

Recuperar dados usando uma cláusula where na coluna DateTime

Erro de MALFORMED_QUERY: truncado

Mapeamento de tipo de dados para Salesforce

Propriedades da atividade de pesquisa

Próximos passos

Comentários

Recursos adicionais