Carregue dados do Facebook Ads para o BigQuery

Pode carregar dados do Facebook Ads para o BigQuery através do conetor do Serviço de transferência de dados do BigQuery para o Facebook Ads. Com o Serviço de transferência de dados do BigQuery, pode agendar tarefas de transferência recorrentes que adicionam os dados mais recentes dos seus anúncios do Facebook ao BigQuery.

Vista geral do conetor

O Serviço de transferência de dados do BigQuery para o conetor do Facebook Ads suporta as seguintes opções para a transferência de dados.

Opções de transferência de dados	Apoio técnico
Relatórios suportados	O Serviço de transferência de dados do BigQuery para o Facebook Ads suporta a transferência dos seguintes relatórios do Facebook Ads: AdAccounts AdInsights AdInsightsActions Para obter informações sobre como os relatórios de anúncios do Facebook são transformados em tabelas e vistas do BigQuery, consulte o artigo Transformação de relatórios de anúncios do Facebook.
Frequência de repetição	O conetor do Facebook Ads suporta transferências de dados diárias. Por predefinição, as transferências de dados são agendadas para a hora em que são criadas. Pode configurar a hora da transferência de dados quando configurar a transferência de dados.
Período de atualização	O conetor do Facebook Ads obtém dados do Facebook Ads de até 30 dias no momento em que a transferência de dados é executada. Não pode configurar o período de atualização para este conetor. Para mais informações, consulte o artigo Períodos de atualização.
Disponibilidade de dados de preenchimento	Execute um repreenchimento de dados para obter dados fora da transferência de dados agendada. Pode obter dados até ao período permitido pela política de retenção de dados na sua origem de dados.

Limitações

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

• O intervalo de tempo mínimo entre transferências de dados recorrentes do Facebook Ads é de 24 horas. O intervalo predefinido para uma transferência de dados recorrente é de 24 horas.
• O Serviço de transferência de dados do BigQuery para o Facebook Ads só suporta um conjunto fixo de tabelas. Os relatórios personalizados não são suportados.
• As transferências de dados do Facebook Ads têm uma duração máxima de seis horas. Uma transferência falha se demorar mais do que esta duração máxima.
• As transferências incrementais não são suportadas para tabelas AdInsights e AdInsightsActions. Quando cria uma transferência de dados que inclui as tabelas AdInsights e AdInsightsActions, e especificou uma data em Opções de agendamento, todos os dados disponíveis para essa data são transferidos.
• O Serviço de transferência de dados do BigQuery suporta uma janela de atualização de até 30 dias para as tabelas AdInsights e AdInsightsActions. O período de atualização refere-se ao número de dias a partir dos quais uma transferência de dados vai obter dados de origem. Quando executa uma transferência de dados pela primeira vez, a transferência de dados obtém todos os dados de origem disponíveis na janela de atualização.

• O token de acesso do utilizador de longa duração necessário para as transferências do Facebook Ads expira após 60 dias.

  Se o seu token de acesso do utilizador de longa duração tiver expirado, pode obter um novo navegando para os detalhes da transferência de dados e clicando em Editar. Na página de edição da transferência, siga os mesmos passos nos pré-requisitos dos anúncios do Facebook para gerar um novo token de acesso do utilizador de longa duraçã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 dos anúncios do Facebook.

Carregamento de dados de transferências do Facebook Ads

Quando transfere dados do Facebook Ads para o BigQuery, os dados são carregados em tabelas do BigQuery particionadas por data. A partição da tabela na qual os dados são carregados corresponde à data da origem de dados. Se agendar várias transferências para a mesma data, o Serviço de transferência de dados do BigQuery substitui a partição dessa data específica pelos dados mais recentes. As várias transferências no mesmo dia ou a execução de preenchimentos não resultam em dados duplicados, e as partições para outras datas não são afetadas.

Para tabelas AdInsights e AdInsightsActions, a partição da tabela na qual os dados são carregados corresponde à data da origem de dados.

Para as tabelas AdAccounts, as capturas são feitas uma vez por dia e armazenadas na partição da data de execução da última transferência. A janela de atualização não se aplica à tabela AdAccounts.

