Referência do conector do Google 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 fornece informações de referência para o conector de gerenciamento do Google Ads no LakeFlow Connect, incluindo tabelas compatíveis, definições de colunas e tipos de dados.

Tabelas suportadas

O conector do Google Ads é compatível com os seguintes tipos de tabelas:

• Tabelas de recursos: Dados de configuração sobre sua account do Google Ads, como campanhas, grupos de anúncios e anúncios. Essas tabelas são totalmente atualizadas a cada execução do pipeline.
• Tabelas de relatórios: métricas de desempenho, como impressões, cliques e conversões. Essas tabelas suportam a ingestão incremental.

tabelas de recursos

Nome da tabela	Descrição
customer	informações sobre a conta do Google Ads.
campaign	Configuração e definições da campanha.
campaign_budget	Configurações de orçamento para campanhas.
campaign_criterion	Critérios de segmentação para campanhas.
ad_group	Configuração do grupo de anúncios.
ad_group_criterion	Critérios de segmentação para grupos de anúncios.
ad	Detalhes e configurações individuais do anúncio.

Nome da tabela	Descrição
customer	informações sobre a conta do Google Ads.
campaign	Configuração e definições da campanha.
campaign_budget	Configurações de orçamento para campanhas.
campaign_criterion	Critérios de segmentação para campanhas.
ad_group	Configuração do grupo de anúncios.
ad_group_criterion	Critérios de segmentação para grupos de anúncios.
ad	Detalhes e configurações individuais do anúncio.

Tabelas de relatório

Nome da tabela	Descrição
customer_report	métricas de desempenho em nível de conta.
campaign_report	Avaliações de desempenho em nível de campanha.
ad_group_report	Avaliações de desempenho em nível de grupo de anúncios.
ad_report	Avaliações de desempenho em nível de anúncio.
keyword_report	Avaliações de desempenho em nível de palavra-chave.
search_query_report	Pesquisar métricas de desempenho em nível de consulta.

Nome da tabela	Descrição
customer_report	métricas de desempenho em nível de conta.
campaign_report	Avaliações de desempenho em nível de campanha.
ad_group_report	Avaliações de desempenho em nível de grupo de anúncios.
ad_report	Avaliações de desempenho em nível de anúncio.
keyword_report	Avaliações de desempenho em nível de palavra-chave.
search_query_report	Pesquisar métricas de desempenho em nível de consulta.

Convenções de tipo de dados

Armazenamento de dinheiro (micros)

O Google Ads armazena valores monetários em microssegundos para evitar problemas de arredondamento. Um milhão de micros equivale a uma unidade monetária:

• 1,000,000 micros = $1.00 USD
• 5,500,000 micros = $5.50 USD

Os campos com sufixo _micros contêm valores armazenados em micros. Divida por 1.000.000 para converter para a sua moeda.

Chave primária

As tabelas usam a notação (Primary Key) para indicar as colunas que formam a key primária. A chave primária composta é indicada por múltiplas colunas marcadas como (Primary Key).

esquemas de tabelas de recursos

customer

informações sobre a conta do Google Ads.

Coluna	Tipo de dados	Descrição
id	long	key primária. ID account do cliente.
auto_tagging_enabled	boolean	Indica se a marcação automática está ativada para a account.
currency_code	string	Código da moeda da account.
descriptive_name	string	Nome amigável para a account do Google Ads.
final_url_suffix	string	Sufixo de URL adicionado aos URLs finais para acompanhamento.
manager	boolean	Se o cliente possui uma conta de Gerente (MCC).
optimization_score	double	Pontuação de otimização para a account.
pay_per_conversion_eligibility_failure_reasons	array<string>	Motivos pelos quais a account não é elegível para lances com pagamento por conversão.
test_account	boolean	Se o cliente é uma account de teste.
time_zone	string	Fuso horário da account.
tracking_url_template	string	URL padrão para construção de URLs de acompanhamento.

