Referência do conector de ingestão de Meta Ads

info

Beta

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página de Pré-visualizações . Veja as prévias do Gerenciador Databricks.

Esta página contém material de referência para o conector de ingestão de Meta Ads no Databricks LakeFlow Connect.

transformações automáticas de dados

O Databricks transforma os tipos de dados Meta Ads em tipos de dados compatíveis com Delta da seguinte forma:

Tipo de anúncios Meta	Tipo Delta
string	String
int	Integer
long	Long
Float	Float
double	Double
boolean	Booleana
datetime	Carimbo de data/hora
Data	Data
Lista	matriz
map	Mapa
enumeração	String

Tipo de anúncios Meta	Tipo Delta
string	String
int	Integer
long	Long
Float	Float
double	Double
boolean	Booleana
datetime	Carimbo de data/hora
Data	Data
Lista	matriz
map	Mapa
enumeração	String

Objetos suportados

O conector Meta Ads suporta a ingestão dos seguintes objetos:

Objeto	Descrição
anúncios	Anúncios individuais em suas campanhas
conjuntos_de_anúncios	Conjuntos de anúncios que agrupam anúncios com segmentação, orçamento e configurações programáticas compartilhadas.
campanhas	Objetos de campanha de nível superior que contêm conjuntos de anúncios
imagens_de_anúncio	Imagem ativa usada em anúncios
insights_de_anúncios	dados de desempenho e análises para anúncios, conjuntos de anúncios, campanhas ou contas
anúncios criativos	Elementos criativos (imagens, vídeos, texto) usados em anúncios
públicos_personalizados	Definições de público-alvo personalizadas para segmentação
vídeos_de_anúncios	Vídeo ativo usado em anúncios
conversões_personalizadas	Definições de eventos de conversão personalizados
Relatórios prontos (21 tabelas)	Variantes ad_insights prontas para uso com uma configuração fixa por relatório.
relatório_personalizado	Relatório de percepções definido pelo usuário. Configure o relatório com custom_report_options e nomeie a saída com destination_table.

Objeto	Descrição
anúncios	Anúncios individuais em suas campanhas
conjuntos_de_anúncios	Conjuntos de anúncios que agrupam anúncios com segmentação, orçamento e configurações programáticas compartilhadas.
campanhas	Objetos de campanha de nível superior que contêm conjuntos de anúncios
imagens_de_anúncio	Imagem ativa usada em anúncios
insights_de_anúncios	dados de desempenho e análises para anúncios, conjuntos de anúncios, campanhas ou contas
anúncios criativos	Elementos criativos (imagens, vídeos, texto) usados em anúncios
públicos_personalizados	Definições de público-alvo personalizadas para segmentação
vídeos_de_anúncios	Vídeo ativo usado em anúncios
conversões_personalizadas	Definições de eventos de conversão personalizados
Relatórios prontos (21 tabelas)	Variantes ad_insights prontas para uso com uma configuração fixa por relatório.
relatório_personalizado	Relatório de percepções definido pelo usuário. Configure o relatório com custom_report_options e nomeie a saída com destination_table.

ad_insights opções de configuração

O objeto ad_insights suporta opções de configuração adicionais para analisar dados de desempenho.

data de início

Defina a data mais antiga a partir da qual os dados históricos ad_insights devem ser ingeridos. A API secreta retém dados por aproximadamente 36 meses, portanto start_date deve estar dentro dos últimos 36 meses. Se não estiver definido, o conector assume por padrão 36 meses antes da data atual.

Níveis de granularidade

Especifique o nível em que deseja obter as métricas de desempenho:

• account: nível da conta
• campaignNível de campanha.
• adset: Conjunto de anúncios em nível de conjunto.
• ad: métricas em nível de anúncio (default)

Dimensões de decomposição

Configure as dimensões de detalhamento para segmentar os dados de desempenho:

• ageFaixas etárias
• gender: Gênero
• country: País
• regionRegião geográfica
• dmaÁrea de mercado designada (somente nos EUA)
• device_platformPlataforma do dispositivo (móvel, computador, etc.)
• placement: Local de veiculação do anúncio
• publisher_platformPlataforma de publicação (Facebook, Audience Network, etc.)
• impression_deviceTipo de dispositivo para impressões

Dimensões de detalhamento da ação

Configure as dimensões de detalhamento de ações para analisar as ações de conversão:

• action_typeTipo de ação de conversão
• action_destinationDestino da ação de conversão
• action_carousel_card_idIdentificador do cartão do carrossel
• action_carousel_card_nameNome do cartão do carrossel
• action_video_soundConfiguração de som do vídeo
• action_video_typeTipo de vídeo

incremento de tempo

Configure o período de agregação para os dados ad_insights :

• all_daysUm único bucket que abrange todo o intervalo de tempo ( default API de percepções).
• monthlyUm balde por mês civil.
• Um número inteiro de dias como uma string (por exemplo, "1" para intervalos diários, "7" para intervalos semanais).

A API de ocultação não suporta incrementos de tempo por hora.

Hora do relatório de ação

Configure o carimbo de data/hora usado para relatar as estatísticas de ações:

• impressionAs conversões são registradas na data da impressão que as gerou.
• conversionAs conversões são registradas na data em que ocorreram.
• mixedAs conversões por clique utilizam o tempo de impressão, enquanto as conversões por viewutilizam o tempo de conversão.
• lifetime: Conversões ao longo da vida útil da entidade.

Janelas de atribuição

Configure as janelas de atribuição para as ações.

• 1d_click, 7d_click: Janelas de atribuição de clique
• 1d_view: janela de atribuição de visualização
• 7d_view, 28d_view: Janelas de atribuição view-through. Descontinuado pela Meta e não é mais suportado pelo conector.

Você pode especificar vários valores (por exemplo, ["7d_click", "1d_view"]). Se action_attribution_windows não estiver definido, o conector usa as configurações de atribuição default da sua account Meta Ads. Para obter uma lista de valores, consulte a referência API de privacidade da Meta.

Janela de retrospectiva

Configure até que ponto o conector reassimila dados (em dias) em cada sincronização. A janela de lookback se aplica a ad_insights, custom_report e relatórios predefinidos. Se não for definido, o default é 7 dias.

• Reingestão de intervalo de tempo : Em cada sincronização após a primeira, o conector extrai dados para [last_sync_cursor - <N> days, today] para que as conversões que chegam atrasadas sejam capturadas. Se custom_insights_lookback_window não estiver definido, o conector reengere os últimos 7 dias por default.
• Atribuição fallback : Quando você define custom_insights_lookback_window explicitamente e não definiu action_attribution_windows, o conector também passa <N>d_click,1d_view como a janela de atribuição para a API escondida. Para controlar a atribuição independentemente do lookback, defina action_attribution_windows.

Relatórios pré-criados

Relatórios predefinidos são variantes ad_insights prontas para uso. Cada relatório predefinido emite uma chamada Meta /insights com uma combinação fixa de nível, detalhamento e detalhamento de ação — nenhuma configuração é necessária. Ao contrário de ad_insights, os relatórios predefinidos não são configuráveis.

Para ingerir um relatório pré-criado, defina source_table como o nome do relatório. connector_options são opcionais. Um relatório pré-criado é executado sem nenhum (usando os defaults), mas é possível definir start_date em meta_ads_options para controlar o intervalo de datas.

Relatórios predefinidos disponíveis

Cada relatório pré-criado mapeia para uma solicitação Meta /insights fixa.

Relatório (source_table)	Categoria	Nível	Detalhamentos	Detalhamentos da ação	Conjunto de métricas
basic_ad_report	Básico	ad	—	action_type	Métricas principais
basic_ad_set_report	Básico	adset	—	action_type	Métricas principais
basic_campaign_report	Básico	campaign	—	action_type	Métricas principais
basic_all_levels_report	Básico	ad	—	action_type	Métricas principais (com nomes de anúncios, conjuntos de anúncios e campanhas)
delivery_device_report	Entrega	ad	device_platform	action_type	Métricas principais
delivery_platform_report	Entrega	ad	publisher_platform	action_type	Métricas principais
delivery_platform_and_device_report	Entrega	ad	publisher_platform, device_platform	action_type	Métricas principais
delivery_purchase_roas_report	Entrega	ad	—	action_type	Conversão / ROAS
demographics_age_report	Dados demográficos	ad	age	action_type	Métricas principais
demographics_gender_report	Dados demográficos	ad	gender	action_type	Métricas principais
demographics_age_and_gender_report	Dados demográficos	ad	age, gender	action_type	Métricas principais
demographics_country_report	Dados demográficos	ad	country	action_type	Métricas principais
demographics_region_report	Dados demográficos	ad	region	action_type	Métricas principais
demographics_dma_region_report	Dados demográficos	ad	comscore_market	action_type	Métricas principais
action_canvas_component_report	Ação	ad	—	action_type	Conversão / ROAS
action_carousel_card_report	Ação	ad	—	action_carousel_card_id, action_carousel_card_name	Conversão / ROAS
action_conversion_device_report	Ação	ad	device_platform	action_type	Conversão / ROAS
action_product_id_report	Ação	ad	product_id	action_type	Conversão / ROAS
action_reactions_report	Ação	ad	—	action_reaction	actions, action_values
action_video_sound_report	Ação	ad	—	action_video_sound	Engajamento de vídeo
action_video_view_type_report	Ação	ad	—	action_video_type	Engajamento de vídeo