Atualize as janelas

Um período de atualização é o número de dias que uma transferência de dados obtém dados quando ocorre uma transferência de dados. Por exemplo, se a janela de atualização for de três dias e ocorrer uma transferência diária, o Serviço de transferência de dados do BigQuery obtém todos os dados da tabela de origem dos últimos três dias. Neste exemplo, quando ocorre uma transferência diária, o Serviço de transferência de dados do BigQuery cria uma nova partição da tabela de destino do BigQuery com uma cópia dos dados da tabela de origem do dia atual e, em seguida, aciona automaticamente execuções de preenchimento para atualizar as partições da tabela de destino do BigQuery com os dados da tabela de origem dos últimos dois dias. As execuções de preenchimento automático acionadas automaticamente substituem ou atualizam incrementalmente a tabela de destino do BigQuery, consoante as atualizações incrementais sejam ou não suportadas no conector do Serviço de transferência de dados do BigQuery.

Quando executa uma transferência de dados pela primeira vez, a transferência de dados obtém todos os dados de origem disponíveis na janela de atualização. Por exemplo, se a janela de atualização for de três dias e executar a transferência de dados pela primeira vez, o Serviço de transferência de dados do BigQuery obtém todos os dados de origem no prazo de três dias.

Para obter dados fora do período de atualização, como dados do histórico, ou para recuperar dados de indisponibilidades ou lacunas de transferência, pode iniciar ou agendar uma execução de preenchimento.

Antes de começar

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

Pré-requisitos dos anúncios do Facebook

Certifique-se de que tem as seguintes informações do Facebook Ads quando criar uma transferência de dados do Facebook Ads.

Parâmetros dos anúncios Facebook	Descrição
clientID	O nome do ID da app para o cliente OAuth 2.0.
clientSecret	O segredo da app para o cliente OAuth 2.0.
refreshToken	A chave de acesso do utilizador de longa duração, também conhecida como chave de atualização.

Para obter um clientID e um clientSecret, siga os passos seguintes:

1. Crie uma app de programador do Facebook com o tipo de app Business.
2. No painel de controlo da app Facebook, clique em Definições da app > Básico e encontre o ID da app e o segredo da app que correspondem à app.

Para obter uma chave de acesso de utilizador de longa duração, também conhecida como chave de atualização, siga os passos seguintes:

1. Na Google Cloud consola, siga os passos para criar uma transferência do Facebook Ads.

2. Na secção Detalhes da origem de dados, copie o URI de redirecionamento apresentado após o campo Token de atualização.

   

3. Clique no painel de controlo da app Facebook, e, de seguida, clique em Configurar na secção Início de sessão no Facebook para empresas.

   

4. Na página Definições, introduza o URL de redirecionamento no campo URIs de redirecionamento OAuth válidos e clique em Guardar.

5. Regresse à Google Cloud consola. Na secção Detalhes da origem de dados, clique em Autorizar. É feito o redirecionamento para uma página de autenticação do Facebook.

   

6. Selecione a app de programador do Facebook para autorizar a conta que se liga ao Serviço de transferência de dados do BigQuery.

7. Quando terminar, clique em OK para regressar à Google Cloud consola. O token de acesso do utilizador de longa duração é agora preenchido na configuração de transferência.

Os tokens de acesso de utilizador de longa duração expiram após 60 dias. Para obter informações sobre como obter um novo token de acesso de utilizador de longa duração, consulte a secção Limitações.

Alternativas ao token de atualização

Em alternativa, pode fornecer um token de atualização quando criar uma transferência de dados se tiver obtido um através de um dos seguintes métodos:

• Gere um token de acesso de utilizador de longa duração através da API Graph. As autorizações ads_management, ads_read e business_management são necessárias para um token válido para a transferência de dados.
• Gere um token de utilizador do sistema. Um token de utilizador do sistema permite-lhe adicionar manualmente recursos, como contas de publicidade, a incluir na transferência de dados. Se um token de utilizador do sistema tiver expirado, tem de atualizar manualmente a configuração de transferência com novas credenciais. Também tem a opção de criar um token que não expira quando cria um token de utilizador do sistema. Para mais informações, consulte o artigo Tokens de acesso suportados.

