Carregar dados de anúncios do Facebook no BigQuery

Para programar transferências de dados recorrentes dos anúncios do Facebook para o BigQuery, crie uma configuração de transferência para especificar quais objetos de dados transferir e com que frequência programar a transferência. É possível criar uma configuração de transferência usando o console Google Cloud , a ferramenta de linha de comando bq ou o serviço de transferência de dados do BigQuery API. Depois de configurar a transferência, o serviço de transferência de dados do BigQuery transfere os dados mais recentes para uma tabela do BigQuery na programação especificada.

Para saber como funciona uma transferência do Facebook Ads, consulte Introdução às transferências do Facebook Ads.

Limitações

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

• A partir de 6 de julho de 2026, o suporte ao relatório AdInsightsMMM será desativado temporariamente. Para mais informações, consulte 6 de julho de 2026.
• O tempo mínimo de intervalo entre as transferências de dados de anúncios recorrentes do Facebook é de 24 horas. O intervalo padrão para uma transferência de dados recorrente é de 24 horas.
• O serviço de transferência de dados do BigQuery para anúncios do Facebook só é compatível com um conjunto fixo de tabelas. Não há suporte para relatórios personalizados.
• As transferências de dados dos Anúncios do Facebook têm uma duração máxima de seis horas. Uma transferência falhará se demorar mais do que essa duração máxima.
• Transferências incrementais não são aceitas para tabelas AdInsights, AdInsightsActions, Ads, Campaigns e AdSets. Quando você cria uma transferência de dados que inclui as tabelas AdInsights, AdInsightsActions, Ads, Campaigns e AdSets, e você especificou uma data nas Opções de programação, todos os dados disponíveis para essa data são transferidos.
• O serviço de transferência de dados do BigQuery oferece suporte a uma janela de atualização de até 30 dias para as tabelas AdInsights, AdInsightsActions, Ads, Campaigns e AdSets. A janela de atualização se refere ao número de dias que uma transferência de dados recupera dados de origem. Quando você executa uma transferência de dados pela primeira vez, a transferência de dados recupera todos os dados de origem disponíveis na janela de atualização.

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

  Se o token de acesso do usuário de longa duração expirar, você poderá conseguir o novo acessando os detalhes da transferência de dados e clicando em Editar. Na página de transferência de edição, siga as mesmas etapas dos pré-requisitos do Facebook Ads para gerar um novo token de acesso do usuário de longa duração.

• Para usar um anexo de rede com essa transferência de dados, primeiro crie um anexo de rede definindo um endereço IP estático.

• Se o anexo de rede e a instância de máquina virtual (VM) configurados estiverem localizados em regiões diferentes, poderá haver movimentação de dados entre regiões ao transferir dados dos anúncios do Facebook.

Antes de começar

As seções a seguir descrevem as etapas que você precisa seguir antes de criar uma transferência de dados de anúncios do Facebook.

Pré-requisitos dos Anúncios do Facebook

Verifique se você tem as seguintes informações dos Anúncios do Facebook ao criar uma transferência de dados dos Anúncios do Facebook.

Parâmetros dos Anúncios do Facebook	Descrição
clientID	O nome do ID do app para o cliente OAuth 2.0.
clientSecret	A chave secreta do app para o cliente OAuth 2.0.
refreshToken	O token de acesso do usuário de longa duração, também conhecido como token de atualização.

Para conseguir um clientID e um clientSecret, siga estas etapas:

1. Crie um app de desenvolvedor do Facebook com o tipo de app Business.
2. No painel do Aplicativo do Facebook, clique em Configurações do aplicativo > Básico e encontre o ID do aplicativo. e o secret do app que corresponde ao app.

Para conseguir um token de acesso do usuário de longa duração, também conhecido como token de atualização, execute as seguintes etapas:

1. No console Google Cloud , siga as etapas para criar uma transferência dos Anúncios do Facebook.

2. Na seção Detalhes da fonte de dados, copie o URI de redirecionamento listado após o campo Atualizar token.

3. Clique no painel do Aplicativo do Facebook e em Configurar na seção Login do Facebook para empresas.

   

