Lea antes:
../conectores.md(mapa de estados) efichas.md(índice de las fichas).
Qué es#
Lee informes de rendimiento de Google Ads (por campaña, grupo de anuncios o palabra clave) y carga en la capa Bronze.
Modos de ingestión soportados:
- Nós buscamos — Nós buscamos os dados na sua fonte.
Para qué sirve#
Traer los datos de Google Ads a su datalake y ponerlos a disposición en las capas Bronze/Silver/Gold, a los modelos de BI y al asistente de preguntas en lenguaje natural.
Cuándo usar / cuándo no usar#
Use cuando necesita consolidar esta fuente en el datalake de forma programada, con aislamiento por workspace.
Úselo con las credenciales de su empresa: el conector llama a la API de Google Ads con el token de desarrollador de su cuenta de administrador (MCC), un cliente OAuth de su proyecto y un refresh token de un usuario con acceso a la cuenta. Todo es suyo; nada depende de una app nuestra.
Plan y permisos#
- Plano: núcleo del producto (conectores forman parte de todos los planes; el límite es el número de fuentes del plan).
- Acceso: exige workspace activo — con la suscripción en atraso, suspendida o cancelada, la ejecución queda bloqueada.
- Desligamento: la ejecución de ingestión puede ser deshabilitada temporalmente (mantenimiento o incidente). Cuando eso ocurre, la pantalla informa que el recurso está indisponible en este momento.
Requisitos previos#
- Una cuenta de administrador (MCC) de Google Ads — es en ella donde se obtiene el token de desarrollador.
- Un usuario de Google con acceso (lectura es suficiente) a la cuenta publicitaria que desea leer.
- Un proyecto en la consola de nube de Google con la Google Ads API activada, para crear el cliente OAuth.
Cómo obtener cada credencial#
- Token de desarrollador (
developerToken) — en la cuenta de administrador (MCC), abra Herramientas → Configuración → Centro de API (API Center), acepte los términos y copie el token. Un token en nivel Acceso de prueba solo lee cuentas de prueba: solicite el Acceso básico en la misma pantalla para leer cuentas reales. - Cliente OAuth (
clientIdyclientSecret) — en la consola de nube de Google, en su proyecto: active la Google Ads API, configure la pantalla de consentimiento OAuth y cree una credencial ID de cliente OAuth del tipo App de escritorio (Desktop). Copie el ID de cliente y el secreto del cliente. - Refresh token (
refreshToken) — autorice ese cliente OAuth con el usuario que accede a la cuenta publicitaria, pidiendo el alcancehttps://www.googleapis.com/auth/adwords, y guarde el refresh token devuelto (ej.: con el OAuth Playground de Google, marcando Use your own OAuth credentials con su ID y secreto). Si la pantalla de consentimiento está en modo Prueba, el refresh token expira en 7 días — publique la app para que dure. - ID de la cuenta (
customerId) — el número123-456-7890en la esquina superior derecha de Google Ads, en la cuenta publicitaria (no en la MCC). - Cuenta de administrador (
loginCustomerId) — solo si su usuario accede a la cuenta publicitaria a través de la MCC: informe el ID de la MCC. Si el acceso es directo, déjelo vacío. - En ingestia.io, en Dados → Conexões → Nova conexão → Google Ads, complete ID da conta (customer ID), Conta administradora (MCC) (si corresponde), OAuth client ID, Developer token, OAuth client secret y Refresh token, y use Testar conexão.
Si la autorización expira o es revocada, genere un nuevo refresh token y use Reconectar en la conexión — la fuente y el historial se conservan.
Credenciales#
Forma de autenticación: OAuth 2.0 (client id/secret + refresh token). Todos los secretos están cifrados (AES-256-GCM) y nunca se muestran de nuevo. Si la autorización expira, basta reconectar — la fuente y el historial se preservan.
Campos sensibles. Están cifrados (AES-256-GCM) y nunca quedan en el config de la conexión, en la definición del pipeline, en el export o en la DAG. Por defecto el valor cifrado queda en la base; mover la credencial de esta conexión al cofre externo de credenciales es una elección explícita, hecha por conexión después de guardar — ver ../../administracao/credenciais-e-rotacao.md.
- Developer token (
developerToken) — Está en el Centro de API de su cuenta administradora (MCC). Debe estar aprobado con acceso básico o estándar. - OAuth client secret (
clientSecret) - Refresh token (
refreshToken) — Se genera una vez con el alcance https://www.googleapis.com/auth/adwords, por el mismo cliente OAuth, por quien tiene acceso a la cuenta.
Los secretos nunca se reexhiben y pasan por la redacción en todo error/log (token crudo, URL-encoded y en JSON).
Campos del formulario#
| Campo | Rótulo | Tipo | Obligatorio | Observación |
|---|---|---|---|---|
customerId | ID de la cuenta (customer ID) | texto | sí | Aparece en la esquina superior derecha de Google Ads. |
loginCustomerId | Cuenta administradora (MCC) | texto | no | — |
reportPreset | Informe | selección | no | predeterminado: campañas; opciones: campañas / grupos / palabras |
lookbackDays | Ventana (días) | número | no | predeterminado: 30 |
clientId | OAuth client ID | texto | sí | Del cliente OAuth (tipo app para computadora o web) creado en su proyecto, con la API de Google Ads activada. |
developerToken 🔒 | Developer token | contraseña/secreto | sí | secreto (cifrado; cofre externo opcional); Está en el Centro de API de su cuenta administradora (MCC). Debe estar aprobado con acceso básico o estándar. |
clientSecret 🔒 | OAuth client secret | contraseña/secreto | sí | secreto (cifrado; cofre externo opcional) |
refreshToken 🔒 | Refresh token | contraseña/secreto | sí | secreto (cifrado; cofre externo opcional); Se genera una vez con el alcance https://www.googleapis.com/auth/adwords, por el mismo cliente OAuth, por quien tiene acceso a la cuenta. |
Paso a paso#
- No menú Dados → Conexões, use Nova conexão.
- Elija Google Ads en el catálogo.
- Complete los campos del formulario (vea la tabla arriba).
- Use Testar conexão. El resultado viene separado en Conectividade, Autenticação y Listagem/leitura — cada uno con OK, Falló, No aplica o No probado. Una capacidad sin prueba propia para este conector aparece como No aplica, y No aplica nunca cuenta como éxito.
- Use Salvar conexão. Guardar NO inicia ninguna ingestión.
- En la tarjeta de la conexión, use Montar extração (o vaya a Orquestração → Pipelines y use Conectar fonte). O pipeline apunta a la conexión guardada — la credencial no se copia.
- En la revisión, Publicar (agenda desligada) crea la versión 1 sin ejecutar nada. Luego, Ativar agenda y Executar agora son acciones separadas.
Ejemplo — prueba de conexão#
Configuración de ejemplo (todos los valores son ficticios; secretos aparecen enmascarados):
# 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#
El Testar conexão retorna la lista de tablas/recursos descubiertos. Tras la primera carga, las filas aparecen en la capa Bronze de su workspace, listas para el pipeline.
Límites y costos#
- Paginação: límite rígido por ejecución (predeterminado 10.000 páginas / 5.000.000 filas); protección anti-loop.
- Carga SaaS: predeterminado
batchSize5.000,maxRows200.000 por recurso. - Volumen estimado: ~0.5 GB/mes (estimación de catálogo, no medición).
- **
Seguridad#
- Alcance por workspace: cada cliente lee y escribe solo en su propio datalake (
<prefixo>_bronze/_silver/_gold); nunca hay filtración entre workspaces. - Secretos cifrados: material sensible es cifrado con AES-256-GCM antes de ser grabado. El cofre externo de credenciales es opcional y se liga por conexión; sin él, el valor cifrado queda en la base. Cambiar el valor aquí NO revoca la credencial en el origen.
- Redaction: todo error/log pasa por la redacción de secretos (crudo, URL-encoded y en JSON).
- Producción no finge: un camino que caería en mock activa la guarda de producción (falla explícita en lugar de simular éxito).
Errores comunes#
- Credencial recusada (401/403) — el proveedor no aceptó la credencial: expirada, revocada o sin el permiso necesario. Reconecte la fuente (la fuente y el historial se preservan; no recree la fuente).
- Limite de requisições (429) — el proveedor pidió esperar. La extracción respeta
Retry-Aftery reintenta; si se repite, aguarde y reduzca la frecuencia del agendamiento. - Recurso não encontrado — verifique el identificador del recurso (cuenta, objeto, informe) y los permisos concedidos.
- Cursor de paginação travado — la extracción finaliza cuando el cursor de la API no avanza (protección anti-loop). Si ocurre en ejecuciones seguidas, abra un ticket con soporte informando el conector y el recurso.
- Caminho de registros vazio — la respuesta llegó sin registros en el lugar esperado. Revise el recurso seleccionado y los filtros (período, cuenta, estado) antes de asumir que no hay datos.
Solución de problemas#
- Use Testar conexão para aislar problemas de credencial/red antes de programar.
- Acompanhe as ejecuciones na observabilidade por conector (taxa de erro, p50/p95, freshness).
- Un cambio de esquema en la fuente es señalizado por el schema drift (columna nueva = info; columna removida/tipo cambiado = atención).
Relacionados#
../conectores.md— catálogo de conectores por estado../ingestao-incremental-backfill.md— full, incremental por watermark, backfill y checkpoint../pipeline-medalhao.md— capas Bronze/Silver/Gold y calidad../agendamento-retry-dlq.md— agendamiento, retry/backoff y DLQ../custo-limites-seguranca.md— costo, techos y seguridad por workspace
Última revisión: 2026-10-05. Ficha generada automáticamente del catálogo de conectores del producto.