Coluna	Tipo de dados	Descrição
id	long	key primária. ID account do cliente.
auto_tagging_enabled	boolean	Indica se a marcação automática está ativada para a account.
currency_code	string	Código da moeda da account.
descriptive_name	string	Nome amigável para a account do Google Ads.
final_url_suffix	string	Sufixo de URL adicionado aos URLs finais para acompanhamento.
manager	boolean	Se o cliente possui uma conta de Gerente (MCC).
optimization_score	double	Pontuação de otimização para a account.
pay_per_conversion_eligibility_failure_reasons	array<string>	Motivos pelos quais a account não é elegível para lances com pagamento por conversão.
test_account	boolean	Se o cliente é uma account de teste.
time_zone	string	Fuso horário da account.
tracking_url_template	string	URL padrão para construção de URLs de acompanhamento.

campaign

Configuração e definições da campanha.

Coluna	Tipo de dados	Descrição
id	long	key primária. ID da campanha.
name	string	Nome da campanha.
status	string	Situação da campanha.
advertising_channel_type	string	Tipo de canal de publicidade.
start_date	string	Data de início da campanha.
end_date	string	Data de término da campanha.
campaign_budget_id	long	Identificação do orçamento de campanha associado.

Coluna	Tipo de dados	Descrição
id	long	key primária. ID da campanha.
name	string	Nome da campanha.
status	string	Situação da campanha.
advertising_channel_type	string	Tipo de canal de publicidade.
start_date	string	Data de início da campanha.
end_date	string	Data de término da campanha.
campaign_budget_id	long	Identificação do orçamento de campanha associado.

campaign_budget

Configurações de orçamento para campanhas.

Coluna	Tipo de dados	Descrição
id	long	key primária. ID do orçamento.
resource_name	string	Nome do recurso do Google Ads.
name	string	Nome do orçamento.
amount_micros	long	Valor do orçamento em microssegundos. Divida por 1.000.000 para converter para moeda corrente.
delivery_method	string	Como o Google gasta o orçamento diário (padrão ou acelerado).
period	string	Período orçamentário.
status	string	Situação orçamentária.
total_amount_micros	long	Montante total do orçamento em microssegundos. Divida por 1.000.000 para converter para moeda corrente.

Coluna	Tipo de dados	Descrição
id	long	key primária. ID do orçamento.
resource_name	string	Nome do recurso do Google Ads.
name	string	Nome do orçamento.
amount_micros	long	Valor do orçamento em microssegundos. Divida por 1.000.000 para converter para moeda corrente.
delivery_method	string	Como o Google gasta o orçamento diário (padrão ou acelerado).
period	string	Período orçamentário.
status	string	Situação orçamentária.
total_amount_micros	long	Montante total do orçamento em microssegundos. Divida por 1.000.000 para converter para moeda corrente.

campaign_criterion

Critérios de segmentação para campanhas.

Coluna	Tipo de dados	Descrição
campaign_id	long	key primária. ID da campanha.
criterion_id	long	key primária. Critério de identificação.
resource_name	string	Nome do recurso do Google Ads.
type	string	Tipo de critério.
status	string	Status do critério.
negative	boolean	Se esse critério exclui um público.
bid_modifier	double	Valor do modificador de lance.

Coluna	Tipo de dados	Descrição
campaign_id	long	key primária. ID da campanha.
criterion_id	long	key primária. Critério de identificação.
resource_name	string	Nome do recurso do Google Ads.
type	string	Tipo de critério.
status	string	Status do critério.
negative	boolean	Se esse critério exclui um público.
bid_modifier	double	Valor do modificador de lance.

ad_group

Configuração do grupo de anúncios.

Coluna	Tipo de dados	Descrição
id	long	key primária. ID do grupo de anúncios.
name	string	Nome do grupo de anúncios.
status	string	Status do grupo de anúncios.
campaign_id	long	ID da campanha associada.
type	string	Tipo de grupo de anúncios.
cpc_bid_micros	long	Lance de custo por clique em microssegundos.
target_cpa_micros	long	Custo alvo por aquisição em microssegundos.

Coluna	Tipo de dados	Descrição
id	long	key primária. ID do grupo de anúncios.
name	string	Nome do grupo de anúncios.
status	string	Status do grupo de anúncios.
campaign_id	long	ID da campanha associada.
type	string	Tipo de grupo de anúncios.
cpc_bid_micros	long	Lance de custo por clique em microssegundos.
target_cpa_micros	long	Custo alvo por aquisição em microssegundos.

ad_group_criterion

Critérios de segmentação para grupos de anúncios.