4. Na página Configurações, insira o URL de redirecionamento no campo URIs de redirecionamento OAuth válidos e clique em Salvar.

5. Volte para o console Google Cloud . Na seção Detalhes da fonte de dados, clique em Autorizar. Você será redirecionado para uma página de autenticação do Facebook.

   

6. Selecione o aplicativo de desenvolvedor do Facebook para autorizar a conta que se conecta com o serviço de transferência de dados do BigQuery.

7. Quando terminar, clique em Ok para voltar ao console do Google Cloud . O token de acesso do usuário de longa duração agora é preenchido na configuração de transferência.

Os tokens de acesso do usuário de longa duração expiram após 60 dias. Para mais informações sobre como receber um novo token de acesso do usuário de longa duração, consulte Limitações.

Atualizar alternativas de token

Se preferir, forneça um token de atualização ao criar uma transferência de dados, se você tiver conseguido um usando um dos seguintes métodos:

• Gere um token de acesso do usuário de longa duração usando a API Graph. As permissõ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 usuário do sistema. Um token de usuário do sistema permite adicionar manualmente recursos, como contas de anúncios, para serem incluídos na transferência de dados. Se um token de usuário do sistema expirar, você deverá atualizar manualmente a configuração de transferência com novas credenciais. Você também tem a opção de criar um token que não expire quando você criar um token de usuário. Para mais informações, consulte Tokens de acesso compatíveis.

Pré-requisitos do BigQuery

• Verifique se você realizou 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 dados.
• Se quiser configurar notificações de execução de transferência do Pub/Sub, verifique se você tem a permissão pubsub.topics.setIamPolicy do Identity and Access Management (IAM). Se você só configura notificações por e-mail, as permissões do Pub/Sub não são necessárias. Para mais informações, consulte Notificações de execução do serviço de transferência de dados 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 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.

Criar uma transferência de dados dos Anúncios do Facebook

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

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

   • Em Anexo de rede, selecione uma opção no menu. Antes de usar um anexo de rede com essa transferência de dados, é preciso criar um anexo de rede definindo um endereço IP estático.
   • Em ID do cliente, digite o ID do app.
   • Em Chave secreta do cliente, digite a chave secreta do app.
   • Em Token de atualização, insira o ID do token de acesso do usuário de longa duração clicando em Autorizar. Como alternativa, se você já tem um token de atualização ou de usuário do sistema, insira-o diretamente nesse campo. Para saber como recuperar um token de acesso do usuário de longa duração, consulte os pré-requisitos do Facebook Ads.
   • Para objetos dos Anúncios do Facebook a serem transferidos: especifique os relatórios ou objetos dos Anúncios do Facebook que serão incluídos na transferência.
   • Selecione Buscar dados somente para contas de anúncios autorizadas para buscar dados apenas de contas de publicidade autorizadas no seu app do Facebook. Encontre as contas de publicidade autorizadas em Configurações do app > Avançado e na seção Contas de publicidade.
   • Em ActionsCollections, especifique uma ou mais coleções de ações.
   • Em Detalhamentos genéricos, selecione os detalhamentos genéricos para os dados de insights. Esses detalhamentos determinam como os dados transferidos são organizados nas tabelas AdInsights e AdInsightsActions. Os anúncios do Facebook só permitem algumas combinações de detalhamentos. Para mais informações sobre as combinações de detalhamento permitidas, consulte Como combinar detalhamentos.
   • Em Detalhes da ação, selecione os detalhamentos dos dados de insights. Esses detalhamentos determinam como os dados transferidos são organizados na tabela AdInsightsActions. Para informações sobre como combinar detalhamentos, consulte Combinar detalhamentos.
   • Em Janela de atualização, especifique uma duração da janela de atualização.

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 a Notificação por e-mail. Quando essa opção está ativada, o administrador de transferência recebe uma notificação por e-mail quando uma execução de transferência falha.
   • Para ativar as notificações de execução de transferência do Pub/Sub para essa transferência de dados, 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.

