Google Ads

Contas, campanhas, grupos, anúncios, palavras-chave e métricas diárias do Google Ads, no Data Catalog e no Memory.

O conector Google Ads lê, pela API do Google Ads, as contas de anúncio que uma credencial OAuth alcança. Ele traz o cadastro das contas, campanhas, orçamentos, grupos, anúncios e palavras-chave, e as métricas diárias de desempenho por dispositivo, por país e por palavra-chave.

Status	Disponível
Conteúdo	Registros
Autenticação	OAuth 2.0 com refresh token
Permissões	Sem permissão por item
Sincronização	Incremental e full refresh, por recurso
Última revisão	07/10/2026

Capacidades

• Lê todas as contas-cliente ativas de uma conta gerente (MCC), ou as contas que o usuário autorizado alcança direto, quando não há MCC.
• Traz ao Data Catalog o cadastro de cada conta: orçamentos, campanhas, grupos de anúncios, anúncios responsivos de pesquisa e palavras-chave.
• Traz, por dia, impressões, cliques, custo, conversões, valor das conversões e todas as conversões, em três cortes: campanha e dispositivo, campanha e país, palavra-chave.
• Instala 12 tabelas clean prontas, com dinheiro em decimal exato na moeda da conta, início e fim de campanha em UTC, o total diário da campanha e os títulos, descrições e URLs dos anúncios em linhas.
• Alimenta o Memory com os nós AdAccount, AdCampaign, AdBudget, AdGroup, Ad e AdKeyword, ligados na hierarquia da conta, e com o início de cada campanha como evento de linha do tempo. Não há fusão com nós de outros conectores. Os nós só entram no grafo depois que a ontologia unificada é aplicada.

Recursos disponíveis

Todo recurso nasce desligado no Data Catalog. Você escolhe quais carregar depois de conectar.

Recurso	O que contém	Carga	Cursor	Destino	Permissão por item
customers	As contas de anúncio lidas, com nome, currency_code, time_zone e status	Full refresh	Nenhum	Catálogo e Memory	Não
campaign_budgets	Orçamentos, com valor, período, forma de entrega e se é compartilhado	Full refresh	Nenhum	Catálogo e Memory	Não
campaigns	Campanhas, com status, tipo de canal, estratégia de lance, orçamento, início e fim	Full refresh	Nenhum	Catálogo e Memory	Não
ad_groups	Grupos de anúncios, com a campanha, o status, o tipo e os lances	Full refresh	Nenhum	Catálogo e Memory	Não
ads	Anúncios, com tipo, status, URLs finais e os títulos e descrições do anúncio responsivo de pesquisa	Full refresh	Nenhum	Catálogo e Memory	Não
keywords	Palavras-chave, com texto, tipo de correspondência, status, se é negativa e lance	Full refresh	Nenhum	Catálogo e Memory	Não
campaign_metrics_by_device	Uma linha por campanha, dia e dispositivo, com as seis métricas	Incremental ou full refresh	date	Catálogo	Não
campaign_metrics_by_country	Uma linha por campanha, dia e país, com as seis métricas	Incremental ou full refresh	date	Catálogo	Não
keyword_metrics	Uma linha por palavra-chave e dia, com as seis métricas	Incremental ou full refresh	date	Catálogo	Não

As seis métricas são impressions, clicks, cost_micros, conversions, conversions_value e all_conversions.

As 12 tabelas clean do Google Ads são instaladas quando você cria o conector, fora do contexto. Ligue no Data Catalog as que você quer usar. Cada uma passa a ser atualizada depois de cada sincronização. São elas: google_ads_customers, google_ads_campaigns, google_ads_campaign_budgets, google_ads_ad_groups, google_ads_ads, google_ads_ad_text_assets, google_ads_ad_final_urls, google_ads_keywords, google_ads_campaign_daily, google_ads_campaign_daily_by_device, google_ads_campaign_daily_by_country e google_ads_keyword_daily.

Como ler as métricas

• date é o dia do calendário no fuso de cada conta (time_zone), o mesmo corte da interface do Google Ads. A data não é convertida para UTC.
• Toda linha traz customer_id, currency_code e time_zone. Os valores monetários ficam na moeda da conta, sem conversão entre moedas.
• Na raw, o dinheiro vem em micros (cost_micros, amount_micros): 1.234.567 micros são 1,234567 na moeda. Na clean, o valor sai em DECIMAL(18,6) na unidade da moeda (cost, budget_amount, cpc_bid).
• google_ads_campaign_daily é a soma dos dispositivos de google_ads_campaign_daily_by_device, para cada campanha e dia.
• O país usa a presença física de quem viu o anúncio, com o código ISO de duas letras em country_code. Só entram países com impressão ou custo no dia.
• Os ids de campanha, grupo e anúncio só são únicos dentro da conta, e o id de palavra-chave só dentro do grupo. Use as colunas de chave da clean (campaign_key, ad_group_key, ad_key, keyword_key), que já incluem a conta.