Coluna	Tipo de dados	Descrição
criterion_id	long	key primária. Critério de identificação.
ad_group_id	long	key primária. ID do grupo de anúncios.
resource_name	string	Nome do recurso do Google Ads.
status	string	Status do critério.
type	string	Tipo de critério.
negative	boolean	Se esse critério exclui um público.
keyword_match_type	string	Tipo de correspondência de palavras-chave (exata, frase, ampla).
keyword_text	string	Texto com palavra-chave.

Coluna	Tipo de dados	Descrição
criterion_id	long	key primária. Critério de identificação.
ad_group_id	long	key primária. ID do grupo de anúncios.
resource_name	string	Nome do recurso do Google Ads.
status	string	Status do critério.
type	string	Tipo de critério.
negative	boolean	Se esse critério exclui um público.
keyword_match_type	string	Tipo de correspondência de palavras-chave (exata, frase, ampla).
keyword_text	string	Texto com palavra-chave.

ad

Detalhes e configurações individuais do anúncio. Esta tabela corresponde a ad_group_ad na API do Google Ads.

Coluna	Tipo de dados	Descrição
id	long	key primária. ID do anúncio.
ad_group_id	long	key primária. ID do grupo de anúncios.
status	string	Status do anúncio.
ad_type	string	Tipo de anúncio.
final_urls	array<string>	URLs de páginas de aterrissagem após clicar no anúncio.
policy_summary_approval_status	string	Se o anúncio foi aprovado de acordo com a política do Google Ads (APROVADO ou REPROVADO).
policy_summary_review_status	string	Indica se o Google concluiu a análise do anúncio (REVIEW_IN_PROGRESS ou REVIEWED).

Coluna	Tipo de dados	Descrição
id	long	key primária. ID do anúncio.
ad_group_id	long	key primária. ID do grupo de anúncios.
status	string	Status do anúncio.
ad_type	string	Tipo de anúncio.
final_urls	array<string>	URLs de páginas de aterrissagem após clicar no anúncio.
policy_summary_approval_status	string	Se o anúncio foi aprovado de acordo com a política do Google Ads (APROVADO ou REPROVADO).
policy_summary_review_status	string	Indica se o Google concluiu a análise do anúncio (REVIEW_IN_PROGRESS ou REVIEWED).

Esquemas de tabelas de relatório

customer_report

métricas de desempenho em nível de conta.

Coluna	Tipo de dados	Descrição
customer_id	long	key primária. ID account do cliente.
date	string	key primária. Data no formato AAAA-MM-DD.
device	string	key primária. Tipo de dispositivo.
ad_network_type	string	key primária. Tipo de rede de anúncios.
impressions	long	Número de impressões.
clicks	long	Número de cliques.
cost_micros	long	Custo em micros. Divida por 1.000.000 para converter para moeda corrente.
conversions	double	Número de conversões.
conversions_value	double	Valor total da conversão.
ctr	double	Taxa de cliques.
average_cpc	double	Custo médio por clique.

Coluna	Tipo de dados	Descrição
customer_id	long	key primária. ID account do cliente.
date	string	key primária. Data no formato AAAA-MM-DD.
device	string	key primária. Tipo de dispositivo.
ad_network_type	string	key primária. Tipo de rede de anúncios.
impressions	long	Número de impressões.
clicks	long	Número de cliques.
cost_micros	long	Custo em micros. Divida por 1.000.000 para converter para moeda corrente.
conversions	double	Número de conversões.
conversions_value	double	Valor total da conversão.
ctr	double	Taxa de cliques.
average_cpc	double	Custo médio por clique.

campaign_report

Avaliações de desempenho em nível de campanha.

Coluna	Tipo de dados	Descrição
customer_id	long	key primária. ID account do cliente.
id	long	key primária. ID da campanha.
date	string	key primária. Data no formato AAAA-MM-DD.
device	string	key primária. Tipo de dispositivo.
ad_network_type	string	key primária. Tipo de rede de anúncios.
campaign_name	string	Nome da campanha.
campaign_status	string	Situação da campanha.
impressions	long	Número de impressões.
clicks	long	Número de cliques.
cost_micros	long	Custo em micros.
conversions	double	Número de conversões.

