Carregue dados do Salesforce para o BigQuery

Pode carregar dados da sua conta de vendas do Salesforce para o BigQuery através do Serviço de transferência de dados do BigQuery para o conetor do Salesforce. Com o Serviço de transferência de dados do BigQuery, pode agendar tarefas 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 conetor do Salesforce só suporta transferências a partir de uma conta de vendas do Salesforce.
  • O conetor do Salesforce só suporta campos incluídos na versão 64.0 da API Salesforce Bulk V1. Alguns campos que foram incluídos em versões anteriores da API em massa do Salesforce podem não ser suportados. Para mais informações acerca destas alterações ao conetor do Salesforce, consulte o artigo API em massa do Salesforce.
  • O conetor do Salesforce usa a Salesforce Bulk API V1 para estabelecer ligação ao ponto final do Salesforce para obter dados.
    • O conetor do Salesforce só suporta a Salesforce Bulk API V1 para estabelecer ligação à instância do Salesforce e só suporta a transferência de entidades suportadas pela Salesforce Bulk API. Para mais informações sobre as entidades suportadas, consulte o artigo Erro "A entidade não é suportada pela API Bulk".
  • O conetor do Salesforce não suporta a transferência dos seguintes objetos com campos binários.
    • Attachment
    • ContentVersion
    • Document
    • StaticResource
    • Scontrol
    • EmailCapture
    • MailMergeTemplate
  • O intervalo de tempo mínimo entre transferências de dados recorrentes é de 15 minutos. O intervalo predefinido para uma transferência recorrente é de 24 horas.
  • Devido aos limites de processamento do Salesforce, agendar demasiadas transferências de dados ao mesmo tempo pode provocar atrasos ou falhas. Recomendamos que limite as transferências de dados do Salesforce ao seguinte:
    • Não ter mais de 10 recursos por configuração de transferência.
    • Nas suas diferentes configurações de transferência, não tenha mais de 10 execuções de transferências simultâneas de cada vez.
  • Uma única configuração de transferência só pode suportar uma execução de transferência de dados num determinado momento. No caso em que uma segunda transferência de dados está agendada para ser executada antes da conclusão da primeira, apenas a primeira transferência de dados é concluída, enquanto todas as outras transferências de dados que se sobreponham à primeira são ignoradas.
    • Para evitar transferências ignoradas numa única configuração de transferência, recomendamos que aumente a duração do tempo entre transferências de grandes volumes de dados configurando a Frequência de repetição.
  • Se o anexo de rede configurado e a instância de máquina virtual (VM) estiverem localizados em regiões diferentes, pode haver movimento de dados entre regiões quando transfere dados do Salesforce.

Limitações de transferências incrementais

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

  • Só pode escolher TIMESTAMP colunas como colunas de marca de água.
  • O carregamento incremental só é suportado para recursos com colunas de marca de água válidas.
  • Os valores numa coluna de marca de água têm de aumentar monotonicamente.
  • As transferências incrementais não podem sincronizar operações de eliminação na tabela de origem.
  • Uma única configuração de transferência só pode suportar o carregamento incremental ou completo.
  • Não pode atualizar objetos na lista asset após a primeira execução de carregamento incremental.
  • Não pode alterar o modo de gravação numa configuração de transferência após a primeira execução de carregamento incremental.
  • Não pode alterar a coluna de marca d'água nem a chave principal após a primeira execução de carregamento incremental.

Opções de carregamento de dados

As secções seguintes fornecem mais informações sobre as opções de carregamento de dados quando configura uma transferência de dados do Salesforce.

Transferências completas ou incrementais

Pode especificar como os dados são carregados no BigQuery selecionando a preferência de escrita Completa ou Incremental na configuração da transferência quando configura uma transferência do Salesforce. As transferências incrementais são suportadas na pré-visualização.

Pode selecionar Completo para transferir todos os dados dos conjuntos de dados do Salesforce com cada transferência de dados.

Em alternativa, pode selecionar Incremental (Pré-visualização) para transferir apenas os dados que foram alterados desde a última transferência de dados, em vez de carregar o conjunto de dados completo com cada transferência de dados. Se selecionar Incremental para a transferência de dados, tem de especificar os modos de escrita Append ou Upsert para definir como os dados são escritos no BigQuery durante uma transferência de dados incremental. As secções seguintes descrevem os modos de escrita disponíveis.

Modo de escrita Anexar

