Conceitos do conector do Reddit Ads
Beta
Esse recurso está em Beta. Administradores do Workspace podem controlar o acesso a este recurso na página **Pré-visualizações**. Consulte Gerenciar prévias do Databricks.
O conector Reddit Ads permite ingerir dados de publicidade do Reddit Ads usando o Databricks Lakeflow Connect.
Como funciona a ingestão do Reddit Ads?
O conector recupera dados da API do Reddit Ads e os grava em tabelas de transmissão. Cada objeto do Reddit Ads corresponde a uma tabela em seu esquema de destino. O conector oferece suporte a dois tipos de tabelas:
- **Tabelas de entidade**: dados de configuração sobre sua conta do Reddit Ads, como campanhas, grupos de anúncios e anúncios. As tabelas de entidade são totalmente atualizadas a cada execução de pipeline e não oferecem suporte ao acompanhamento da história (SCD tipo 2).
- Tabelas de relatórios : métricas de desempenho, tais como impressões, cliques e gastos. As tabelas de relatórios suportam a ingestão incremental com uma janela de retrospectiva configurável para capturar dados de chegada tardia e atualizações de atribuição.
Modelo de Dados do Conector
O conector do Reddit Ads pode ingerir os seguintes objetos da sua account do Reddit Ads:
ad_account: As contas de anúncios acessíveis ao usuário autenticadocampaign,ad_group,ad: Objetos de entidade que descrevem sua estrutura de account- Tabelas de Relatórios (por exemplo,
campaign_report,ad_group_report,ad_report): métricas de desempenho pré-construídas em cada nível da hierarquia da account. custom_report: Um relatório definido pelo usuário com análise configurável e combinação de campos.
Para a lista completa de tabelas compatíveis e seus esquemas, consulte referência do conector do Reddit Ads.
Esquemas de Origem
O Reddit Ads organiza tabelas em esquemas de origem (namespaces) que correspondem à hierarquia de account:
- A tabela de entidade
ad_accountestá localizada no esquema especialdefault. Ele lista todas as contas de anúncios acessíveis ao usuário autenticado. - Todas as outras tabelas —
campaign,ad_group,ade todas as tabelas de relatório — ficam em um esquema nomeado pelo ID do account de anúncios (por exemplo,t2_abc123). Este nome de esquema é o valor que você define comosource_schemana sua especificação do pipeline.
Um pipeline pode ingerir de múltiplos esquemas de account de anúncios, e cada entrada source_schema mapeia para uma account de anúncios.
Tabelas de relatórios
As tabelas de relatórios fornecem métricas de desempenho para suas campanhas de publicidade. O conector fornece dados de relatório de aproximadamente os últimos 24 meses. Independentemente do parâmetro sync_start_date, as tabelas de relatórios não podem recuperar dados mais antigos do que esta janela — as solicitações de dados mais antigos são rejeitadas pelo Reddit. Este limite se aplica apenas às tabelas de relatório, não às tabelas de entidades.
Relatórios personalizados
O objeto custom_report permite definir seu próprio relatório com uma combinação de detalhamento e campo configurável. Controla-se a configuração usando custom_report_options, e cada relatório personalizado é ingerido em um destination_table separado. A lista breakdowns deve incluir pelo menos uma dimensão de tempo (DATE ou HOUR), que se torna o cursor incremental da tabela.
Para detalhamentos e campos suportados, consulte Detalhamentos e campos de relatório personalizados.
Noções básicas do conector
- Na execução inicial do pipeline, o conector ingere data histórica dos objetos selecionados.
- Em execuções subsequentes do pipeline, o conector ingere registros recém-criados ou modificados em tabelas de relatório usando ingestão incremental e faz refresh completo das tabelas de entidades.
- O conector transforma automaticamente os tipos de dados do Reddit Ads em tipos de dados compatíveis com Delta.
- Cada tabela de destino é uma tabela de transmissão, que é uma tabela Delta com suporte extra para processamento incremental de dados.
Ingestão incremental
Por default, o conector ingere dois anos de data histórica para tabelas de relatório na primeira execução. É possível configurar isso usando o parâmetro sync_start_date, que aceita uma data no formato YYYY-MM-DD. O parâmetro se aplica apenas à primeira execução. Após o primeiro checkpoint, alterá-lo não tem efeito sem um refresh completo.
Em execuções subsequentes, o conector utiliza ingestão incremental para tabelas de relatórios. Como as métricas do Reddit Ads podem mudar depois de serem comunicadas inicialmente — por exemplo, quando conversões ou atribuição são recalculadas — o conector reconsulta os dados dos dias mais recentes em cada sincronização. As tabelas de entidade são totalmente atualizadas em cada execução.
Atribuição e janelas de lookback
Para capturar conversões de chegada tardia e atualizações de atribuição, o conector re-lê um número configurável de dias recentes em cada sincronização. Por default, ele relê os últimos 30 dias. Você pode mudar isso com o parâmetro lookback_window_days (qualquer valor de 1 a 30).
Defina lookback_window_days para corresponder à janela de atribuição de conversão de sua organização. Por exemplo, se sua organização usa uma janela de atribuição de 14 dias, defina lookback_window_days: 14.
Fuso horário
Os limites de data do relatório são interpretados no fuso horário próprio do account de anúncios. O conector lê isso automaticamente do account. Você não define um fuso horário na especificação do pipeline.
Moeda
Colunas monetárias — por exemplo, spend, cpc, bid_value — são armazenadas na moeda da conta de anúncio como valores decimais (por exemplo, 12.34), não em micros. O código da moeda da conta está disponível na coluna ad_account.currency e na coluna currency do relatório.
Autenticação
O conector usa autenticação OAuth 2.0 user-to-machine (U2M) com PKCE para autenticar com o Reddit Ads. Crie uma aplicação de desenvolvedor no Reddit Ads Business Manager e configure as definições de OAuth para permitir que o Databricks acesse seus dados de publicidade. O escopo adsread é definido automaticamente pelo Databricks. As credenciais de conexão são armazenadas de forma segura no Unity Catalog.