> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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ê. |
Ative a Google Ads API no projeto e crie um cliente OAuth em **APIs & Services → Credentials**. Copie o Client ID e o Client Secret.
Na tela de consentimento OAuth, deixe o app em **In production**. Em **Testing**, o refresh token expira em 7 dias.
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.
Se as contas ficam sob uma MCC, anote o ID dela, no formato `123-456-7890`.
## Configuração no Console
Em **Conectores**, clique em **+ Nova Conexão** e selecione **Google Ads**, em **Mídia paga**.
**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.
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.
Em **Sincronização** (Obrigatório), escolha a frequência. O padrão do Google Ads é uma vez por dia, às 06:00 UTC.
Em **Permissionamento**, defina **Quem pode usar este conector**. O **Comportamento dos dados** é sempre "Aberto".
Em **Revisão**, confira os dados e salve. O Client Secret e o Refresh Token não aparecem na revisão.
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](https://developers.google.com/google-ads/api/docs/best-practices/quotas)
## 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
Ligue os recursos e as tabelas clean do Google Ads e escolha o modo de carga das métricas.
Veja como contas, campanhas, orçamentos, grupos, anúncios e palavras-chave entram no grafo.
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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.