Coluna	Tipo de dados	Descrição
customer_id	long	key primária. ID account do cliente.
id	long	key primária. ID da campanha.
date	string	key primária. Data no formato AAAA-MM-DD.
device	string	key primária. Tipo de dispositivo.
ad_network_type	string	key primária. Tipo de rede de anúncios.
campaign_name	string	Nome da campanha.
campaign_status	string	Situação da campanha.
impressions	long	Número de impressões.
clicks	long	Número de cliques.
cost_micros	long	Custo em micros.
conversions	double	Número de conversões.

ad_group_report

Avaliações de desempenho em nível de grupo de anúncios.

Coluna	Tipo de dados	Descrição
customer_id	long	key primária. ID account do cliente.
id	long	key primária. ID do grupo de anúncios.
date	string	key primária. Data no formato AAAA-MM-DD.
device	string	key primária. Tipo de dispositivo.
ad_network_type	string	key primária. Tipo de rede de anúncios.
ad_group_name	string	Nome do grupo de anúncios.
ad_group_status	string	Status do grupo de anúncios.
campaign_id	long	ID da campanha associada.
impressions	long	Número de impressões.
clicks	long	Número de cliques.
cost_micros	long	Custo em micros.

Coluna	Tipo de dados	Descrição
customer_id	long	key primária. ID account do cliente.
id	long	key primária. ID do grupo de anúncios.
date	string	key primária. Data no formato AAAA-MM-DD.
device	string	key primária. Tipo de dispositivo.
ad_network_type	string	key primária. Tipo de rede de anúncios.
ad_group_name	string	Nome do grupo de anúncios.
ad_group_status	string	Status do grupo de anúncios.
campaign_id	long	ID da campanha associada.
impressions	long	Número de impressões.
clicks	long	Número de cliques.
cost_micros	long	Custo em micros.

keyword_report

Avaliações de desempenho em nível de palavra-chave.

Coluna	Tipo de dados	Descrição
customer_id	long	key primária. ID account do cliente.
date	string	key primária. Data no formato AAAA-MM-DD.
ad_group_criterion_criterion_id	long	key primária. Critério de identificação.
ad_group_id	long	key primária. ID do grupo de anúncios.
device	string	key primária. Tipo de dispositivo.
ad_network_type	string	key primária. Tipo de rede de anúncios.
keyword_text	string	Texto com palavra-chave.
keyword_match_type	string	Tipo de correspondência de palavras-chave.
impressions	long	Número de impressões.
clicks	long	Número de cliques.
cost_micros	long	Custo em micros.

Coluna	Tipo de dados	Descrição
customer_id	long	key primária. ID account do cliente.
date	string	key primária. Data no formato AAAA-MM-DD.
ad_group_criterion_criterion_id	long	key primária. Critério de identificação.
ad_group_id	long	key primária. ID do grupo de anúncios.
device	string	key primária. Tipo de dispositivo.
ad_network_type	string	key primária. Tipo de rede de anúncios.
keyword_text	string	Texto com palavra-chave.
keyword_match_type	string	Tipo de correspondência de palavras-chave.
impressions	long	Número de impressões.
clicks	long	Número de cliques.
cost_micros	long	Custo em micros.

ad_report

Avaliações de desempenho em nível de anúncio.

Coluna	Tipo de dados	Descrição
customer_id	long	key primária. ID account do cliente.
date	string	key primária. Data no formato AAAA-MM-DD.
ad_id	long	key primária. ID do anúncio.
ad_group_id	long	key primária. ID do grupo de anúncios.
device	string	key primária. Tipo de dispositivo.
ad_network_type	string	key primária. Tipo de rede de anúncios.
campaign_id	long	ID da campanha associada.
impressions	long	Número de impressões.
clicks	long	Número de cliques.
cost_micros	long	Custo em micros.
conversions	double	Número de conversões.

Coluna	Tipo de dados	Descrição
customer_id	long	key primária. ID account do cliente.
date	string	key primária. Data no formato AAAA-MM-DD.
ad_id	long	key primária. ID do anúncio.
ad_group_id	long	key primária. ID do grupo de anúncios.
device	string	key primária. Tipo de dispositivo.
ad_network_type	string	key primária. Tipo de rede de anúncios.
campaign_id	long	ID da campanha associada.
impressions	long	Número de impressões.
clicks	long	Número de cliques.
cost_micros	long	Custo em micros.
conversions	double	Número de conversões.