O modo de gravação Anexar apenas insere novas linhas na tabela de destino. Esta opção anexa estritamente os dados transferidos sem verificar a existência de registos, pelo que este modo pode potencialmente causar a duplicação de dados na tabela de destino.

Quando seleciona o modo Anexar, tem de selecionar uma coluna de marca de água. É necessária uma coluna de marca de água para que o conetor do Salesforce acompanhe as alterações na tabela de origem.

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

Modo de escrita Upsert

O modo de gravação Upsert atualiza uma linha ou insere uma nova linha na tabela de destino verificando se existe uma chave primária. Pode especificar uma chave principal para permitir que o conetor do Salesforce determine que alterações 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 do BigQuery de destino durante uma transferência de dados, o conector do Salesforce atualiza essa linha com novos dados da tabela de origem. Se não estiver presente uma chave principal durante uma transferência de dados, o conector do Salesforce insere uma nova linha.

Quando seleciona o modo Upsert, tem de selecionar uma coluna de marca d'água e uma chave principal:

  • É necessária uma coluna de marca de água para que o conetor do Salesforce acompanhe as alterações na tabela de origem.
    • Selecione uma coluna de marca d'água que seja atualizada sempre que uma linha é modificada. Recomendamos que use a coluna SystemModstamp ou LastModifiedDate.
  • A chave principal pode ser uma ou mais colunas na sua tabela que são necessárias para o conetor do Salesforce determinar se precisa de inserir ou atualizar uma linha.
    • Selecione colunas que contenham valores não nulos que sejam exclusivos em todas as linhas da tabela. Recomendamos colunas que incluam identificadores gerados pelo sistema, códigos de referência únicos (por exemplo, IDs de incremento automático) ou IDs de sequência baseados em tempo imutáveis.
    • Para evitar uma potencial perda de dados ou corrupção de dados, as colunas de chave primária que selecionar têm de ter valores únicos. Se tiver dúvidas sobre a unicidade da coluna de chave principal escolhida, recomendamos que use o modo de gravação Anexar.

Antes de começar

As secções seguintes descrevem os passos que tem de realizar antes de criar uma transferência de dados do Salesforce.

Crie uma app associada do Salesforce

Tem de criar uma app associada do Salesforce com as seguintes configurações necessárias:

  • Configure as informações básicas na app associada. Os campos Nome da app associada e Email de contacto são obrigatórios para uma transferência do Salesforce.
  • Ative as definições de OAuth com as seguintes configurações:
    • Selecione a caixa de verificação Ativar definições OAuth.
    • No campo URL de retorno, introduza o seguinte:
      • Para um ambiente de produção, introduza https://login.salesforce.com/services/oauth2/token.
      • Para um ambiente de teste restrito, introduza https://test.salesforce.com/services/oauth2/token.
    • Verifique se a caixa de verificação Emitir tokens de acesso baseados em JSON Web Token(JWT) para utilizadores com nome não está selecionada.
  • Na secção Âmbitos do OAuth selecionados, selecione Gerir dados do utilizador através de APIs (api).
  • Desmarque a caixa de verificação Extensão de chave de prova necessária para troca de código (PKCE) para fluxos de autorização suportados.
  • Selecione Ativar fluxo de credenciais do cliente e, de seguida, clique em OK no aviso apresentado.

Depois de configurar a app associada com as configurações necessárias, clique em Guardar. É redirecionado para a página de detalhes da app associada criada recentemente.

Depois de criar a app associada, também tem de configurar o fluxo de credenciais do cliente da seguinte forma:

  1. Clique em Configurar.
  2. Na barra de pesquisa, pesquise Apps associadas.
  3. Clique em Gerir apps > Apps associadas. Se estiver a usar o Salesforce Lightning Experience, clique em Gerir apps associadas.
  4. Na app associada que criou, clique em Editar.
  5. É apresentada a página Detalhes da app. Na secção Fluxo de credenciais do cliente, introduza o seu nome de utilizador no campo Executar como. Pode usar a ferramenta de localização neste campo para garantir que selecionou o utilizador correto.
  6. Clique em Guardar.

Informações do Salesforce necessárias

Tem de ter as seguintes informações do Salesforce quando criar uma transferência de dados do Salesforce:

Nome do parâmetro Descrição
myDomain O seu My Domain no Salesforce.
clientId Chave do consumidor da aplicação associada do Salesforce.
clientSecret

Segredo do cliente OAuth ou segredo do consumidor da aplicação associada do Salesforce.

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

