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

Artigo
02/06/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 no pipeline do Azure Data Factory e do Azure Synapse para copiar dados de e para o Salesforce. 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 serviço lançou um novo conector do Salesforce que fornece melhor suporte nativo do Salesforce, consulte o artigo do Conector do Salesforce para obter detalhes.

Funcionalidades com suporte

Há suporte para este conector do Salesforce nas seguintes funcionalidades:

Funcionalidades com suporte	IR
Atividade de cópia (origem/coletor)	① ②
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 ou coletores, confira a tabela Armazenamentos de dados com suporte.

Especificamente, este conector Salesforce dá suporte à:

Edições de Desenvolvedor, Professional, Enterprise ou Ilimitada do Salesforce.
Copiar dados de e para a produção, da área restrita e do domínio personalizado do Salesforce.

Observação

Essa função dá suporte à cópia de qualquer esquema dos ambientes Salesforce mencionados acima, incluindo oPacote de Sucesso Sem Fins lucrativos (NPSP).

O conector do Salesforce é criado sobre a API REST/Em massa do Salesforce. Ao copiar os dados do Salesforce, o conector escolhe automaticamente entre as APIs REST e Bulk com base no tamanho dos dados - quando o conjunto de resultados for grande, a API Bulk será usada para melhorar o desempenho; você pode definir explicitamente a versão da API usada para ler/gravar dados usando a apiVersion propriedade no serviço vinculado. Ao copiar dados para o Salesforce, o conector usará a API BULK v1.

Observação

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

Pré-requisitos

A permissão de API deve estar habilitada no Salesforce.

Limites da solicitação Salesforce

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

Se o número de solicitações simultâneas exceder o limite, a limitação será atingida 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, veja a seção "Limites de Solicitações da API" na seção Salesforce Developer Limits (Limites do Desenvolvedor Salesforce).

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 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 workspace do Azure Data Factory ou do Synapse, selecione Serviços Vinculados e clique em Novo:
- Azure Data Factory
- Azure Synapse
Pesquise por Salesforce e selecione o conector do Salesforce.
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 específicas ao conector do Salesforce.

Propriedades do serviço vinculado

As propriedades a seguir têm suporte para o serviço vinculado do Salesforce.

Propriedade	Descrição	Obrigatório
type	A propriedade type deve ser definida para Salesforce.	Yes
environmentUrl	Especifique a URL da instância do Salesforce. – O padrão é `"https://login.salesforce.com"`. – Para copiar dados da área restrita, especifique `"https://test.salesforce.com"`. – Para copiar dados do domínio personalizado, especifique, por exemplo, `"https://[domain].my.salesforce.com"`.	No
Nome de Usuário	Especifique um nome de usuário para a conta de usuário.	Sim
password	Especifique um senha para a conta de usuário. Marque este campo como um SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault.	Sim
securityToken	Especifique um token de segurança para a conta de usuário. Para saber mais sobre os tokens de segurança em geral, veja Security and the API (Segurança e a API). O token de segurança só poderá ser ignorado se você adicionar o IP do Integration Runtime à lista de endereços IP confiáveis no Salesforce. Ao usar o Azure IR, consulte o endereço IP do Azure Integration Runtime. Para obter instruções sobre como obter e redefinir o token de segurança, consulte Obter token de segurança. Marque este campo como um SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault.	Não
apiVersion	Especifique a versão da API REST/Em massa do Salesforce que será usada, por exemplo, `52.0`.	Não
connectVia	O runtime de integração a ser usado para se conectar ao armazenamento de dados. Se não for especificado, ele usa o Integration Runtime padrão do Azure.	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: Credenciais de armazenamento no Key Vault

