Pular para o conteúdo
Atualizado em 2026-10-05

Google Ads — conector

Lê relatórios de desempenho do Google Ads (por campanha, grupo de anúncios ou palavra-chave) e carrega na camada Bronze.

Nesta página (16)

Leia antes: ../conectores.md (mapa de estados) e fichas.md (índice das fichas).


O que é#

Lê relatórios de desempenho do Google Ads (por campanha, grupo de anúncios ou palavra-chave) e carrega na camada Bronze.

Modos de ingestão suportados:

  • Nós buscamos — Nós buscamos os dados na sua fonte.

Para que serve#

Trazer os dados de Google Ads para o seu datalake e disponibilizá-los às camadas Bronze/Silver/Gold, aos modelos de BI e ao wizard de perguntas em linguagem natural.

Quando usar / quando não usar#

Use quando você precisa consolidar esta fonte no datalake de forma agendada, com isolamento por workspace.

Use com as credenciais da sua empresa: o conector chama a API do Google Ads com o token de desenvolvedor da sua conta administradora (MCC), um cliente OAuth do seu projeto e um refresh token de um usuário com acesso à conta. Tudo é seu; nada depende de um app nosso.

Plano e permissões#

  • Plano: núcleo do produto (conectores fazem parte de todos os planos; o limite é o número de fontes do plano).
  • Acesso: exige workspace ativo — com a assinatura em atraso, suspensa ou cancelada, a execução fica bloqueada.
  • Desligamento: a execução de ingestão pode ser desligada temporariamente (manutenção ou incidente). Quando isso acontece, a tela informa que o recurso está indisponível no momento.

Pré-requisitos#

  • Uma conta administradora (MCC) do Google Ads — é nela que se obtém o token de desenvolvedor.
  • Um usuário Google com acesso (leitura basta) à conta de anúncios que você quer ler.
  • Um projeto no console de nuvem do Google com a Google Ads API ativada, para criar o cliente OAuth.

Como obter cada credencial#

  1. Token de desenvolvedor (developerToken) — na conta administradora (MCC), abra Ferramentas → Configuração → Central de API (API Center), aceite os termos e copie o token. Um token em nível Acesso de teste só lê contas de teste: peça o Acesso básico na mesma tela para ler contas reais.
  2. Cliente OAuth (clientId e clientSecret) — no console de nuvem do Google, no seu projeto: ative a Google Ads API, configure a tela de consentimento OAuth e crie uma credencial ID do cliente OAuth do tipo App para computador (Desktop). Copie o ID do cliente e a chave secreta do cliente.
  3. Refresh token (refreshToken) — autorize esse cliente OAuth com o usuário que acessa a conta de anúncios, pedindo o escopo https://www.googleapis.com/auth/adwords, e guarde o refresh token devolvido (ex.: com o OAuth Playground do Google, marcando Use your own OAuth credentials com o seu ID e chave). Se a tela de consentimento estiver em modo Teste, o refresh token expira em 7 dias — publique o app para ele durar.
  4. ID da conta (customerId) — o número 123-456-7890 no canto superior direito do Google Ads, na conta de anúncios (não na MCC).
  5. Conta administradora (loginCustomerId) — só se o seu usuário acessa a conta de anúncios através da MCC: informe o ID da MCC. Se o acesso é direto, deixe vazio.
  6. No ingestia.io, em Dados → Conexões → Nova conexão → Google Ads, preencha ID da conta (customer ID), Conta administradora (MCC) (se for o caso), OAuth client ID, Developer token, OAuth client secret e Refresh token, e use Testar conexão.

Se a autorização expirar ou for revogada, gere um novo refresh token e use Reconectar na conexão — a fonte e o histórico são preservados.

Credenciais#

Forma de autenticação: OAuth 2.0 (client id/secret + refresh token). Todos os segredos são cifrados (AES-256-GCM) e nunca são exibidos de novo. Se a autorização expirar, basta reconectar — a fonte e o histórico são preservados.

Campos sensíveis. Eles são cifrados (AES-256-GCM) e nunca ficam no config da conexão, na definição do pipeline, no export ou na DAG. Por padrão o valor cifrado fica no banco; mover a credencial desta conexão para o cofre externo de credenciais é uma escolha explícita, feita por conexão depois de salvar — ver ../../administracao/credenciais-e-rotacao.md.

  • Developer token (developerToken) — Fica na Central de API da sua conta administradora (MCC). Precisa estar aprovado com acesso básico ou padrão.
  • OAuth client secret (clientSecret)
  • Refresh token (refreshToken) — Gerado uma vez com o escopo https://www.googleapis.com/auth/adwords, pelo mesmo cliente OAuth, por quem tem acesso à conta.

Segredos nunca são reexibidos e passam pela redação em todo erro/log (token cru, URL-encoded e em JSON).

Campos do formulário#