Salesforce Classic

Obtenha detalhes de myDomain

Para encontrar o seu myDomain, faça o seguinte:

  1. Inicie sessão na plataforma Salesforce.
  2. Clique em Configurar.
  3. Na barra de pesquisa, pesquise O meu domínio.
  4. Nos resultados da pesquisa, clique em Gestão de domínios > O meu domínio.

Na secção Detalhes do meu domínio, o seu myDomain aparece como o prefixo no URL atual de O meu domínio. Por exemplo, se o URL do meu domínio for example.my.salesforce.com, o valor myDomain a usar é example.

Obtenha detalhes de ClientId e ClientSecret

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

  1. Inicie sessão na plataforma Salesforce.
  2. Clique em Configurar.
  3. Na barra de pesquisa, pesquise Apps.
  4. Na secção Criar nos resultados da pesquisa, clique em Criar > Apps.
  5. Clique num Nome da app associada.
  6. Na página de detalhes Apps associadas, clique em Gerir detalhes do consumidor.
  7. Valide a sua identidade através de um dos métodos registados. Pode ver a página de detalhes do consumidor durante um máximo de cinco minutos antes de lhe ser pedido que valide novamente a sua identidade.
  8. Na página Detalhes do consumidor, a chave de consumidor é o seu valor ClientId. O segredo do cliente é o seu valor ClientSecret.

Salesforce Lightning Experience

Obtenha detalhes de myDomain

Para encontrar o seu myDomain, faça o seguinte:

  1. Inicie sessão na plataforma Salesforce.
  2. Clique em Configurar.

Abra a página de configuração na plataforma Salesforce.

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

Na secção Detalhes do meu domínio, o seu myDomain aparece como o prefixo no URL atual de O meu domínio. Por exemplo, se o URL do meu domínio for example.my.salesforce.com, o valor myDomain a usar é example.

Obtenha detalhes de ClientId e ClientSecret

  1. Inicie sessão na plataforma Salesforce.
  2. Clique em Configurar.
  3. Na barra de pesquisa, pesquise Apps.
  4. Nos resultados da pesquisa, clique em Apps > Gestor de apps.
  5. Encontre uma app associada e, de seguida, clique em Ver.
  6. Clique em Gerir detalhes do consumidor.
  7. Valide a sua identidade através de um dos métodos registados. Pode ver a página de detalhes do consumidor durante um máximo de cinco minutos antes de lhe ser pedido que valide novamente a sua identidade.
  8. Na página Detalhes do consumidor, a chave de consumidor é o seu valor ClientId. O segredo do cliente é o seu valor ClientSecret.

Configure a lista de autorizações de IPs para transferências do Salesforce

Tem de configurar o seu Google Cloud ambiente e a sua conta do Salesforce para adicionar endereços IP específicos à lista de autorizações para transferências de dados. Isto garante que o Salesforce só aceita ligações de um endereço IP estático fidedigno.

Para tal, primeiro tem de configurar a sua Google Cloud rede para usar um endereço IP estático:

  1. Configure uma traduçã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 tem de ser configurado na mesma região que o conjunto de dados de destino para esta transferência de dados.
  2. Configure uma associação de rede na mesma rede de VPC. Este recurso é usado pelo Serviço de transferência de dados do BigQuery para aceder a serviços privados.

Em seguida, tem de configurar os intervalos de IPs fidedignos no Salesforce. Quando adicionar o intervalo do endereço IP, use o endereço IP estático do seu NAT público para os endereços IP inicial e final do intervalo de IPs.Google Cloud

Depois de configurar os intervalos de IP, pode especificar o IP estático quando configurar a configuração de transferência selecionando a associação de rede no campo Associação de rede.

Pré-requisitos do BigQuery

Funções do BigQuery necessárias

Para receber as autorizações de que precisa para criar uma transferência de dados do Serviço de transferência de dados do BigQuery, peça ao seu administrador para lhe conceder a função do IAM de administrador do BigQuery (roles/bigquery.admin) no seu projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para criar uma transferência de dados do Serviço de transferência de dados do BigQuery. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para criar uma transferência de dados do Serviço de transferência de dados do BigQuery:

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

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Para mais informações, consulte o artigo Conceda acesso ao bigquery.admin.

Configure uma transferência de dados do Salesforce

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