Permissões (ACL)

Esta fonte não define permissões por registro, então todo mundo que puder usar o conector vê todos os registros.

Quem pode usar o conector é definido em Quem pode usar este conector: “Todos os usuários” ou “Apenas times específicos”. O Comportamento dos dados deste conector é sempre “Aberto”.

Como a fonte define acesso

No Google Ads, o acesso é por conta de anúncio. Cada conta tem a lista dos usuários com o papel de cada um, e quem acessa uma conta gerente alcança as contas-cliente dela.

Como a Strattum traduz o acesso

A Strattum não grava permissão por item. Todas as contas que a credencial alcança, e todas as linhas delas, ficam visíveis para quem pode usar o conector. O conector não oferece Exigir login na fonte como prova de identidade.

Quando a identidade não é encontrada

Não se aplica: nenhuma linha depende da identidade de quem consulta.

Quando a permissão é atualizada

Não há permissão da fonte para atualizar. O acesso depende só de Quem pode usar este conector. Para tirar uma conta da Strattum, retire o acesso da credencial a ela no Google Ads.

Pré-requisitos

• Um usuário Google com acesso à conta gerente (MCC) ou às contas de anúncio que você quer ler.
• Um projeto no Google Cloud com a Google Ads API ativada e um cliente OAuth (Client ID e Client Secret).
• Um nível de acesso do projeto que alcance as suas contas. O nível Test só alcança contas de teste. O Explorer permite 2.880 operações por dia e o Basic, 15.000.
• Uma só conexão Google Ads por instalação da Strattum. Ela lê todas as contas que a credencial alcança.

Autenticação e escopos

A autenticação é OAuth 2.0 de um único usuário, com refresh token. A cada sincronização, o conector troca o refresh token por um token de acesso de uma hora. Não é preciso developer token: a Google descontinuou o developer token em 09/09/2026, e a chamada funciona sem ele.

Escopo ou permissão	Para quê
https://www.googleapis.com/auth/adwords	Ler a hierarquia de contas, o cadastro e as métricas de todas as contas alcançadas.
Acesso do usuário autorizado às contas	Definir quais contas o conector lê.

1. Prepare o projeto no Google Cloud

   Ative a Google Ads API no projeto e crie um cliente OAuth em APIs & Services → Credentials. Copie o Client ID e o Client Secret.

2. Publique o app OAuth

   Na tela de consentimento OAuth, deixe o app em In production. Em Testing, o refresh token expira em 7 dias.

3. Gere o refresh token

   Faça o consentimento OAuth uma vez com o usuário que tem acesso às contas, pedindo o escopo adwords, acesso offline e consentimento explícito. Guarde o refresh token devolvido.

4. Anote o ID da conta gerente

   Se as contas ficam sob uma MCC, anote o ID dela, no formato 123-456-7890.

Configuração no Console

1. Abra o assistente

   Em Conectores, clique em + Nova Conexão e selecione Google Ads, em Mídia paga.

2. Preencha a conexão

   Nome do Conector (Opcional): como a conexão aparece na lista. O padrão é Google Ads.

   Client ID (Obrigatório): o Client ID do cliente OAuth do projeto Google Cloud.

   Client Secret (Obrigatório): o Client Secret do mesmo cliente OAuth.

   Refresh Token (Obrigatório): o token gerado no consentimento, com acesso offline e escopo adwords.

   ID da conta gerente (MCC) (Opcional): o ID da MCC, com ou sem hífen. Com ele, o conector lê todas as contas-cliente ativas da MCC. Sem ele, lê as contas que o usuário autorizado acessa direto.

3. Teste a conexão

   Clique em Testar Conexão. Você só avança depois de um teste com sucesso. O teste avisa, sem bloquear, quando a conta é uma conta de teste (que não veicula anúncios) e quando a credencial só alcança uma conta gerente sem o ID dela preenchido.

4. Escolha a frequência

   Em Sincronização (Obrigatório), escolha a frequência. O padrão do Google Ads é uma vez por dia, às 06:00 UTC.