{
    "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 de Chaves, assim como o environmentUrl e o username

Observe que, ao fazer isso, você não conseguirá 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ê precisará editar toda essa configuração manualmente. A vantagem é que você poderá derivar TODAS as configurações 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 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 Salesforce.

Para copiar dados do e para o Salesforce, defina a propriedade tipo do conjunto de dados como SalesforceObject. Há suporte para as seguintes propriedades.

Propriedade	Descrição	Obrigatório
type	A propriedade tipo deve ser definida para SalesforceObject.	Yes
objectApiName	O nome do objeto de Salesforce para recuperar dados.	Não para fonte, Sim para o coletor

Importante

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

Screenshot showing Salesforce connection API Name.

Exemplo:

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

Observação

Para retrocompatibilidade: ao copiar dados de Salesforce, se você usar o conjunto de dados de tipo "RelationalTable" anterior continuará funcionando, enquanto você vê uma sugestão para alternar para o novo tipo de "SalesforceObject".

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

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 e coletor do Salesforce.

Salesforce como um tipo de fonte

Para copiar dados do Salesforce, defina o tipo de origem na atividade de cópia como SalesforceSource. As propriedades a seguir têm suporte na seção source da atividade de cópia.

Propriedade	Descrição	Obrigatório
type	A propriedade tipo da fonte da atividade de cópia deve ser definida como: SalesforceSource.	Sim
Consulta	Utiliza a consulta personalizada para ler os dados. É possível usar a consulta SOQL (Salesforce Object Query Language) ou a consulta SQL-92. Veja mais dicas na seção 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 deve consultar os registros existentes, ou consultar todos os registros, incluindo o que foi excluído. Se não for especificado, o comportamento padrão é o primeiro. Valores permitidos: query (padrão), queryAll.	No

Importante

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

Screenshot showing Salesforce connection API Name list.

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

Observação

Para retrocompatibilidade: ao copiar dados de Salesforce, se você usar a cópia de tipo "RelationalSource" anterior, a fonte continuará funcionando, enquanto você vê uma sugestão para alternar para o novo tipo de "SalesforceSource".

Observação

A origem do Salesforce não dá suporte a configurações de proxy no runtime de integração auto-hospedada, mas o coletor dá suporte.

Salesforce como um tipo de coletor

Para copiar dados do Salesforce, defina o tipo de coletor na atividade de cópia como SalesforceSink. As propriedades a seguir têm suporte na seção sink da atividade de cópia.

Propriedade	Descrição	Obrigatório
type	A propriedade type do coletor da atividade de cópia deve ser definida como SalesforceSink.	Sim
writeBehavior	O comportamento da operação de gravação. Valores permitidos são Insert e Upsert.	Não (o padrão é Insert)
externalIdFieldName	O nome do campo de ID externo para a operação upsert. O campo especificado deve ser definido como “Campo de ID Externo” no objeto Salesforce. Ele não pode ter valores nulos 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 deve ignorar valores NULL de dados de entrada durante a operação de gravação. Os valores permitidos são True e False. - True: Deixa os dados no objeto de destino inalterados quando você faz uma operação upsert ou atualização. Insira um valor padrão definido quando você faz uma operação insert. - False: atualiza os dados no objeto de destino como NULL quando você faz uma operação upsert ou atualização. Insira um valor NULL quando você faz uma operação insert.	Não (padrão é falso)
maxConcurrentConnections	O limite superior de conexões simultâneas estabelecidas com o armazenamento de dados durante a execução da atividade. Especifique um valor somente quando desejar limitar as conexões simultâneas.	Nenhum

Exemplo: coletor 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

Recupere dados do 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\"}".

Recupere registros excluídos da lixeira do Salesforce

Para consultar os registros excluídos de maneira reversível 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, é possível usar a consulta SOQL ou a consulta SQL. Observe que esses dois tipos de suporte têm sintaxe e funcionalidade diferentes, portanto, não os misture. Recomenda-se usar a consulta SOQL que tem suporte nativo no Salesforce. A tabela a seguir lista as principais diferenças:

Syntax	Modo SOQL	Modo SQL
Seleção de coluna	É necessário enumerar os campos que serão copiados na consulta, por exemplo `SELECT field1, filed2 FROM objectname`	`SELECT *` tem suporte além da seleção de colunas.
Aspas	Nomes de campos/objetos não podem ser entre aspas.	Nomes de campos/objetos podem ser entre aspas, p. ex. `SELECT "id" FROM "Account"`
Formato de data/hora	Consulte os detalhes aqui e exemplos na próxima seção.	Consulte os detalhes aqui e exemplos na próxima seção.
Valores boolianos	Representado como `False` e `True`, p. ex. `SELECT … WHERE IsDeleted=True`.	Representado como 0 ou 1, p. ex. `SELECT … WHERE IsDeleted=1`.
Renomeação de coluna	Não há suporte.	Com suporte, p. ex.: `SELECT a AS b FROM …`.
Relação	Com suporte, p. ex. `Account_vod__r.nvs_Country__c`.	Não há suporte.

Recuperar dados usando um onde cláusula na coluna DateTime

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

Exemplo de 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

O erro de "MALFORMED_QUERY: truncado" normalmente ocorre quando há uma coluna de tipo JunctionIdList nos dados e o Salesforce tem compatibilidade limitada com dados que têm um grande número de linhas. Para mitigá-lo, tente excluir a coluna JunctionIdList ou limitar o número de linhas que serão copiadas (você pode particionar várias execuções da atividade de cópia).

Mapeamento de tipo de dados para Salesforce

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

Tipo de dados do Salesforce	Tipo de dados provisório do serviço
Numeração automática	String
Caixa de seleção	Boolean
Moeda	Decimal
Data	Datetime
Data/Hora	Datetime
Email	String
ID	String
Relação de pesquisa	String
Lista de seleção múltipla	String
Número	Decimal
Porcentagem	Decimal
Telefone	String
Lista de seleção	String
Texto	Cadeia de caracteres
Área de texto	String
Área de texto (longo)	String
Área de texto (Rich)	String
Texto (criptografado)	String
URL	String

Observação

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 segue a precisão e a escala definidas. Para dados cujas casas decimais excedem a escala definida, o valor será arredondado em dados de visualização e cópia. Para evitar a perda de precisão nos pipelines do Azure Data Factory e do Azure Synapse, aumente as casas decimais para um valor maior na medida do possível na página Edição da Definição de Campo Personalizado do Salesforce.

Pesquisar propriedades de atividade

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

Próximas etapas

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

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

Funcionalidades com suporte

Pré-requisitos

Limites da solicitação Salesforce

Introdução

Criar um serviço vinculado ao Salesforce 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

Salesforce como um tipo de fonte

Salesforce como um tipo de coletor

Dicas de consulta

Recupere dados do relatório do Salesforce

Recupere registros excluídos da lixeira do Salesforce

Diferença entre a sintaxe de consulta SOQL e SQL

Recuperar dados usando um onde cláusula na coluna DateTime

Erro de MALFORMED_QUERY: truncado

Mapeamento de tipo de dados para Salesforce

Pesquisar propriedades de atividade

Próximas etapas

Recursos adicionais