CampoRótuloTipoObrigatórioObservação
customerIdID da conta (customer ID)textosimAparece no canto superior direito do Google Ads.
loginCustomerIdConta administradora (MCC)textonão—
reportPresetRelatórioseleçãonãopadrão: campanhas; opções: campanhas / grupos / palavras
lookbackDaysJanela (dias)númeronãopadrão: 30
clientIdOAuth client IDtextosimDo cliente OAuth (tipo app para computador ou web) criado no seu projeto, com a API do Google Ads ativada.
developerToken 🔒Developer tokensenha/segredosimsegredo (cifrado; cofre externo opcional); Fica na Central de API da sua conta administradora (MCC). Precisa estar aprovado com acesso básico ou padrão.
clientSecret 🔒OAuth client secretsenha/segredosimsegredo (cifrado; cofre externo opcional)
refreshToken 🔒Refresh tokensenha/segredosimsegredo (cifrado; cofre externo opcional); Gerado uma vez com o escopo https://www.googleapis.com/auth/adwords, pelo mesmo cliente OAuth, por quem tem acesso à conta.

Passo a passo#

  1. No menu Dados → Conexões, use Nova conexão.
  2. Escolha Google Ads no catálogo.
  3. Preencha os campos do formulário (veja a tabela acima).
  4. Use Testar conexão. O resultado vem separado em Conectividade, Autenticação e Listagem/leitura — cada um com OK, Falhou, Não se aplica ou Não testado. Capacidade sem teste próprio para este conector aparece como Não se aplica, e Não se aplica nunca conta como sucesso.
  5. Use Salvar conexão. Salvar NÃO inicia ingestão nenhuma.
  6. No cartão da conexão, use Montar extração (ou vá em Orquestração → Pipelines e use Conectar fonte). O pipeline aponta para a conexão salva — a credencial não é copiada.
  7. Na revisão, Publicar (agenda desligada) cria a versão 1 sem executar nada. Depois, Ativar agenda e Executar agora são ações separadas.

Exemplo — teste de conexão#

Configuração de exemplo (todos os valores são fictícios; segredos aparecem mascarados):

text
# Exemplo sintético (valores fictícios — não são credenciais reais)
customerId = 123-456-7890
loginCustomerId = <loginCustomerId>
reportPreset = campanhas
lookbackDays = 30
clientId = exemplo-client-id-ficticio
developerToken = •••••• (cifrado — nunca exibido)
clientSecret = •••••• (cifrado — nunca exibido)
refreshToken = •••••• (cifrado — nunca exibido)

Resultado esperado#

O Testar conexão retorna a lista de tabelas/recursos descobertos. Após a primeira carga, as linhas aparecem na camada Bronze do seu workspace, prontas para o pipeline.

Limites e custos#

  • Paginação: teto duro por execução (default 10.000 páginas / 5.000.000 linhas); guarda anti-loop.
  • Carga SaaS: default batchSize 5.000, maxRows 200.000 por recurso.
  • Volume estimado: ~0.5 GB/mês (estimativa de catálogo, não medição).
  • Custo: a extração em si não é cobrada pela plataforma; a carga Bronze consome processamento do datalake (cobrável).

Segurança#

  • Escopo por workspace: cada cliente lê e escreve só no seu próprio datalake (<prefixo>_bronze / _silver / _gold); nunca há vazamento entre workspaces.
  • Segredos cifrados: material sensível é cifrado com AES-256-GCM antes de ser gravado. O cofre externo de credenciais é opcional e ligado por conexão; sem ele, o valor cifrado fica no banco. Trocar o valor aqui NÃO revoga a credencial na origem.
  • Redaction: todo erro/log passa pela redação de segredos (cru, URL-encoded e em JSON).
  • Produção não finge: um caminho que cairia em mock aciona a guarda de produção (falha explícita em vez de simular sucesso).

Erros comuns#

  • Credencial recusada (401/403) — o provedor não aceitou a credencial: expirada, revogada ou sem a permissão necessária. Reconecte a fonte (a fonte e o histórico são preservados; não recrie a fonte).
  • Limite de requisições (429) — o provedor pediu para esperar. A extração respeita Retry-After e retenta; se repetir, aguarde e reduza a frequência da agenda.
  • Recurso não encontrado — confira o identificador do recurso (conta, objeto, relatório) e as permissões concedidas.
  • Cursor de paginação travado — a extração encerra quando o cursor da API não avança (guarda anti-loop). Se acontecer em execuções seguidas, abra um chamado com o suporte informando o conector e o recurso.
  • Caminho de registros vazio — a resposta chegou sem registros no lugar esperado. Confira o recurso selecionado e os filtros (período, conta, status) antes de assumir que não há dados.

Solução de problemas#

  • Use Testar conexão para isolar problemas de credencial/rede antes de agendar.
  • Acompanhe as execuções na observabilidade por conector (taxa de erro, p50/p95, freshness).
  • Uma mudança de esquema na origem é sinalizada pelo schema drift (coluna nova = info; coluna removida/tipo mudado = atenção).

Relacionados#


Última revisão: 2026-10-05. Ficha gerada automaticamente do catálogo de conectores do produto.

Links relacionados