Intégration à Google Ads

Cette page décrit les configurations requises pour importer des données depuis Google Ads en tant que source de données de la charge de travail marketing de la fondation de données Cortex Framework.

Google Ads est une plate-forme publicitaire en ligne qui permet aux entreprises de promouvoir leurs produits ou services sur différentes propriétés Google. Cortex Framework rassemble vos données Google Ads et celles d'autres canaux marketing, les analyse de manière exhaustive et utilise l'IA pour améliorer les résultats de vos campagnes.

Le schéma suivant décrit comment les données Google Ads sont disponibles via la charge de travail marketing de la Data Foundation Cortex Framework :

Source de données Google Ads

Figure 1. Source de données Google Ads.

Fichier de configuration

Le fichier config.json configure les paramètres requis pour transférer des données depuis n'importe quelle source de données, y compris Google Ads. Ce fichier contient les paramètres suivants pour Google Ads :

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

Le tableau suivant décrit la valeur de chaque paramètre marketing Google Ads :

Paramètre	Signification	Valeur par défaut	Description
`marketing.deployGoogleAds`	Déployer Google Ads	`true`	Exécutez le déploiement pour la source de données Google Ads.
`marketing.GoogleAds.deployCDC`	Déployer CDC pour Google Ads	`true`	Générez des scripts de traitement CDC Google Ads à exécuter en tant que DAG dans Managed Airflow.
`marketing.GoogleAds.lookbackDays`	Jours de période d'analyse pour Google Ads	`180`	Nombre de jours à partir desquels commencer à extraire les données de l'API Google Ads.
`marketing.GoogleAds.datasets.cdc`	Ensemble de données CDC pour Google Ads		Ensemble de données CDC pour Google Ads.
`marketing.GoogleAds.datasets.raw`	Ensemble de données brutes pour Google Ads		Ensemble de données brutes pour Google Ads.
`marketing.GoogleAds.datasets.reporting`	Ensemble de données de reporting pour Google Ads	`"REPORTING_GoogleAds"`	Ensemble de données de reporting pour Google Ads.

Modèle de données

Cette section décrit le modèle de données Google Ads à l'aide du diagramme entité-relation (ERD).

Figure 2. Google Ads : diagramme entité-relation.

Vues de base

Il s'agit des objets bleus du diagramme entité-relation. Ce sont des vues sur les tables CDC sans transformations, à l'exception de certains alias de noms de colonnes. Consultez les scripts dans src/marketing/src/GoogleAds/src/reporting/ddls.

Vues de rapports

Il s'agit des objets verts du diagramme entité-relation. Ce sont des vues de reporting qui contiennent des métriques agrégées. Consultez les scripts dans src/marketing/src/GoogleAds/src/reporting/ddls.

Connexion à l'API

Les modèles d'ingestion Cortex Framework utilisent l'API Google Ads pour récupérer les attributs et les métriques de reporting de Google Ads. Les modèles Cortex Framework actuels utilisent la version 17.1 de l'API Google Ads. Tenez compte des limites de l'API Google Ads :

Opérations d'accès de base par jour : 15 000 (les requêtes paginées contenant un next_page_token valide ne sont pas comptabilisées).
Taille maximale des pages : 10 000 lignes par page.
Paramètres par défaut recommandés : la taille de la page est égale à 10 000 lignes par page.

Pour en savoir plus sur la connexion à l'API, consultez la documentation de l'API Google Ads.

Authentification du compte

Pour configurer l'authentification du compte :

Dans la consoleGoogle Cloud , cliquez sur Menu de navigation > API et services > Identifiants > Créer des identifiants.
Créez un identifiant ID client OAuth avec les caractéristiques suivantes. Pour en savoir plus, consultez Utiliser OAuth 2.0 pour accéder aux API Google.
```
Application type: "Web Application"
Name: CHOSEN_NAME #(For example,"Cortex Authentication Client").
Authorized redirect URIs: http://127.0.0.1
```
Remplacez CHOSEN_NAME par le nom choisi pour le compte d'identifiants de l'ID client OAuth.
Enregistrez les Client ID et Client secret une fois les identifiants configurés. Vous en aurez besoin ultérieurement.
Générez un nouveau jeton à l'aide de la page Utiliser OAuth 2.0 pour accéder aux API Google. Cortex Data Foundation détecte et ingère automatiquement les données de tous les clients (comptes) accessibles avec les identifiants utilisés pour générer le jeton.
Créez un secret à l'aide de Secret Manager :
- Dans la consoleGoogle Cloud , cliquez sur Secret Manager.
- Créez un secret appelé cortex-framework-google-ads-yaml en utilisant le format suivant et en modifiant les valeurs en fonction de vos paramètres :
```
{"developer_token": "DEVELOPER_TOKEN_VALUE", "refresh_token": "REFRESH_TOKEN_VALUE", "client_id": "CLIENT_ID_VALUE", "client_secret": "CLIENT_SECRET_VALUE", "use_proto_plus": False}
```

Remplacez les éléments suivants :

DEVELOPER_TOKEN_VALUE avec la valeur du jeton de développeur disponible dans le compte Google Ads.
REFRESH_TOKEN_VALUE par la valeur du jeton d'actualisation obtenue à l'étape 4.
CLIENT_ID_VALUE par la valeur de l'ID client obtenue lors de la configuration d'OAuth à l'étape 2.
Remplacez CLIENT_SECRET_VALUE par la valeur du code secret du client obtenue lors de la configuration OAuth à l'étape 2.

