Carregue dados do Facebook Ads para o BigQuery

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Nota: para receber apoio técnico ou enviar feedback sobre esta funcionalidade, contacte [e-mail].

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.

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:

• Ads
• AdInsights
• AdInsightsActions

Para obter informações sobre como os relatórios do Facebook Ads são transformados em tabelas e vistas do BigQuery, consulte o artigo Transformação de dados do Facebook Ads.

Opção de denúncia	Apoio técnico
Frequência de repetição	Diariamente, à hora em que a transferência de dados é criada pela primeira vez (predefinição) Pode configurar a hora do dia.
Período de atualização	Últimos 30 dias Configurável até 30 dias.

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 o 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 do Facebook Ads.

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 AdInsightsAction, 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 da última execução da transferência. A janela de atualização não se aplica à tabela AdAccounts.

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, em 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 está 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 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.

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 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 acerca das combinações de discriminações permitidas, consulte o artigo Combinar discriminações
  • actionBreakdowns: especifique as análises detalhadas 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 conetor 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 discriminações

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 seu token de acesso de 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. Caso contrário, siga os passos em Pré-requisitos dos anúncios do Facebook para gerar um novo token de acesso do utilizador de longa duração.
• 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 o 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

Não existe qualquer custo para transferir dados do Facebook Ads para o BigQuery enquanto esta funcionalidade estiver em pré-visualização.

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.