5. Defina o acesso

   Em Permissionamento, defina Quem pode usar este conector. O Comportamento dos dados é sempre “Aberto”.

6. Revise e salve

   Em Revisão, confira os dados e salve. O Client Secret e o Refresh Token não aparecem na revisão.

7. Ligue os recursos no Data Catalog

   No Data Catalog, ligue os recursos e as tabelas clean que você quer carregar. Nos três recursos de métrica, escolha o modo Incremental na aba Carga: em full refresh, cada execução relê 37 meses de métrica e gasta muito mais da cota diária.

Como a sincronização funciona

A frequência vem do passo Sincronização. O padrão é uma execução por dia, às 06:00 UTC, porque o conector só lê dias fechados.

Contas. Cada execução começa descobrindo as contas. Com o ID da MCC, o conector percorre a árvore de contas gerentes a partir dela e fica com as contas-cliente ativas que não são gerentes. Sem o ID, lê as contas de listAccessibleCustomers. Conta que a API recusa como desativada é pulada. Qualquer outro erro falha a execução, para não gravar uma leitura incompleta.

Ordem. Depois, o conector lê os recursos selecionados um por um, conta por conta, com uma chamada por vez. Recurso desligado no Data Catalog não é lido.

Cadastro em full refresh. customers, campaign_budgets, campaigns, ad_groups, ads e keywords são reescritos por inteiro a cada execução. Um item apagado no Google Ads some da tabela na execução seguinte.

Métricas. O último dia lido é sempre ontem, no fuso de cada conta. O dia de hoje nunca entra. As consultas saem em blocos de 30 dias, do mais recente para o mais antigo.

• Primeira carga e full refresh: desde o primeiro dia do mês, 36 meses antes do mês de ontem, dentro do limite de 37 meses da API.
• Incremental: relê os últimos 30 dias fechados e substitui as linhas pela chave de cada linha. A releitura existe porque o Google revisa os números depois do dia, com estornos de clique inválido e conversões atribuídas ao dia do clique.
• Conta nova: uma conta que entra na MCC depois da primeira carga recebe os 37 meses, mesmo em incremental. Uma conta que sai e volta também.

Remoção. No cadastro, o full refresh reflete a remoção. Nas métricas em incremental, os dias já gravados de uma conta que deixou de ser lida continuam na tabela. Um full refresh os remove.

API da fonte

Método e caminho	Usado para	Recurso
POST https://oauth2.googleapis.com/token	Trocar o refresh token por um token de acesso	Todos
GET /v25/customers:listAccessibleCustomers	Listar as contas que o usuário acessa, quando não há MCC	Todos
POST /v25/customers/{customer_id}/googleAds:searchStream	Consultas GAQL em customer_client e customer: hierarquia e dados de cada conta	customers e a descoberta de contas
POST /v25/customers/{customer_id}/googleAds:searchStream	Consultas GAQL em campaign_budget, campaign, ad_group, ad_group_ad e ad_group_criterion	campaign_budgets, campaigns, ad_groups, ads, keywords
POST /v25/customers/{customer_id}/googleAds:searchStream	Métricas diárias em campaign, geographic_view e keyword_view	campaign_metrics_by_device, campaign_metrics_by_country, keyword_metrics
POST /v25/customers/{customer_id}/googleAds:searchStream	Código ISO do país em geo_target_constant	campaign_metrics_by_country

As consultas searchStream só leem dados. O host da API é https://googleads.googleapis.com.

Rate limits. O Google Ads conta uma operação por consulta Search ou SearchStream, na cota diária do projeto Google Cloud: 2.880 operações por dia no nível Explorer e 15.000 no Basic. Há também um limite por segundo, por conta e por projeto, sem número publicado. Uma conta custa cerca de 9 operações por execução incremental e cerca de 117 na primeira carga.

O conector envia uma consulta por vez, com tempo limite de 300 segundos. Diante do limite por segundo (RESOURCE_TEMPORARILY_EXHAUSTED), espera o Retry-After quando ele vem, senão um recuo crescente de no máximo 60 segundos, e tenta de novo até 5 vezes. Diante da cota diária esgotada (RESOURCE_EXHAUSTED), a execução falha na hora, sem novas tentativas. Erros 5xx e falhas de rede têm até 4 novas tentativas. Se um recurso ainda falhar, a execução tenta o recurso de novo até 3 vezes, depois de 30, 60 e 120 segundos, menos quando a causa é a cota diária ou uma credencial revogada.

