Carregar dados do Salesforce Marketing Cloud no BigQuery

É possível carregar dados do Salesforce Marketing Cloud para o BigQuery usando o serviço de transferência de dados do BigQuery para o conector do Salesforce Marketing Cloud. 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 do Salesforce Marketing Cloud ao BigQuery.

Limitações

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

  • Uma única configuração de transferência só pode dar suporte a uma execução de transferência de dados por vez. No caso de uma segunda transferência de dados ser programada para ser executada antes que a primeira seja concluída, apenas a primeira transferência de dados será concluída, enquanto todas as outras transferências de dados que se sobrepõem à primeira serão ignoradas.
    • Para evitar transferências ignoradas em uma única configuração de transferência, recomendamos que você aumente o tempo entre grandes transferências de dados configurando a Frequência de repetição.
  • Para usar um anexo de rede com essa transferência de dados, primeiro é preciso criar um anexo de rede definindo um endereço IP estático.
  • As transferências do Salesforce Marketing Cloud não são compatíveis com extensões de dados que contêm campos binários ou de blob grandes.
  • Se o anexo de rede configurado e a instância de máquina virtual (VM) estiverem localizados em regiões diferentes, poderá haver movimentação de dados entre regiões ao transferir dados do Salesforce Marketing Cloud.

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 Marketing Cloud.

Pré-requisitos do Salesforce Marketing Cloud

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

Nome do parâmetro Descrição
subdomain O subdomínio da API, encontrado no URI base. Por exemplo, no URI da base de autenticação https://SUBDOMAIN.auth.marketingcloudapis.com/, SUBDOMAIN é o valor do subdomínio.
instance A instância do servidor de API, encontrada no URL depois de fazer login no aplicativo Salesforce Marketing Cloud. O valor da instância inclui "s" seguido por um valor numérico. Por exemplo, no URL `https://mc.s4.exacttarget.com/`, o valor da instância é `s4`. Para mais informações, consulte Encontrar o local da pilha de uma conta do Marketing Cloud.
clientId O ID do cliente da integração da API. Navegue até Configuração > Apps > Pacotes instalados e clique no nome do pacote. O ID do cliente aparece em Componentes.
clientSecret A chave secreta do cliente de integração do app. Acesse Configuração > Apps > Pacotes instalados e clique no nome do pacote. A chave secreta do cliente aparece em Componentes.
Salesforce Marketing Cloud objects to transfer Compile uma lista de objetos do Salesforce Marketing Cloud para incluir nessa transferência. É possível selecionar objetos ao definir uma configuração de transferência. Para uma lista de objetos compatíveis, consulte Tabelas compatíveis.

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

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

Para fazer isso, primeiro configure sua rede do 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 Cloud NAT precisa ser configurado na mesma região do conjunto de dados de destino para essa transferência de dados.
  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, adicione o endereço IP estático à lista de permissões no Salesforce Marketing Cloud. Ao adicionar o intervalo do endereço IP, use o endereço IP estático do Google Cloud Public NAT para os endereços IP inicial e final do intervalo de IP.

Depois de configurar os intervalos de IP, especifique o IP estático ao definir a configuração de transferência selecionando o anexo de rede no campo Anexo de rede.

Requisitos de objeto de extensão de dados

Para incluir objetos de extensão de dados na transferência de dados, o objeto precisa atender aos seguintes requisitos:

  • O nome do objeto de extensão de dados precisa incluir o prefixo DataExtensionObject seguido pelo nome do objeto. Por exemplo, DataExtensionObject_DATA_EXTENSION_NAME.
  • Ative o escopo Read para o objeto de extensão de dados.
  • Os locais de arquivo do objeto de extensão de dados precisam ter os escopos Read e Write.

Instalar e configurar o pacote de integração da API do Salesforce Marketing Cloud

Você precisa instalar um pacote de integração de API de servidor para servidor no Salesforce Marketing Cloud. Para isso, instale um novo pacote no Salesforce Marketing Cloud e especifique o componente Integração de API > Servidor para servidor. Para mais informações, consulte Criar e instalar pacotes.

Depois de instalar o pacote de integração da API, adicione os seguintes escopos de permissão:

  • Acesso: Offline Access
  • E-mail: Read
  • OTT: Read
  • Push:Read
  • SMS:Read
  • Web: Read
  • Documentos e imagens: Read
  • Conteúdo salvo: Read
  • Jornadas: Read
  • Públicos-alvo: Read
  • Lista e inscritos: Read
  • Extensões de data: Read
  • Locais do arquivo Read
  • Eventos de rastreamento: Read
  • Callbacks: Read
  • Assinaturas: Read
  • Campanha: Read
  • Recursos: Read
  • Contas: Read
  • Canais OTT: Read
  • Usuários: Read

Para mais informações, consulte Escopos de permissão de integração de API.

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 de Administrador do BigQuery (roles/bigquery.admin) no 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 permissões a seguir 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 Marketing Cloud

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