Relatório (source_table)	Categoria	Nível	Detalhamentos	Detalhamentos da ação	Conjunto de métricas
basic_ad_report	Básico	ad	—	action_type	Métricas principais
basic_ad_set_report	Básico	adset	—	action_type	Métricas principais
basic_campaign_report	Básico	campaign	—	action_type	Métricas principais
basic_all_levels_report	Básico	ad	—	action_type	Métricas principais (com nomes de anúncios, conjuntos de anúncios e campanhas)
delivery_device_report	Entrega	ad	device_platform	action_type	Métricas principais
delivery_platform_report	Entrega	ad	publisher_platform	action_type	Métricas principais
delivery_platform_and_device_report	Entrega	ad	publisher_platform, device_platform	action_type	Métricas principais
delivery_purchase_roas_report	Entrega	ad	—	action_type	Conversão / ROAS
demographics_age_report	Dados demográficos	ad	age	action_type	Métricas principais
demographics_gender_report	Dados demográficos	ad	gender	action_type	Métricas principais
demographics_age_and_gender_report	Dados demográficos	ad	age, gender	action_type	Métricas principais
demographics_country_report	Dados demográficos	ad	country	action_type	Métricas principais
demographics_region_report	Dados demográficos	ad	region	action_type	Métricas principais
demographics_dma_region_report	Dados demográficos	ad	comscore_market	action_type	Métricas principais
action_canvas_component_report	Ação	ad	—	action_type	Conversão / ROAS
action_carousel_card_report	Ação	ad	—	action_carousel_card_id, action_carousel_card_name	Conversão / ROAS
action_conversion_device_report	Ação	ad	device_platform	action_type	Conversão / ROAS
action_product_id_report	Ação	ad	product_id	action_type	Conversão / ROAS
action_reactions_report	Ação	ad	—	action_reaction	actions, action_values
action_video_sound_report	Ação	ad	—	action_video_sound	Engajamento de vídeo
action_video_view_type_report	Ação	ad	—	action_video_type	Engajamento de vídeo

Cada relatório predefinido usa um de três conjuntos de métricas, que determinam as colunas incluídas na saída:

Conjunto de métricas	Colunas
Métricas principais	reach, impressions, frequency, spend, cpm, cpc, cost_per_inline_link_click, ctr, inline_link_click_ctr, inline_link_clicks, actions, cost_per_action_type (array)
Conversão / ROAS	inline_link_clicks, outbound_clicks, website_purchase_roas, mobile_app_purchase_roas (array)
Engajamento de vídeo	video_thruplay_watched_actions, video_30_sec_watched_actions, video_p25_watched_actions, video_p50_watched_actions, video_p75_watched_actions, video_p100_watched_actions, video_avg_time_watched_actions (array)

Conjunto de métricas	Colunas
Métricas principais	reach, impressions, frequency, spend, cpm, cpc, cost_per_inline_link_click, ctr, inline_link_click_ctr, inline_link_clicks, actions, cost_per_action_type (array)
Conversão / ROAS	inline_link_clicks, outbound_clicks, website_purchase_roas, mobile_app_purchase_roas (array)
Engajamento de vídeo	video_thruplay_watched_actions, video_30_sec_watched_actions, video_p25_watched_actions, video_p50_watched_actions, video_p75_watched_actions, video_p100_watched_actions, video_avg_time_watched_actions (array)

Colunas de saída

