Integración con Google Ads

En esta página, se describen las configuraciones necesarias para importar datos de Google Ads como fuente de datos de la carga de trabajo de marketing de la base de datos de Cortex Framework.

Google Ads es una plataforma publicitaria en línea que permite a las empresas promocionar sus productos o servicios en varias propiedades de Google. Cortex Framework combina tus datos de anuncios de Google Ads con otros canales de marketing, los analiza de forma integral y utiliza la IA para mejorar los resultados de tus campañas.

En el siguiente diagrama, se describe cómo los datos de anuncios de Google Ads están disponibles a través de la carga de trabajo de marketing de la base de datos de Cortex Framework:

Fuente de datos de Google Ads

Figura 1. Es la fuente de datos de Google Ads.

Archivo de configuración

El archivo config.json configura los parámetros necesarios para transferir datos desde cualquier fuente de datos, incluido Google Ads. Este archivo contiene los siguientes parámetros para Google Ads:

  "marketing": {
          "deployGoogleAds": true,
          "GoogleAds": {
              "deployCDC": true,
              "lookbackDays": 180,
              "datasets": {
                  "cdc": "",
                  "raw": "",
                  "reporting": "REPORTING_GoogleAds"
                    }
                  }
                 }

En la siguiente tabla, se describe el valor de cada parámetro de marketing de Google Ads:

Parámetro	Significado	Valor predeterminado	Descripción
`marketing.deployGoogleAds`	Implementa Google Ads	`true`	Ejecuta la implementación de la fuente de datos de Google Ads.
`marketing.GoogleAds.deployCDC`	Implementa el CDC para Google Ads	`true`	Generar secuencias de comandos de procesamiento de CDC de Google Ads para ejecutarlas como DAG en Managed Airflow
`marketing.GoogleAds.lookbackDays`	Período de observación de Google Ads	`180`	Cantidad de días a partir de los cuales se comenzarán a recuperar datos de la API de Google Ads.
`marketing.GoogleAds.datasets.cdc`	Conjunto de datos de CDC para Google Ads		Es el conjunto de datos de CDC para Google Ads.
`marketing.GoogleAds.datasets.raw`	Conjunto de datos sin procesar para Google Ads		Es el conjunto de datos sin procesar de Google Ads.
`marketing.GoogleAds.datasets.reporting`	Conjunto de datos de informes para Google Ads	`"REPORTING_GoogleAds"`	Es el conjunto de datos de informes de Google Ads.

Modelo de datos

En esta sección, se describe el modelo de datos de Google Ads con el diagrama de relación entre entidades (ERD).

Figura 2: Google Ads: Diagrama de relación entre entidades.

Vistas base

Estos son los objetos azules en el DER y son vistas de las tablas de CDC sin transformaciones, excepto algunos alias de nombres de columnas. Consulta las secuencias de comandos en src/marketing/src/GoogleAds/src/reporting/ddls.

Vistas de informes

Estos son los objetos verdes en el DER y son vistas de informes que contienen métricas agregadas. Consulta las secuencias de comandos en src/marketing/src/GoogleAds/src/reporting/ddls.

Conexión a la API

Las plantillas de transferencia de Cortex Framework usan la API de Google Ads para recuperar los atributos y las métricas de informes de Google Ads. Las plantillas actuales de Cortex Framework usan la versión 17.1 de la API de Google Ads. Ten en cuenta las limitaciones de la API de Google Ads:

Operaciones de acceso básico por día: 15,000 (no se cuentan las solicitudes paginadas que contienen un next_page_token válido).
Tamaño máximo de la página: 10,000 filas por página.
Parámetros predeterminados recomendados: El tamaño de la página es igual a 10,000 filas por página.

Para obtener más información sobre la conexión a la API, consulta la documentación de la API de Google Ads.

Autenticación de cuenta

Sigue estos pasos para configurar la autenticación de la cuenta:

En la Google Cloud consola, haz clic en Menú de navegación > APIs y servicios > Credenciales > Crear credenciales.
Crea una credencial de ID de cliente de OAuth con las siguientes características. Si deseas obtener más información, consulta Usa OAuth 2.0 para acceder a las APIs de Google.
```
Application type: "Web Application"
Name: CHOSEN_NAME #(For example,"Cortex Authentication Client").
Authorized redirect URIs: http://127.0.0.1
```
Reemplaza CHOSEN_NAME por el nombre elegido para la cuenta de credenciales del ID de cliente de OAuth.
Guarda Client ID y Client secret después de configurar la credencial. La necesitarás más tarde.
Genera un token nuevo con Usa OAuth 2.0 para acceder a las APIs de Google. Cortex Data Foundation detecta y procesa automáticamente los datos de todos los clientes (cuentas) a los que se puede acceder con las credenciales que se usan para generar el token.
Crea un secreto con Secret Manager:
- En la Google Cloud consola, haz clic en Secret Manager.
- Crea un secreto llamado cortex-framework-google-ads-yaml con el siguiente formato y cambia los valores según tu configuración:
```
{"developer_token": "DEVELOPER_TOKEN_VALUE", "refresh_token": "REFRESH_TOKEN_VALUE", "client_id": "CLIENT_ID_VALUE", "client_secret": "CLIENT_SECRET_VALUE", "use_proto_plus": False}
```

Reemplaza lo siguiente:

DEVELOPER_TOKEN_VALUE con el valor del token de desarrollador disponible en la cuenta de Google Ads.
REFRESH_TOKEN_VALUE por el valor del token de actualización que obtuviste en el paso 4.
CLIENT_ID_VALUE con el valor del ID de cliente que obtuviste en la configuración de OAuth del paso 2.
CLIENT_SECRET_VALUE con el valor del secreto del cliente que obtuviste de la configuración de OAuth en el paso 2.