Console

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

    Acesse Transferências de dados

  2. Clique em Criar transferência.

  3. Na seção Tipo de origem, em Origem, selecione Salesforce Marketing Cloud.

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

  5. Na seção Configurações de destino, em Conjunto de dados, selecione o conjunto de dados que você criou 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, realize estas ações:

    • 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 um tópico.

  9. Clique em Salvar.

bq

Insira o comando bq mke 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=DISPLAY_NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

Substitua:

  • 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 (por exemplo, saphana).
  • DISPLAY_NAME: o nome de exibição da configuração da transferência. O nome da transferência de dados 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 de 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 do Salesforce Marketing Cloud:
    • connector.subdomain: o subdomínio da API.
    • connector.instance: o valor da instância da API.
    • connector.authentication.oauth.clientId: o nome do ID do app para o cliente OAuth.
    • connector.authentication.oauth.clientSecret: a chave secreta do app para o cliente OAuth.
    • assets: uma lista dos nomes das tabelas do Salesforce Marketing Cloud a serem transferidas do Salesforce Marketing Cloud como parte da transferência.

Por exemplo, o comando a seguir cria uma transferência de dados do Salesforce Marketing Cloud no projeto padrão com todos os parâmetros necessários:

  bq mk
      --transfer_config
      --target_dataset=mydataset
      --data_source=salesforce_marketing
      --display_name='My Transfer'
      --params='{"connector.subdomain": "abcd",
      "connector.instance": "x",
      "connector.authentication.oauth.clientId": "1234567890",
      "connector.authentication.oauth.clientSecret":"ABC12345"}'

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 Marketing Cloud aciona automaticamente uma execução de transferência de acordo com a opção de programação.

Tabelas compatíveis

A cada execução de transferência, o conector do Salesforce Marketing Cloud transfere todos os dados disponíveis do Salesforce Marketing Cloud para o BigQuery nas seguintes tabelas com base na interface REST:

  • Assets
  • CampaignAssets
  • Campaigns
  • Categories
  • EventDefinitions
  • FacebookMessengerProperties
  • JourneyActivities
  • Journeys
  • LineMessengerProperties
  • SendDefinitions
  • Subscriptions
  • DataExtension
  • DataExtensionObject_DATA_EXTENSION_NAME
  • Email
  • LinkSend
  • List
  • ListSubscriber
  • Subscriber
  • TriggeredSendDefinition

Para executar manualmente uma transferência de dados fora da 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 Marketing Cloud para os tipos de dados correspondentes do BigQuery.

Tipo de dados do Salesforce Marketing Cloud Tipo de dados do BigQuery
Boolean BOOLEAN
Number INTEGER
Text STRING
Decimal FLOAT
EmailAddress STRING
Phone STRING
Date DATE
DateTime TIMESTAMP
Locale STRING

Resolver problemas na configuração da transferência

Se você estiver com problemas para configurar ou executar uma transferência de dados do Salesforce Marketing Cloud, tente as seguintes etapas de solução de problemas:

  • Verifique se o pacote de integração da API no Salesforce Marketing Cloud está configurado especificamente para autenticação de servidor para servidor.
  • Verifique se o app autenticador está configurado com todas as permissões necessárias em Escopo, incluindo Data Extensions: Read.
  • Para evitar tempos limite e falhas intermitentes, limite cada configuração de transferência a no máximo 10 recursos.
  • Verifique se você não está transferindo extensões de dados que contêm campos binários ou de blob grandes.

Mensagens de erro

Erro: invalid_grant. The client's IP address is unauthorized for this account. Allowlist the client's IP address in Marketing Cloud Administration.

Resolução: tente uma das seguintes etapas:

Erro: INVALID_ARGUMENT. Table tableName does not exist in asset TableName

Resolução:verifique se o nome do recurso é uma correspondência exata, que diferencia maiúsculas de minúsculas, com o nome na sua conta do Salesforce Marketing Cloud e se o escopo Data Extensions: Read foi concedido. Ao transferir dados de linha para uma extensão de dados, o nome precisa seguir o padrão exato: DataExtensionObject_DATA_EXTENSION_NAME. Para mais informações, consulte Pré-requisitos do Salesforce Marketing Cloud.

Problema: a transferência é bem-sucedida, mas nenhum registro é carregado

Resolução:é preciso ter as permissões Read e Write para Locais de arquivos para ler o conteúdo de uma extensão de dados. Verifique se os escopos do Salesforce Marketing Cloud incluem File Locations: Read, Write.

Erro: FAILED_PRECONDITION: There was an issue connecting to API.

Resolução:esse erro pode ocorrer quando você inclui um anexo de rede na transferência, mas não configura o Public NAT e a lista de permissões de IP. Para resolver esse erro, siga as etapas em Criar um anexo de rede e defina um endereço IP estático.

Preços

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

A seguir