Quando essa transferência de dados é executada, o serviço de transferência de dados do BigQuery preenche automaticamente as tabelas a seguir.

Nome da tabela	Descrição
AdAccounts	As contas de anúncios disponíveis para um usuário.
AdInsights	Relatório de insights de anúncios para todas as contas de anúncios.
AdInsightsActions	Relatório de ações dos insights de anúncios para todas as contas de anúncios.
AdInsightsMMM Observação:o suporte para esse relatório está temporariamente desativado. Para mais informações, consulte 6 de julho de 2026 .	Relatório de modelagem da mixagem de marketing (MMM) de insights de anúncios para todas as contas de anúncios.
Ads	Relatórios de anúncios para todas as contas de anúncios.
AdCreatives	Relatórios de criativos do anúncio para todas as contas de anúncios.
AdSets	Relatórios de conjuntos de anúncios para todas as contas de anúncios.
Campaigns	Relatórios de campanha para todas as contas de anúncios.
AdImages	Relatórios de imagens de anúncios para todas as contas de anúncios.
AdLabels	Relatórios de rótulos de anúncio para todas as contas de anúncios.
Businesses	Contas comerciais da Meta associadas ao usuário.
CustomAudiences	Relatórios de público-alvo personalizado para todas as contas de anúncios.

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=DISPLAY_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 (por exemplo, facebook-ads).
• DISPLAY_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 de dados.
• PARAMETERS é o parâmetro da configuração de transferência de dados criada no formato JSON. Por exemplo, --params='{"param":"param_value"}'. Confira a seguir os parâmetros para uma transferência dos Anúncios do Facebook:
  • connector.authentication.oauth.clientId: o nome do ID do app para o cliente OAuth 2.0.
  • connector.authentication.oauth.clientSecret: a chave secreta do app para o cliente OAuth 2.0.
  • connector.authentication.oauth.refreshToken: o ID do token de longa duração.
  • connector.authorizedAdAccountsOnly: se definido como true, o conector só vai recuperar dados de contas de publicidade autorizadas no seu app do Facebook. Encontre as contas de publicidade autorizadas em Configurações do app > Avançado e na seção Contas avançadas.
  • connector.actionCollections: 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 uma lista completa de valores de actionCollections, consulte Coleções de ações.
    • Para mais informações, consulte Insights de anúncios.
  • connector.genericBreakdowns: especifique os detalhamentos genéricos para os dados de insights. Esses detalhamentos determinam como os dados transferidos são organizados nas tabelas AdInsights e AdInsightsActions. Os anúncios do Facebook só permitem algumas combinações de detalhamentos. Para mais informações sobre as combinações de detalhamento permitidas, consulte Como combinar detalhamentos.
  • actionBreakdowns: especifique os detalhamentos da ação para os dados de insights. Esses detalhamentos determinam como os dados transferidos são organizados nas tabelas AdInsights e AdInsightsActions. Para informações sobre como combinar detalhamentos, consulte Combinar detalhamentos.
  • connector.insightsLevel: nível de agregação para buscar dados de insights (por exemplo, anúncio, conjunto de anúncios, campanha, conta).
  • connector.insightsTimeIncrement: número de dias para agrupar os dados agregados de insights (entre 1 e 7).
  • Observação:o período escolhido se aplica não apenas às tabelas de insights (AdInsights e AdInsightsActions), mas também filtra as tabelas Ads, Campaigns e AdSets usando o parâmetro time_range do Facebook.

Por exemplo, o comando a seguir cria uma transferência de dados dos Anúncios do Facebook no projeto padrão 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 você salva 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 programação. Em cada execução de transferência, o conector dos anúncios do Facebook transfere todos os dados disponíveis dos anúncios do Facebook para o BigQuery.

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

Para saber como os dados transferidos são mapeados para os campos da API do Meta, consulte Transformação de relatórios do Facebook Ads.

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. É possível especificar coleções de ações ao configurar a transferência.

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

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

Atenção: quanto mais coleções de ações você especificar para uma transferência, maior será a probabilidade de atingir os limites de taxa impostos pelo Facebook Ads.