search_query_report

Pesquisar métricas de desempenho em nível de consulta.

Coluna	Tipo de dados	Descrição
customer_id	long	key primária. ID account do cliente.
date	string	key primária. Data no formato AAAA-MM-DD.
resource_name	string	key primária. Nome do recurso do Google Ads.
search_term	string	Termo de pesquisa do usuário.
search_term_match_type	string	Como a palavra-chave correspondeu ao termo de pesquisa.
ad_group_id	long	ID do grupo de anúncios associado.
campaign_id	long	ID da campanha associada.
impressions	long	Número de impressões.
clicks	long	Número de cliques.

Coluna	Tipo de dados	Descrição
customer_id	long	key primária. ID account do cliente.
date	string	key primária. Data no formato AAAA-MM-DD.
resource_name	string	key primária. Nome do recurso do Google Ads.
search_term	string	Termo de pesquisa do usuário.
search_term_match_type	string	Como a palavra-chave correspondeu ao termo de pesquisa.
ad_group_id	long	ID do grupo de anúncios associado.
campaign_id	long	ID da campanha associada.
impressions	long	Número de impressões.
clicks	long	Número de cliques.

Ingestão incremental

As tabelas de relatório suportam ingestão incremental com uma janela de retrospectiva configurável. O conector usa a coluna date como coluna do cursor para acompanhar atualizações incrementais.

Para obter mais informações sobre ingestão incremental e janelas de retrospectiva, consulte Conceitos do conector do Google Ads.

Opções de configuração de relatório personalizado

Relatórios personalizados permitem selecionar qualquer recurso do Google Ads com uma combinação de campos de recurso, segmentos e métricas. O nome destination_table é obrigatório.

Defina source_table como custom_report e forneça custom_report_options em connector_options.google_ads_options:

Opção	Obrigatório	Descrição
resource	Sim	O recurso do Google Ads para query (por exemplo, ad_group_ad, keyword_view, search_term_view). O recurso deve suportar métricas.
resource_fields	Não	Campos de recurso para selecionar, no formato GAQL totalmente qualificado (por exemplo, ad_group_ad.ad.id, ad_group_ad.status). O nome do recurso é adicionado por default.
segments	Não	Campos de segmento para selecionar (por exemplo, segments.date, segments.device). É necessário incluir pelo menos um segmento de linha do tempo — segments.date, segments.week ou segments.month — que se torna o cursor incremental da tabela.
metrics	Não	Campos de métricas para selecionar (por exemplo, metrics.clicks, metrics.cost_micros).

Opção	Obrigatório	Descrição
resource	Sim	O recurso do Google Ads para query (por exemplo, ad_group_ad, keyword_view, search_term_view). O recurso deve suportar métricas.
resource_fields	Não	Campos de recurso para selecionar, no formato GAQL totalmente qualificado (por exemplo, ad_group_ad.ad.id, ad_group_ad.status). O nome do recurso é adicionado por default.
segments	Não	Campos de segmento para selecionar (por exemplo, segments.date, segments.device). É necessário incluir pelo menos um segmento de linha do tempo — segments.date, segments.week ou segments.month — que se torna o cursor incremental da tabela.
metrics	Não	Campos de métricas para selecionar (por exemplo, metrics.clicks, metrics.cost_micros).

Observações:

• As colunas de destino omitem os prefixos padrão metrics. e segments.; para campos de recurso, os pontos são convertidos em underscores (por exemplo, ad_group_ad.ad.id se torna ad_group_ad_ad_id).
• O atributo resource_name é sempre incluído para identificar cada linha.
• A ingestão de relatórios personalizados é incremental, com base na janela de retrospectiva.
• Google Ads retém dados segmentados diária e semanalmente por apenas 37 meses. Relatórios personalizados que usam segments.date ou segments.week não podem sincronizar dados mais antigos que esta janela; use segments.month para dados mais antigos.
• O planejamento de pipeline valida nomes de campo em relação ao Google Ads. A falta de segmentos de linha do tempo ou campos inválidos causa falhas de atualização. Use a configuração validate_only para testar configurações sem mover dados.