Carregar dados do Salesforce no BigQuery

É possível carregar dados da sua conta de vendas do Salesforce para o BigQuery usando o conector do serviço de transferência de dados do BigQuery para Salesforce. Com o serviço de transferência de dados do BigQuery, é possível programar jobs de transferência recorrentes que adicionam os dados mais recentes da sua conta de vendas do Salesforce ao BigQuery.

Limitações

As transferências de dados do Salesforce estão sujeitas às seguintes limitações:

  • O conector do Salesforce só aceita transferências de uma conta de vendas do Salesforce.
  • O conector do Salesforce só é compatível com campos incluídos na API Bulk V1 versão 64.0 do Salesforce. Alguns campos incluídos em versões anteriores da API Bulk do Salesforce podem não ser compatíveis. Para mais informações sobre essas mudanças no conector do Salesforce, consulte API Bulk do Salesforce.
  • O conector do Salesforce usa a API Salesforce Bulk V1 para se conectar ao endpoint do Salesforce e extrair dados.
    • O conector do Salesforce é compatível apenas com a API Salesforce Bulk V1 para se conectar à instância do Salesforce e aceita apenas a transferência de entidades compatíveis com essa API. Para mais informações sobre quais entidades são compatíveis, consulte "A entidade não é compatível com o erro da API Bulk".
  • O conector do Salesforce não é compatível com a transferência dos seguintes objetos que têm campos binários.
    • Attachment
    • ContentVersion
    • Document
    • StaticResource
    • Scontrol
    • EmailCapture
    • MailMergeTemplate
  • O intervalo mínimo entre as transferências de dados recorrentes é de 15 minutos. O intervalo padrão para uma transferência recorrente é 24 horas.
  • Devido aos limites de processamento do Salesforce, programar muitas transferências de dados ao mesmo tempo pode causar atrasos ou falhas. Recomendamos que você limite as transferências de dados do Salesforce ao seguinte:
    • Ter no máximo 10 recursos por configuração de transferência.
    • Não ter mais de 10 execuções de transferência simultâneas nas diferentes configurações.
  • Uma única configuração de transferência só pode oferecer suporte a uma execução de transferência de dados por vez. Se uma segunda transferência de dados for programada para ser executada antes da conclusão da primeira, apenas a primeira será concluída. As outras transferências que se sobrepõem à primeira serão ignoradas.
    • Para evitar transferências ignoradas em uma única configuração, recomendamos aumentar a duração entre grandes transferências de dados configurando a Frequência de repetição.
  • Se a instância de máquina virtual (VM) e o anexo de rede configurados estiverem localizados em regiões diferentes, poderá haver movimentação de dados entre regiões ao transferir dados do Salesforce.

Limitações da transferência incremental

As transferências incrementais do Salesforce estão sujeitas às seguintes limitações:

  • Só é possível escolher TIMESTAMP colunas como colunas de marca-d'água.
  • A ingestão incremental só é compatível com recursos que têm colunas de marca-d'água válidas.
  • Os valores em uma coluna de marca-d'água precisam ser monotonicamente crescentes.
  • As transferências incrementais não podem sincronizar operações de exclusão na tabela de origem.
  • Uma única configuração de transferência pode oferecer suporte apenas à ingestão incremental ou completa.
  • Não é possível atualizar objetos na lista asset após a primeira execução de ingestão incremental.
  • Não é possível mudar o modo de gravação em uma configuração de transferência após a primeira execução de ingestão incremental.
  • Não é possível mudar a coluna de marca d'água ou a chave primária após a primeira execução de ingestão incremental.

Opções de ingestão de dados

As seções a seguir fornecem mais informações sobre as opções de ingestão de dados ao configurar uma transferência de dados do Salesforce.

Transferências completas ou incrementais

É possível especificar como os dados são carregados no BigQuery selecionando a preferência de gravação Completa ou Incremental na configuração da transferência ao configurar uma transferência do Salesforce. As transferências incrementais são compatíveis com o pré-lançamento.

Selecione Completa para transferir todos os dados dos seus conjuntos de dados do Salesforce com cada transferência de dados.