Actualidad y demora de los datos

Como regla general, la actualización de los datos de las fuentes de datos de Cortex Framework está limitada por lo que permite la conexión upstream, así como por la frecuencia de ejecución de tu DAG. Ajusta la frecuencia de ejecución de tu DAG para que coincida con la frecuencia de los procesos ascendentes, las restricciones de recursos y las necesidades de tu empresa.

Los datos recuperados con la API de Google Ads están disponibles de forma general con una latencia de más de 3 horas. Es posible que se ajusten posteriormente debido a las conversiones y la detección de tráfico no válido. Para obtener más información, consulta el siguiente artículo Acerca de la actualización de los datos en el Centro de ayuda de Google Ads.

Permisos de conexiones de Managed Service para Apache Airflow

Crea las siguientes conexiones en Managed Airflow. Para obtener más detalles, consulta la documentación sobre cómo administrar conexiones de Airflow.

Nombre de la conexión	Purpose
`googleads_raw_dataflow`	Para la API de Google Ads > Conjunto de datos sin procesar de BigQuery
`googleads_cdc_bq`	Para la transferencia de conjuntos de datos sin procesar > conjuntos de datos de CDC.
`googleads_reporting_bq`	Para la transferencia de datos del conjunto de datos de CDC al conjunto de datos de informes.

Permisos de la cuenta de servicio de Airflow administrado

Otorga permisos de Dataflow a la cuenta de servicio que se usa en Airflow administrado (como se configuró en la conexión googleads_raw_dataflow). Consulta las instrucciones en la documentación de Dataflow.

Configuración de transferencia

Controla las canalizaciones de datos Source to Raw y Raw to CDC a través de la configuración del archivo src/GoogleAds/config/ingestion_settings.yaml. En esta sección, se describen los parámetros de cada canalización de datos.

De tablas de origen a tablas sin procesar

En esta sección, se describe qué entidades recuperan las APIs y cómo lo hacen. Cada entrada corresponde a una entidad de Google Ads. Según esta configuración, Cortex crea DAG de Airflow que ejecutan canalizaciones de Dataflow para recuperar datos con las APIs de Google Ads.

Los siguientes parámetros controlan la configuración de Source to Raw para cada entrada:

Parámetro	Descripción
`load_frequency`	Es la frecuencia con la que se ejecuta un DAG para esta entidad y se recuperan datos de Google Ads. Para obtener más información sobre los valores posibles, consulta la documentación de Airflow.
`api_name`	Nombre del recurso de API (por ejemplo, `customer`).
`table_name`	Tabla en el conjunto de datos sin procesar en la que se almacenan los datos recuperados (por ejemplo, `customer`).
`schema_file`	Archivo de esquema en el directorio `src/table_schema` que asigna los campos de respuesta de la API a los nombres de las columnas de la tabla de destino.
`key`	Columnas (separadas por comas) que forman un registro único para esta tabla.
`is_metrics_table`	Indica si una entrada determinada corresponde a una entidad de métrica (en la API de Google Ads). El sistema trata estas tablas de manera un poco diferente debido a su naturaleza agregada.
`partition_details`	Opcional: Si deseas que esta tabla se particione por motivos de rendimiento. Para obtener más información, consulta Partición de tablas.
`cluster_details`	Opcional: Si deseas que esta tabla se agrupe para tener en cuenta el rendimiento. Para obtener más información, consulta Configuración del clúster.

Tablas sin procesar a CDC

En esta sección, se describen las entradas que controlan cómo se transfieren los datos de las tablas sin procesar a las tablas de CDC. Cada entrada corresponde a una tabla sin procesar (que, a su vez, corresponde a una entidad de la API de Google Ads, como se mencionó).

Los siguientes parámetros controlan la configuración de Raw to CDC para cada entrada:

Parámetro	Descripción
`table_name`	Tabla en el conjunto de datos de CDC en la que se almacenan los datos sin procesar después de la transformación de CDC (por ejemplo, `customer`).
`raw_table`	Es la tabla en la que se replicaron los datos sin procesar.
`key`	Columnas (separadas por comas) que forman un registro único para esta tabla.
`load_frequency`	Frecuencia con la que se ejecuta un DAG para esta entidad y, así, completar la tabla del CDC. Para obtener más información sobre los valores posibles, consulta la documentación de Airflow.
`schema_file`	Archivo de esquema en el directorio `src/table_schema` que asigna columnas sin procesar a columnas de CDC y al tipo de datos de la columna de CDC. Este es el mismo archivo de esquema al que se hace referencia en la sección anterior.
`partition_details`	Opcional: Si deseas que esta tabla se particione por motivos de rendimiento. Para obtener más información, consulta Partición de tablas.
`cluster_details`	Opcional: Si deseas que esta tabla se agrupe para tener en cuenta el rendimiento. Para obtener más información, consulta Configuración del clúster.

Configuración de informes

Puedes configurar y controlar cómo Cortex Framework genera datos para la capa de informes finales de Google Ads con el archivo de configuración de informes src/GoogleAds/config/reporting_settings.yaml. Este archivo controla cómo se generan los objetos de BigQuery de la capa de informes (tablas, vistas,funciones o procedimientos almacenados).

Para obtener más información, consulta Cómo personalizar el archivo de configuración de informes.

Próximos pasos

Para obtener más información sobre otras fuentes de datos y cargas de trabajo, consulta Fuentes de datos y cargas de trabajo.
Para obtener más información sobre los pasos para la implementación en entornos de producción, consulta Requisitos previos para la implementación de la base de datos de Cortex Framework.