Fraîcheur et délai des données

En règle générale, la fraîcheur des données pour les sources de données Cortex Framework est limitée par ce que permet la connexion en amont, ainsi que par la fréquence d'exécution de votre DAG. Ajustez la fréquence d'exécution de votre DAG pour l'adapter à la fréquence en amont, aux contraintes de ressources et à vos besoins commerciaux.

Les données récupérées à l'aide de l'API Google Ads sont généralement disponibles avec une latence de trois heures ou plus. Ils pourront être ajustés par la suite en raison des conversions et de la détection du trafic incorrect. Pour en savoir plus, consultez l'article À propos de la fraîcheur des données du centre d'aide Google Ads.

Autorisations des connexions Managed Service pour Apache Airflow

Créez les connexions suivantes dans Managed Airflow. Pour en savoir plus, consultez la documentation sur la gestion des connexions Airflow.

Nom de la connexion	Purpose
`googleads_raw_dataflow`	Pour l'API Google Ads > Ensemble de données brutes BigQuery.
`googleads_cdc_bq`	Pour le transfert d'ensemble de données brutes > ensemble de données CDC.
`googleads_reporting_bq`	Pour le transfert de l'ensemble de données CDC vers l'ensemble de données de reporting.

Autorisations du compte de service Managed Airflow

Accorder des autorisations Dataflow au compte de service utilisé dans Managed Airflow (tel que configuré dans la connexion googleads_raw_dataflow). Consultez les instructions dans la documentation Dataflow.

Paramètres d'ingestion

Contrôlez les pipelines de données Source to Raw et Raw to CDC à l'aide des paramètres du fichier src/GoogleAds/config/ingestion_settings.yaml. Cette section décrit les paramètres de chaque pipeline de données.

Source vers les tables brutes

Cette section décrit les entités récupérées par les API et la manière dont elles le sont. Chaque entrée correspond à une entité Google Ads. Sur la base de cette configuration, Cortex crée des DAG Airflow qui exécutent des pipelines Dataflow pour extraire des données à l'aide des API Google Ads.

Les paramètres suivants contrôlent les paramètres de Source to Raw pour chaque entrée :

Paramètre	Description
`load_frequency`	Fréquence à laquelle un DAG pour cette entité s'exécute pour extraire les données de Google Ads. Pour en savoir plus sur les valeurs possibles, consultez la documentation Airflow.
`api_name`	Nom de ressource de l'API (par exemple, `customer`).
`table_name`	Table de l'ensemble de données brutes dans laquelle les données récupérées sont stockées (par exemple, `customer`).
`schema_file`	Fichier de schéma dans le répertoire `src/table_schema` qui mappe les champs de réponse de l'API aux noms de colonnes de la table de destination.
`key`	Colonnes (séparées par une virgule) qui forment un enregistrement unique pour cette table.
`is_metrics_table`	Indique si une entrée donnée concerne une entité métrique (dans l'API Google Ads). Le système traite ces tables un peu différemment en raison de leur nature agrégée.
`partition_details`	Facultatif : si vous souhaitez que cette table soit partitionnée pour des raisons de performances. Pour en savoir plus, consultez Partition de table.
`cluster_details`	Facultatif : si vous souhaitez que cette table soit regroupée pour des raisons de performances. Pour en savoir plus, consultez Paramètres du cluster.

Tables brutes vers tables CDC

Cette section décrit les entrées qui contrôlent la façon dont les données sont transférées des tables brutes vers les tables CDC. Chaque entrée correspond à une table brute (qui correspond elle-même à une entité de l'API Google Ads, comme indiqué).

Les paramètres suivants contrôlent les paramètres de Raw to CDC pour chaque entrée :

Paramètre	Description
`table_name`	Table de l'ensemble de données CDC dans laquelle sont stockées les données brutes après la transformation CDC (par exemple, `customer`).
`raw_table`	Table sur laquelle les données brutes ont été répliquées.
`key`	Colonnes (séparées par une virgule) qui forment un enregistrement unique pour cette table.
`load_frequency`	Fréquence d'exécution d'un DAG pour cette entité afin de remplir le tableau CDC. Pour en savoir plus sur les valeurs possibles, consultez la documentation Airflow.
`schema_file`	Fichier de schéma dans le répertoire `src/table_schema` qui mappe les colonnes brutes aux colonnes CDC et au type de données de la colonne CDC. Il s'agit du même fichier de schéma que celui mentionné dans la section précédente.
`partition_details`	Facultatif : si vous souhaitez que cette table soit partitionnée pour des raisons de performances. Pour en savoir plus, consultez Partition de table.
`cluster_details`	Facultatif : si vous souhaitez que cette table soit regroupée pour des raisons de performances. Pour en savoir plus, consultez Paramètres du cluster.

Paramètres de création de rapports

Vous pouvez configurer et contrôler la façon dont Cortex Framework génère des données pour la couche de reporting final Google Ads à l'aide du fichier de paramètres de reporting src/GoogleAds/config/reporting_settings.yaml. Ce fichier contrôle la façon dont les objets BigQuery de la couche de reporting (tables, vues,fonctions ou procédures stockées) sont générés.

Pour en savoir plus, consultez Personnaliser le fichier de paramètres de création de rapports.

Étape suivante

Pour en savoir plus sur les autres sources de données et charges de travail, consultez Sources de données et charges de travail.
Pour en savoir plus sur les étapes de déploiement dans les environnements de production, consultez Conditions préalables au déploiement de la Data Foundation de Cortex Framework.