Como alternativa, selecione Incremental (Prévia) para transferir apenas os dados que foram alterados desde a última transferência, em vez de carregar todo o conjunto de dados a cada transferência. Se você selecionar Incremental para sua transferência de dados, especifique os modos de gravação Adicionar ou Upsert para definir como os dados são gravados no BigQuery durante uma transferência incremental. As seções a seguir descrevem os modos de gravação disponíveis.

Modo de gravação Append

O modo de gravação Append insere apenas novas linhas na tabela de destino. Essa opção anexa estritamente os dados transferidos sem verificar registros existentes. Portanto, esse modo pode causar duplicação de dados na tabela de destino.

Ao selecionar o modo Adicionar, escolha uma coluna de marca d'água. Uma coluna de marca-d'água é necessária para que o conector do Salesforce rastreie as mudanças na tabela de origem.

Para transferências do Salesforce, recomendamos selecionar uma coluna que só seja atualizada quando o registro for criado e que não mude com atualizações subsequentes. Por exemplo, a coluna CreatedDate.

Modo de gravação upsert

O modo de gravação Upsert atualiza uma linha ou insere uma nova na tabela de destino verificando uma chave primária. Você pode especificar uma chave primária para permitir que o conector do Salesforce determine quais mudanças são necessárias para manter a tabela de destino atualizada com a tabela de origem. Se a chave primária especificada estiver presente na tabela de destino do BigQuery durante uma transferência de dados, o conector do Salesforce vai atualizar essa linha com novos dados da tabela de origem. Se uma chave primária não estiver presente durante uma transferência de dados, o conector do Salesforce vai inserir uma nova linha.

Ao selecionar o modo Upsert, você precisa escolher uma coluna de marca d'água e uma chave primária:

  • Uma coluna de marca d'água é necessária para que o conector do Salesforce rastreie as mudanças na tabela de origem.
    • Selecione uma coluna de marca-d'água que seja atualizada sempre que uma linha for modificada. Recomendamos usar a coluna SystemModstamp ou LastModifiedDate.
  • A chave primária pode ser uma ou mais colunas na sua tabela necessárias para que o conector do Salesforce determine se precisa inserir ou atualizar uma linha.
    • Selecione colunas que contenham valores não nulos e exclusivos em todas as linhas da tabela. Recomendamos colunas que incluem identificadores gerados pelo sistema, códigos de referência exclusivos (por exemplo, IDs de incremento automático) ou IDs de sequência imutáveis baseados em tempo.
    • Para evitar possíveis perdas ou corrupção de dados, as colunas de chave primária selecionadas precisam ter valores exclusivos. Se você tiver dúvidas sobre a exclusividade da coluna de chave primária escolhida, recomendamos usar o modo de gravação Adicionar.

Antes de começar

Nas seções a seguir, descrevemos as etapas que você precisa seguir antes de criar uma transferência de dados do Salesforce.

Criar um app conectado do Salesforce

É necessário criar um app conectado do Salesforce com as seguintes configurações obrigatórias:

  • Configure as informações básicas no app conectado. Os campos Connected App Name e Contact Email são obrigatórios para uma transferência do Salesforce.
  • Ative as configurações do OAuth com as seguintes configurações:
    • Marque a caixa de seleção Ativar configurações do OAuth.
    • No campo URL de chamada de retorno, digite o seguinte.
      • Para um ambiente de produção, insira https://login.salesforce.com/services/oauth2/token.
      • Para um ambiente de sandbox, insira https://test.salesforce.com/services/oauth2/token.
    • Verifique se a caixa de seleção Emitir tokens de acesso baseados em JSON Web Token(JWT) para usuários nomeados não está marcada.
  • Na seção Escopos OAuth selecionados, selecione Gerenciar dados do usuário por APIs (api).
  • Desmarque a caixa de seleção Required Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows.
  • Selecione Ativar o fluxo de credenciais do cliente e clique em OK no aviso que aparece.

Depois de configurar o app conectado com as configurações necessárias, clique em Salvar. Você será redirecionado para a página de detalhes do app conectado recém-criado.