Cada linha de relatório pré-construído inclui date_start, date_stop, account_id, as colunas de entidade e hierarquia do relatório (por exemplo, ad_id, adset_id, campaign_id e nomes, quando aplicável), qualquer coluna de detalhamento (por exemplo, age, device_platform), o breakdown_hash derivado e a chave primária insight_id. As colunas de métrica dependem do conjunto de métricas do relatório. As colunas de Ação e ROAS são do tipo array<string>.

Comportamento do relatório pré-construído

• Cada linha é identificada exclusivamente por insight_id. O conector sincroniza dados incrementalmente, usando date_stop como cursor.
• A configuração do relatório — level, breakdowns, action_breakdowns, time_increment (diariamente), janelas de atribuição (7d_click, 1d_view) e action_report_time (mixed) — é fixa por relatório e não pode ser substituída usando meta_ads_options.
• É possível definir opcionalmente start_date (default: 36 meses antes de hoje) e custom_insights_lookback_window (default: 7 dias) em meta_ads_options.

custom_report opções de configuração

custom_report permite definir seu próprio relatório no estilo ad_insightscom uma combinação personalizada de nível, detalhamento e detalhamento de ação, e ingeri-lo em uma tabela nomeada. Utilize-o quando nenhum relatório pré-construído corresponder às necessidades e for desejável ter controle total sobre a configuração /insights.

Para ingerir um relatório personalizado, defina source_table como custom_report, escolha um nome de destination_table e configure o relatório em connector_options.meta_ads_options.custom_report_options. Você pode adicionar vários objetos custom_report a um pipeline, cada um com um destination_table distinto.

Estrutura do objeto:

JSON

{
  "table": {
    "source_schema": "<meta-ads-account-id>",
    "source_table": "custom_report",
    "destination_catalog": "<catalog>",
    "destination_schema": "<schema>",
    "destination_table": "<your-report-name>",
    "connector_options": {
      "meta_ads_options": {
        "start_date": "<YYYY-MM-DD>",
        "custom_insights_lookback_window": 7,
        "custom_report_options": {
          "level": "ad",
          "breakdowns": ["country"],
          "action_breakdowns": ["action_type"],
          "time_increment": "1",
          "action_report_time": "mixed",
          "action_attribution_windows": ["7d_click", "1d_view"]
        }
      }
    }
  }
}

custom_report_options

Cada opção corresponde à opção ad_insights:

Opção	Descrição
level	Granularidade: account, campaign, adset, ou ad.
breakdowns	Dimensões que segmentam todas as métricas (por exemplo, ["country", "age"]).
action_breakdowns	Dimensões que segmentam métricas de ação/conversão (por exemplo, ["action_type"]).
time_increment	Período de agregação: all_days, monthly ou um número inteiro de dias como uma string (por exemplo, "1" para diário).
action_report_time	Quando as ações são contadas: impression, conversion, mixed ou lifetime.
action_attribution_windows	Janelas de atribuição para ações (por exemplo, ["7d_click", "1d_view"]).

Opção	Descrição
level	Granularidade: account, campaign, adset, ou ad.
breakdowns	Dimensões que segmentam todas as métricas (por exemplo, ["country", "age"]).
action_breakdowns	Dimensões que segmentam métricas de ação/conversão (por exemplo, ["action_type"]).
time_increment	Período de agregação: all_days, monthly ou um número inteiro de dias como uma string (por exemplo, "1" para diário).
action_report_time	Quando as ações são contadas: impression, conversion, mixed ou lifetime.
action_attribution_windows	Janelas de atribuição para ações (por exemplo, ["7d_click", "1d_view"]).

Compartilhado meta_ads_options

Opção	Descrição	Default quando não definido
start_date	Data mais antiga para ingestão, YYYY-MM-DD.	36 meses antes da data atual
custom_insights_lookback_window	Número de dias para reingerir em cada sincronização subsequente (captura conversões tardias).	7 dias

Opção	Descrição	Default quando não definido
start_date	Data mais antiga para ingestão, YYYY-MM-DD.	36 meses antes da data atual
custom_insights_lookback_window	Número de dias para reingerir em cada sincronização subsequente (captura conversões tardias).	7 dias

Você deve definir destination_table no objeto da tabela para que vários relatórios personalizados possam coexistir em um pipeline.

Cada linha é identificada exclusivamente por insight_id. O conector sincroniza dados incrementalmente, usando date_stop como cursor.

Versões da API

O conector Meta Ads utiliza a API de marketing Meta ( API gráfica). A Databricks mantém o conector atualizado com a versão estável mais recente da API.