Referência oficial: Google Ads API, cotas

Limitações conhecidas

• Sem permissão por item: todo usuário que pode usar o conector vê todas as contas que a credencial alcança. Para restringir, limite Quem pode usar este conector.
• Uma conexão Google Ads por instalação. O conector lê todas as contas que a credencial alcança, e não há como escolher contas na Strattum. Para tirar uma conta, retire o acesso da credencial a ela no Google Ads.
• O dia de hoje nunca é lido. Em incremental, o dia mais recente já carregado só volta a ser revisado a partir da segunda execução seguinte.
• Uma correção na fonte só é capturada enquanto o dia estiver nos últimos 30 dias fechados. Para corrigir dias mais antigos, rode um full refresh.
• O histórico vai até 37 meses, o limite da API para métricas diárias.
• Conta de teste do Google não veicula anúncios, então as métricas dela vêm vazias. Recurso de métrica que ainda não teve nenhuma linha relê os 37 meses a cada execução incremental, até a primeira linha aparecer.
• Os títulos e descrições vêm só de anúncios responsivos de pesquisa. Outros tipos de anúncio entram sem texto.
• Não há conversão de moeda.
• Ficam de fora termos de pesquisa, cliques individuais, leads, públicos, o histórico de alterações e a lista de usuários de cada conta.
• O refresh token deixa de funcionar depois de 6 meses sem uso, se o usuário que autorizou perder o acesso, ou em 7 dias, se o app OAuth estiver em modo Testing.
• O conector usa a versão v25 da API, que a Google projeta encerrar em agosto de 2027.

Troubleshooting

Mensagem ou sintoma	Causa	O que fazer
Client ID, client secret e refresh token são obrigatórios.	Um dos três campos está vazio.	Preencha os três com os dados do cliente OAuth e o refresh token gerado para o escopo adwords.
O ID da conta gerente (MCC) deve ter 10 dígitos.	O ID da MCC está incompleto.	Informe os 10 dígitos, com ou sem hífens, ou deixe o campo vazio.
O refresh token foi recusado: está inválido, revogado ou expirado.	O token expirou (app em Testing, 6 meses sem uso) ou o acesso foi revogado.	Publique o app OAuth como In production e gere um novo refresh token.
Client ID ou client secret incorretos.	Os dois valores não são do mesmo cliente OAuth que gerou o refresh token.	Copie os dois do cliente OAuth no projeto Google Cloud.
O projeto Google Cloud está no nível de acesso Test, que não alcança contas de produção.	O nível de acesso do projeto é Test.	Peça o nível Explorer ou acima para o projeto.
A credencial não tem acesso a esta conta do Google Ads.	O usuário autorizado não acessa a conta, ou o ID da MCC está errado.	Confira o acesso do usuário e o ID da MCC.
A conta Google autorizada não tem acesso a nenhuma conta do Google Ads.	O usuário do consentimento não tem conta do Google Ads.	Gere o refresh token com um usuário que acesse as contas.
A conta do Google Ads não está habilitada.	A conta está cancelada ou suspensa.	Reative a conta ou informe o ID de uma MCC ativa.
O limite de requisições da API do Google Ads foi atingido.	O limite por segundo ou a cota diária do projeto foi atingida.	Aguarde. A cota diária se renova numa janela de 24 horas. Use o modo incremental nas métricas.
Aviso: a conta alcançada é uma conta gerente (MCC).	A credencial só alcança a MCC e o ID dela não foi preenchido.	Preencha o ID da conta gerente (MCC).
Aviso: conta de teste.	A conta é de teste e não veicula anúncios.	Use uma conta de produção para ver métricas.
Já existe um conector do tipo google_ads.	A instalação já tem uma conexão Google Ads.	Edite a conexão existente ou remova-a antes de criar outra.
As tabelas google_ads_* não aparecem na clean.	As tabelas clean estão fora do contexto.	Ligue-as no Data Catalog e rode a sincronização.

Próximos passos

Data Catalog

Ligue os recursos e as tabelas clean do Google Ads e escolha o modo de carga das métricas.

Memory

Veja como contas, campanhas, orçamentos, grupos, anúncios e palavras-chave entram no grafo.

Desenvolvimento local

O conector não lê variáveis do .env. As credenciais são informadas no Console e ficam no cofre de segredos da plataforma, sob os nomes GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN e GOOGLE_ADS_LOGIN_CUSTOMER_ID. Para testar localmente, crie a conexão pelo Console da stack local.