Pré-requisitos do BigQuery

• Verifique se concluiu todas as ações necessárias para ativar o Serviço de transferência de dados do BigQuery.
• Crie um conjunto de dados do BigQuery para armazenar os seus dados.
• Se pretender configurar notificações de execução de transferências para o Pub/Sub, certifique-se de que tem a autorização de pubsub.topics.setIamPolicygestão de identidade e de acesso (IAM). Se configurar apenas notificações por email, não são necessárias autorizações do Pub/Sub. Para mais informações, consulte Notificações de execução do Serviço de transferência de dados 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.

Crie uma transferência de dados do Facebook Ads

Selecione 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, em Origem, selecione Anúncios do Facebook.

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

   • Para o ID de cliente, introduza o ID da app.
   • Para Segredo do cliente, introduza o segredo da app.
   • Para Atualizar chave, introduza o ID da chave de acesso do utilizador de longa duração clicando em Autorizar. Em alternativa, se já tiver uma chave de atualização ou uma chave de utilizador do sistema, pode introduzir a chave de atualização diretamente neste campo. Para obter informações sobre como obter uma chave de acesso do utilizador de longa duração, consulte os pré-requisitos dos anúncios do Facebook.
   • Para transferir objetos do Facebook Ads: especifique os relatórios ou os objetos do Facebook Ads a incluir nesta transferência.
   • Selecione Obter dados apenas para contas de publicidade autorizadas para obter dados apenas de contas de publicidade autorizadas na sua app do Facebook. Pode encontrar as suas contas de publicidade autorizadas em Definições da app > Avançadas e na secção Contas de publicidade.
   • Para ActionsCollections, especifique uma ou mais coleções de ações.
   • Para Análises detalhadas genéricas, selecione as análises detalhadas genéricas para os dados de estatísticas. Estas discriminações determinam como os dados transferidos são organizados nas tabelas AdInsights e AdInsightsActions. Os anúncios do Facebook só permitem determinadas combinações de discriminações. Para mais informações sobre as combinações de discriminações permitidas, consulte o artigo Combinar discriminações
   • Para Detalhes das ações, selecione os detalhes das ações para os dados de estatísticas. Estas discriminações determinam como os dados transferidos são organizados na tabela AdInsightsActions. Para obter informações sobre a combinação de discriminações, consulte o artigo Combinar discriminações.
   • Para Atualizar janela, especifique uma duração de atualização da janela.

5. Na secção Definições de destino, para Conjunto de dados, selecione 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 agendamento, faça o seguinte:

   • 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 de transferência falha.
   • Para ativar as notificações de execução de transferências do Pub/Sub para esta transferência de dados, 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.

Quando esta transferência de dados é executada, o Serviço de transferência de dados do BigQuery preenche automaticamente as seguintes tabelas.