Depois de criar o app conectado, você também precisa configurar o fluxo de credenciais do cliente:

  1. Clique em Configurar.
  2. Na barra de pesquisa, pesquise Apps conectados.
  3. Clique em Gerenciar apps > Apps conectados. Se você estiver usando a Salesforce Lightning Experience, clique em Gerenciar apps conectados.
  4. No app conectado que você criou, clique em Editar.
  5. A página Detalhes do app é exibida. Na seção Fluxo de credenciais do cliente, insira seu nome de usuário no campo Executar como. Você pode usar a ferramenta de localização neste campo para garantir que selecionou o usuário correto.
  6. Clique em Salvar.

Informações obrigatórias do Salesforce

Você precisa ter as seguintes informações do Salesforce ao criar uma transferência de dados do Salesforce:

Nome do parâmetro Descrição
myDomain Seu Meu domínio no Salesforce.
clientId Chave do cliente do aplicativo conectado do Salesforce.
clientSecret

Chave secreta do cliente OAuth ou do cliente do aplicativo conectado do Salesforce.

Para receber os valores myDomain, clientID e clientSecret, selecione uma das seguintes opções:

Salesforce Classic

Extrair detalhes de myDomain

Para encontrar o myDomain, faça o seguinte:

  1. Faça login na plataforma do Salesforce.
  2. Clique em Configurar.
  3. Na barra de pesquisa, pesquise Meu domínio.
  4. Nos resultados da pesquisa, clique em Gerenciamento de domínio > Meu domínio.

Na seção Detalhes do meu domínio, o myDomain aparece como o prefixo no URL atual do meu domínio. Por exemplo, se o URL do Meu domínio for example.my.salesforce.com, o valor de myDomain a ser usado será example.

Extrair detalhes de ClientId e ClientSecret

Para encontrar os valores ClientId e ClientSecret, faça o seguinte:

  1. Faça login na plataforma do Salesforce.
  2. Clique em Configurar.
  3. Na barra de pesquisa, digite Apps.
  4. Na seção Build dos resultados da pesquisa, clique em Criar > Apps.
  5. Clique em um Nome do app conectado.
  6. Na página de detalhes Apps conectados, clique em Gerenciar detalhes do consumidor.
  7. Verifique sua identidade usando um dos métodos registrados. Você pode acessar a página de detalhes do consumidor por até cinco minutos antes de receber a solicitação de verificação da identidade novamente.
  8. Na página Detalhes do consumidor, a chave do consumidor é o valor ClientId. O Customer Secret é o valor ClientSecret.

Experiência do Salesforce Lightning

Extrair detalhes de myDomain

Para encontrar o myDomain, faça o seguinte:

  1. Faça login na plataforma do Salesforce.
  2. Clique em Configurar.

Abra a página "Configuração" na plataforma do Salesforce.

  1. Na barra de pesquisa, pesquise Meu domínio.
  2. Nos resultados da pesquisa, clique em Configurações da empresa > Meu domínio.

Na seção Detalhes do meu domínio, o myDomain aparece como o prefixo no URL atual do meu domínio. Por exemplo, se o URL do Meu domínio for example.my.salesforce.com, o valor de myDomain a ser usado será example.

Extrair detalhes de ClientId e ClientSecret

  1. Faça login na plataforma do Salesforce.
  2. Clique em Configurar.
  3. Na barra de pesquisa, digite Apps.
  4. Nos resultados da pesquisa, clique em Apps > Gerenciador de apps.
  5. Encontre um app conectado e clique em Visualizar.
  6. Clique em Gerenciar detalhes do consumidor.
  7. Verifique sua identidade usando um dos métodos registrados. Você pode acessar a página de detalhes do consumidor por até cinco minutos antes de receber a solicitação de verificação da identidade novamente.
  8. Na página Detalhes do consumidor, a chave do consumidor é o valor ClientId. O Customer Secret é o valor ClientSecret.

Configurar a lista de permissões de IP para transferências do Salesforce

É necessário configurar seu ambiente Google Cloud e sua conta do Salesforce para adicionar endereços IP específicos à lista de permissões para transferências de dados. Isso garante que o Salesforce só aceite conexões de um endereço IP estático e confiável.

Para isso, primeiro configure sua rede Google Cloud para usar um endereço IP estático:

  1. Configure uma conversão de endereços de rede (NAT) pública com um endereço IP estático na sua rede de nuvem privada virtual. O CloudNAT precisa ser configurado na mesma região que o conjunto de dados de destino para essa transferência.
  2. Configure um anexo de rede na mesma rede VPC. Esse recurso é usado pelo serviço de transferência de dados do BigQuery para acessar serviços particulares.