Confira abaixo uma lista de coleções de ações compatíveis com uma 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

Como combinar detalhamentos

Os anúncios do Facebook têm restrições sobre quais colunas podem ser selecionadas juntas. O uso dessas combinações restritas vai fazer com que a transferência de dados falhe.

Para mais informações sobre quais detalhamentos podem ser combinados, consulte Como combinar detalhamentos.

Resolver problemas na configuração de transferência

Se você estiver com problemas para configurar uma transferência de dados do Facebook Ads, tente as seguintes etapas de solução de problemas:

• Verifique se o token de acesso do usuário expirou usando o depurador de tokens de acesso do Facebook. Os tokens de acesso do usuário de longa duração expiram após 60 dias. Se o token de acesso do usuário de longa duração tiver expirado, navegue até os detalhes da transferência e clique em Editar para modificar sua configuração de transferência. Na página de transferência de edição, siga as mesmas etapas nos pré-requisitos do Facebook Ads para gerar uma nova.

• Verifique se o token de acesso do usuário de longa duração é gerado com as permissões necessárias: ads_management, ads_read e business_management. Para verificar as permissões no seu token de acesso de usuário de longa duração, insira o seguinte link no navegador:

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

  Em que TOKEN é o valor do token de acesso do usuário de longa duração.

  Se você não tiver as permissões necessárias, gere um novo token de acesso do usuário de longa duração seguindo as etapas em Pré-requisitos do Facebook Ads.

• Verifique se há algum item que precise de atenção na guia Ações necessárias no painel do app Facebook.

Talvez você encontre as seguintes mensagens relacionadas aos 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 há fluxos de trabalho paralelos usando os mesmos apps ou credenciais. Se os erros persistirem, tente atualizar suas permissões para Acesso avançado para aumentar a cota de limitação de taxa. Para mais informações, consulte Limitação de taxa da API Marketing.

Mensagens comuns de métricas de monitoramento

Também é possível verificar as métricas de monitoramento do serviço de transferência de dados do BigQuery para determinar a causa de uma falha na transferência de dados. A tabela a seguir lista 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. Você também pode encontrar esse erro com a mensagem This combination of action and generic breakdowns is not allowed.. Para informações sobre combinações de detalhamento válidas, consulte Como combinar detalhamentos.
PERMISSION_DENIED	As credenciais são inválidas
UNAUTHENTICATED	A autenticação é necessária
SERVICE_UNAVAILABLE	O serviço está temporariamente impossibilitado de processar esta transferência de dados
DEADLINE_EXCEEDED	A transferência de dados não foi concluída dentro do período máximo de seis horas
NOT_FOUND	Um recurso solicitado não foi encontrado
INTERNAL	Outro motivo fez com que o conector falhasse
FAILED_PRECONDITION	Esse erro pode aparecer com a mensagem There was an issue connecting to Facebook Ads API.. Ele pode ocorrer quando você inclui um anexo de rede com a transferência, mas não configurou corretamente a conversão de endereços de rede (NAT) pública. Para resolver esse erro, siga as etapas para criar um anexo de rede definindo um endereço IP estático. Esse erro também pode aparecer devido à limitação da taxa. Nesses casos, faça o seguinte: Fluxos de trabalho paralelos que usam o mesmo usuário do Facebook Ads ou credenciais do app podem fazer com que você atinja os limites de taxa com mais frequência. Use credenciais de usuário ou app diferentes fora da configuração de transferência. Divida suas transferências de dados para ter menos dados em cada uma e execute cada transferência de dados de forma independente para ter algum tempo entre elas e permitir que os limites de taxa sejam recuperados. Verifique se a transferência de dados não inclui um cálculo de detalhamento caro, muitos detalhamentos ou muitas coleções de ações.
RESOURCE_EXHAUSTED	A cota ou o limite de uma fonte de dados foi esgotado

A seguir

• Saiba mais sobre o serviço de transferência de dados do BigQuery.
• Saiba mais sobre como trabalhar com transferências, como visualizar configurações e acessar o histórico de execução.
• Saiba como carregar dados com operações do BigQuery Omni.