Nome da tabela	Descrição
AdAccounts	As contas de publicidade disponíveis para um utilizador.
AdInsights	Relatório de estatísticas de anúncios para todas as contas de anúncios.
AdInsightsActions	Relatório de ações de estatísticas de anúncios para todas as contas de anúncios.

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=DISPLAY_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 (por exemplo, facebook-ads).
• DISPLAY_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 de dados.
• PARAMETERS: os parâmetros da configuração de transferência de dados criada no formato JSON. Por exemplo: --params='{"param":"param_value"}'. Seguem-se os parâmetros para uma transferência de anúncios do Facebook:
  • connector.authentication.oauth.clientId: o nome do ID da app para o cliente OAuth 2.0.
  • connector.authentication.oauth.clientSecret: o segredo da app para o cliente OAuth 2.0.
  • connector.authentication.oauth.refreshToken: o ID da chave de longa duração.
  • connector.authorizedAdAccountsOnly: se estiver definido como true, o conector apenas obtém dados de contas de publicidade autorizadas para a sua app do Facebook. Pode encontrar as suas contas de publicidade autorizadas em Definições da app > Avançadas e na secção Contas avançadas.
  • connector.actionCollections: As coleções de ações são objetos que especificam os diferentes tipos de ações que as pessoas realizaram em resposta ao seu anúncio. Para ver uma lista completa dos valores de actionCollections, consulte Coleções de ações.
    • Para mais informações, consulte Estatísticas dos anúncios.
  • connector.genericBreakdowns: especifique as discriminações genéricas para os dados de estatísticas. Estas discriminações determinam como os dados transferidos são organizados nas tabelas AdInsights e AdInsightsActions. Os anúncios do Facebook só permitem determinadas combinações de discriminações. Para mais informações acerca das combinações de discriminações permitidas, consulte o artigo Combinar discriminações.
  • actionBreakdowns: especifique as discriminações de ações para os dados de estatísticas. Estas discriminações determinam como os dados transferidos são organizados nas tabelas AdInsights e AdInsightsActions. Para obter informações sobre a combinação de discriminações, consulte o artigo Combinar discriminações.

Por exemplo, o comando seguinte cria uma transferência de dados do Facebook Ads no projeto predefinido com todos os parâmetros necessários:

bq mk
--transfer_config
--target_dataset=mydataset
--data_source=facebook_ads
--display_name='My Transfer'
--params='{"connector.authentication.oauth.clientId": "1650000000",
    "connector.authentication.oauth.clientSecret":"TBA99550",
    "connector.authentication.oauth.refreshToken":"abcdef",
    "connector.authorizedAdAccountsOnly":true,
    "connector.actionCollections":["Actions", "Conversions"],
    "connector.genericBreakdowns":["PublisherPlatform", "PlatformPosition"],
    "connector.actionBreakdowns":["ActionDevice", "ActionType"]}'

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 Facebook Ads aciona automaticamente uma execução de transferência de acordo com a opção de agendamento. Com cada execução de transferência, o conetor do Facebook Ads transfere todos os dados disponíveis do Facebook Ads para o BigQuery.

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

Para ver informações sobre como os dados transferidos são mapeados para os campos da API Meta, consulte o artigo Transformação de relatórios de anúncios do Facebook.

Coleções de ações

As coleções de ações são objetos que especificam os diferentes tipos de ações que as pessoas realizaram em resposta ao seu anúncio. Pode especificar coleções de ações quando configurar a configuração de transferência.

As coleções de ações representam os campos do tipo list<AdsActionStats> que estão presentes na resposta do ponto final Ad Account, Insights.

Quando uma transferência é concluída, estas coleções de ações são preenchidas na tabela AdInsightsActions.

Atenção: quanto mais coleções de ações especificar para uma transferência, maior é a probabilidade de atingir os limites de taxa impostos pelos anúncios do Facebook.

Segue-se uma lista de recolhas de ações suportadas numa transferência de dados do Facebook Ads:

• ActionValues
• Actions
• AdClickActions
• AdImpressionActions
• CatalogSegmentActions
• CatalogSegmentValue
• CatalogSegmentValueMobilePurchaseRoas
• CatalogSegmentValueOmniPurchaseRoas
• CatalogSegmentValueWebsitePurchaseRoas
• ConversionValues
• Conversions
• ConvertedProductQuantity
• ConvertedProductValue
• CostPer15_secVideoView
• CostPer2SecContinuousVideoView
• CostPerActionType
• CostPerAdClick
• CostPerConversion
• CostPerOneThousandAdImpression
• CostPerOutboundClick
• CostPerThruplay
• CostPerUniqueActionType
• CostPerUniqueConversion
• CostPerUniqueOutboundClick
• InteractiveComponentTap
• MobileAppPurchaseRoas
• OutboundClicks
• OutboundClicksCtr
• PurchaseRoas
• UniqueActions
• UniqueConversions
• UniqueOutboundClicks
• UniqueOutboundClicksCtr
• UniqueVideoView15_sec
• Video15_secWatchedActions
• Video30_secWatchedActions
• VideoAvgTimeWatchedActions
• VideoContinuous2SecWatchedActions
• VideoP100_watchedActions
• VideoP25WatchedActions
• VideoP50WatchedActions
• VideoP75WatchedActions
• VideoP95WatchedActions
• VideoPlayActions
• VideoPlayCurveActions
• VideoPlayRetentionGraphActions
• VideoTimeWatchedActions
• WebsiteCtr
• WebsitePurchaseRoas