Consola

  1. Aceda à página Transferências de dados na Google Cloud consola.

    Aceda a Transferências de dados

  2. Clique em Criar transferência.

  3. Na secção Tipo de origem, para Origem, escolha Salesforce.

  4. Na secção Detalhes da origem de dados, faça o seguinte:

    • Para Anexo de rede, selecione um anexo de rede na lista. Para mais informações, consulte o artigo Configure a lista de IPs permitidos para transferências do Salesforce
    • Para O meu domínio, introduza O meu domínio do Salesforce.
    • Para o ID de cliente, introduza a chave de consumidor da aplicação associada do Salesforce.
    • Para o Segredo do cliente, introduza o segredo do consumidor da aplicação associada do Salesforce.
    • Para Tipo de carregamento, selecione Completo ou Incremental.
    • Para transferir objetos do Salesforce, clique em Procurar:
      • Selecione os objetos a transferir para o conjunto de dados de destino do BigQuery. Também pode introduzir manualmente quaisquer objetos a incluir na transferência de dados neste campo.
      • Se selecionou Anexar como modo de gravação incremental, tem de selecionar uma coluna como coluna de marca de água.
      • Se selecionou Inserir/atualizar como modo de gravação incremental, tem de selecionar uma coluna como coluna de marca cronológica e, em seguida, selecionar uma ou mais colunas como chave principal.

  5. Na secção Definições de destino, para Conjunto de dados, escolha o conjunto de dados que criou para armazenar os seus dados.

  6. Na secção Nome da configuração de transferência, em Nome a apresentar, introduza um nome para a transferência de dados.

  7. Na secção Opções de programação:

    • Na lista Frequência de repetição, selecione uma opção para especificar a frequência com que esta transferência de dados é executada. Para especificar uma frequência de repetição personalizada, selecione Personalizado. Se selecionar A pedido, esta transferência é executada quando aciona manualmente a transferência.
    • Se aplicável, selecione Começar agora ou Começar à hora definida e indique uma data de início e um tempo de execução.

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

    • Para ativar as notificações por email, clique no botão Notificação por email. Quando ativa esta opção, o administrador da transferência recebe uma notificação por email quando uma execução da transferência falha.
    • Para ativar as notificações de execução de transferências do Pub/Sub para esta transferência, clique no botão ativar/desativar Notificações do Pub/Sub. Pode selecionar o nome do tópico ou clicar em Criar um tópico para criar um.

  9. Clique em Guardar.

bq

Introduza o comando bq mk e forneça a flag de criação de transferência --transfer_config:

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

Onde:

  • PROJECT_ID (opcional): o ID do seu Google Cloud projeto. Se --project_id não for fornecido para especificar um projeto em particular, é usado o projeto predefinido.
  • DATA_SOURCE: a origem de dados: salesforce.
  • NAME: o nome a apresentar da configuração de transferência de dados. O nome da transferência pode ser qualquer valor que lhe permita identificar a transferência se precisar de a modificar mais tarde.
  • DATASET: o conjunto de dados de destino para a configuração de transferência.

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

    • connector.authentication.oauth.clientId: a chave do consumidor da aplicação associada do Salesforce.
    • connector.authentication.oauth.clientSecret: segredo do cliente OAuth ou segredo do consumidor da aplicação associada do Salesforce.
    • connector.authentication.oauth.myDomain: o Salesforce My Domain. Por exemplo, se o URL do seu domínio for example.my.salesforce.com, o valor é example.
    • ingestionType: especifique FULL ou INCREMENTAL. As transferências incrementais são suportadas na pré-visualização. 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 de água. Este campo é obrigatório para transferências incrementais.
    • primaryKeys: especifique colunas na sua tabela como chaves primárias. Este campo é obrigatório para transferências incrementais.
    • assets: o caminho para os objetos do Salesforce a transferir para o BigQuery.

Quando especifica 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 seguinte, Id corresponde à tabela Account, enquanto master_label e type correspondem à tabela CaseHistory.

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

O comando seguinte cria uma transferência de dados incremental do Salesforce no projeto predefinido 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 guarda 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. Com cada execução de transferência, o conetor 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 normal, pode iniciar uma execução de preenchimento.

Mapeamento de tipos de dados

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

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 ver informações sobre os preços das transferências do Salesforce, consulte os preços do Serviço de transferência de dados.

Resolva problemas de configuração da transferência

Se estiver a ter problemas com a configuração da transferência de dados, consulte Problemas de transferência do Salesforce.

O que se segue?