Em seguida, configure os intervalos de IP confiáveis no Salesforce. Ao adicionar o intervalo de endereços IP, use o endereço IP estático do seu NAT públicoGoogle Cloud para os endereços IP inicial e final do intervalo.

Depois de configurar os intervalos de IP, especifique o IP estático ao configurar a transferência. Para isso, selecione o anexo de rede no campo Anexo de rede.

Pré-requisitos do BigQuery

Papéis obrigatórios do BigQuery

Para receber as permissões necessárias para criar uma transferência de dados do serviço de transferência de dados do BigQuery, peça ao administrador para conceder a você o papel do IAM Administrador do BigQuery (roles/bigquery.admin) no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar uma transferência de dados do serviço de transferência de dados do BigQuery. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar uma transferência de dados do serviço de transferência de dados do BigQuery:

  • Permissões do serviço de transferência de dados do BigQuery:
    • bigquery.transfers.update
    • bigquery.transfers.get
  • Permissões do BigQuery:
    • bigquery.datasets.get
    • bigquery.datasets.getIamPolicy
    • bigquery.datasets.update
    • bigquery.datasets.setIamPolicy
    • bigquery.jobs.create

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Para mais informações, consulte Conceder acesso ao bigquery.admin.

Configurar uma transferência de dados do Salesforce

Adicione dados do Salesforce ao BigQuery configurando uma configuração de transferência usando uma das seguintes opções:

Console

  1. Acesse a página "Transferências de dados" no console Google Cloud .

    Acesse Transferências de dados

  2. Clique em Criar transferência.

  3. Na seção Tipo de origem, em Origem, escolha Google AdWords.

  4. Na seção Detalhes da fonte de dados, faça o seguinte:

    • Em Anexo de rede, selecione uma opção na lista. Para mais informações, consulte Configurar a lista de permissões de IP para transferências do Salesforce.
    • Em Meu domínio, insira o Meu domínio do Salesforce.
    • Em ID do cliente, insira o token do cliente do aplicativo conectado do Salesforce.
    • Em Chave secreta do cliente, insira a chave secreta do cliente do aplicativo conectado do Salesforce.
    • Em Tipo de ingestão, selecione Completa ou Incremental.
    • Em Objetos do Salesforce para transferência, clique em Procurar:
      • Selecione os objetos a serem transferidos para o conjunto de dados de destino do BigQuery. Nesse campo, também é possível inserir manualmente qualquer objeto para incluir na transferência de dados.
      • Se você tiver selecionado Adicionar como modo de gravação incremental, escolha uma coluna como marca d'água.
      • Se você tiver selecionado Upsert como modo de gravação incremental, selecione uma coluna como marca d'água e uma ou mais colunas como chave primária.

  5. No campo Conjunto de dados da seção Configurações de destino, escolha o conjunto criado para armazenar seus dados.

  6. No campo Nome de exibição da seção Nome de configuração da transferência, insira um nome para a transferência de dados.

  7. Na seção Opções de programação, faça o seguinte:

    • Na lista Frequência de repetição, selecione uma opção para especificar com que frequência essa transferência de dados é executada. Para especificar uma frequência de repetição personalizada, selecione Personalizada. Se você selecionar Sob demanda, essa transferência será executada quando você acionar manualmente a transferência.
    • Se aplicável, selecione Começar agora ou Começar no horário definido e escolha uma data de início e hora de execução.

  8. Opcional: na seção Opções de notificação, faça o seguinte:

    • Para ativar as notificações por e-mail, clique no botão que ativa as Notificações por e-mail. Quando essa opção está ativada, o administrador da transferência recebe uma notificação por e-mail quando uma execução da transferência falha.
    • Para ativar as notificações de execução de transferência do Pub/Sub para essa transferência, clique no botão de alternância Notificações do Pub/Sub. Selecione o nome do tópico ou clique em Criar tópico.

  9. Clique em Salvar.

bq

Insira o comando bq mk e forneça a sinalização de execução da transferência --transfer_config:

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