Combinar detalhes

Os anúncios do Facebook têm restrições quanto às colunas que podem ser selecionadas em conjunto. A utilização destas combinações restritas faz com que a transferência de dados falhe.

Para mais informações sobre as discriminações que podem ser combinadas, consulte o artigo Combinar discriminações.

Resolva problemas de configuração da transferência

Se tiver problemas ao configurar uma transferência de dados do Facebook Ads, experimente os seguintes passos de resolução de problemas:

• Verifique se a sua chave de acesso de utilizador expirou através do depurador de chaves de acesso do Facebook. Os tokens de acesso do utilizador de longa duração expiram após 60 dias. Se o token de acesso do utilizador de longa duração tiver expirado, navegue para os detalhes da transferência e, de seguida, clique em Editar para modificar a configuração da transferência. Na página de edição da transferência, siga os mesmos passos em Pré-requisitos dos anúncios do Facebook para gerar um novo.

• Verifique se a chave de acesso do utilizador de longa duração é gerada com as autorizações necessárias: ads_management, ads_read e business_management. Pode verificar as autorizações na sua chave de acesso de utilizador de longa duração introduzindo o seguinte link no navegador:

  https://graph.facebook.com/me/permissions?access_token=TOKEN
  

  Em que TOKEN é o valor do símbolo de acesso do utilizador de longa duração.

  Se não tiver as autorizações necessárias, gere um novo token de acesso de utilizador de longa duração seguindo os passos descritos nos pré-requisitos dos anúncios do Facebook.

• Consulte o separador Ações necessárias no painel de controlo da app Facebook para ver todos os itens que requerem atenção.

Pode encontrar as seguintes mensagens de erro relacionadas com erros de limite de taxa da API Meta:

Erro: There have been too many calls from this ad-account. Wait a bit and try again.

Resolução: verifique se não existem fluxos de trabalho paralelos a usar as mesmas apps ou credenciais. Se estes erros persistirem, experimente atualizar as suas autorizações para acesso avançado para obter uma quota de limitação de taxa mais elevada. Para mais informações, consulte o artigo Limites de taxa da API Google Marketing.

Mensagens de métricas de monitorização comuns

Também pode verificar as métricas de monitorização do Serviço de transferência de dados do BigQuery para determinar a causa de uma falha de transferência de dados. A tabela seguinte apresenta algumas mensagens ERROR_CODE comuns para transferências de dados de anúncios do Facebook.

Erro	Descrição
INVALID_ARGUMENT	A configuração fornecida é inválida. Também pode encontrar este erro com a mensagem This combination of action and generic breakdowns is not allowed. Para obter informações sobre combinações de discriminações válidas, consulte o artigo Combinar discriminações.
PERMISSION_DENIED	As credenciais são inválidas
UNAUTHENTICATED	É necessária autenticação
SERVICE_UNAVAILABLE	O serviço não consegue processar esta transferência de dados temporariamente
DEADLINE_EXCEEDED	A transferência de dados não terminou dentro da duração máxima de seis horas
NOT_FOUND	Não foi possível encontrar um recurso solicitado
INTERNAL	Outro motivo causou a falha do conetor
RESOURCE_EXHAUSTED	Foi esgotada uma quota ou um limite da origem de dados

Preços

Para ver informações de preços sobre as transferências de anúncios do Facebook, consulte os preços do serviço de transferência de dados.

O que se segue?

• Saiba mais acerca do Serviço de transferência de dados do BigQuery.
• Saiba mais sobre como trabalhar com transferências, como ver configurações e o histórico de execução.
• Saiba como carregar dados com operações em várias nuvens.