Em que:

  • PROJECT_ID (opcional): o ID do projeto do Google Cloud . Se --project_id não for fornecido para especificar um projeto determinado, o projeto padrão será usado.
  • DATA_SOURCE: a fonte de dados — salesforce.
  • NAME: o nome de exibição da configuração da transferência de dados. O nome da transferência pode ser qualquer valor que permita identificá-la, caso você precise modificá-la mais tarde.
  • DATASET: o conjunto de dados de destino na configuração da transferência.

  • PARAMETERS é o parâmetro da configuração de transferência criada no formato JSON. Por exemplo, --params='{"param":"param_value"}'. Confira a seguir os parâmetros de uma transferência de dados do Salesforce:

    • connector.authentication.oauth.clientId: a chave do cliente do aplicativo conectado do Salesforce.
    • connector.authentication.oauth.clientSecret: chave secreta do cliente OAuth ou do cliente do aplicativo conectado do Salesforce.
    • connector.authentication.oauth.myDomain: o My Domain do Salesforce. Por exemplo, se o URL do domínio for example.my.salesforce.com, o valor será example.
    • ingestionType: especifique FULL ou INCREMENTAL. As transferências incrementais são compatíveis com a prévia. Para mais informações, consulte Transferências completas ou incrementais.
    • writeMode: especifique WRITE_MODE_APPEND ou WRITE_MODE_UPSERT.
    • watermarkColumns: especifique colunas na sua tabela como colunas de marca d'água. Esse campo é obrigatório para transferências incrementais.
    • primaryKeys: especifique colunas na sua tabela como chaves primárias. Esse campo é obrigatório para transferências incrementais.
    • assets: o caminho para os objetos do Salesforce a serem transferidos para o BigQuery.

Ao especificar vários recursos durante uma transferência incremental, os valores dos campos watermarkColumns e primaryKeys correspondem à posição dos valores no campo assets. No exemplo a seguir, Id corresponde à tabela Account, enquanto master_label e type correspondem à tabela CaseHistory.

      "primaryKeys":[['Id'], ['master_label','type']],
      "assets":["Account","CaseHistory"],

O comando a seguir cria uma transferência de dados incremental do Salesforce no projeto padrão e usa o modo de gravação APPEND.

bq mk
    --transfer_config
    --target_dataset=mydataset
    --data_source=salesforce
    --display_name='My Transfer'
    --params='{"assets": ["Account", "CaseHistory"]
        "connector.authentication.oauth.clientId": "1234567890",
        "connector.authentication.oauth.clientSecret":"ABC12345",
        "connector.authentication.oauth.myDomain":"MyDomainName",
        "connector.authentication.username":"user1@force.com",
        "connector.authentication.password":"abcdef1234",
        "ingestionType":"incremental",
        "writeMode":"WRITE_MODE_UPSERT",
        "watermarkColumns":["SystemModstamp","CreatedDate"]
        "primaryKeys":[['Id'], ['master_label','type']]}'

API

Use o método projects.locations.transferConfigs.create e forneça uma instância do recurso TransferConfig.

Quando você salva a configuração de transferência, o conector do Salesforce aciona automaticamente uma execução de transferência de acordo com a opção de programação. A cada execução de transferência, o conector do Salesforce transfere todos os dados disponíveis do Salesforce para o BigQuery.

Para executar manualmente uma transferência de dados fora da sua programação regular, inicie uma execução de preenchimento.

Mapeamento de tipo de dados

A tabela a seguir mapeia os tipos de dados do Salesforce para os tipos de dados correspondentes do BigQuery:

Tipo de dados do Salesforce Tipo de dados do BigQuery
_bool BOOLEAN
_int INTEGER
_long INTEGER
_double FLOAT
currency FLOAT
percent FLOAT
geolocation (latitude) FLOAT
geolocation (longitude) FLOAT
date DATE
datetime TIMESTAMP
time TIME
picklist STRING
multipicklist STRING
combobox STRING
reference STRING
base64 STRING
textarea STRING
phone STRING
id STRING
url STRING
email STRING
encryptedstring STRING
datacategorygroupreference STRING
location STRING
address STRING
anyType STRING

Preços

Para informações sobre preços de transferências do Salesforce, consulte Preços do serviço de transferência de dados.

Resolver problemas na configuração da transferência

Se você tiver problemas para configurar a transferência de dados, consulte Problemas de transferência no Salesforce.

A seguir