Intégration à Google Ads

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

Google Ads est une plate-forme de publicité en ligne qui permet aux entreprises de faire la publicité de leurs produits ou services sur différentes propriétés Google. Cortex Framework regroupe vos données relatives aux annonces Google Ads avec 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 Cortex Framework Data Foundation :

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écuter le déploiement pour la source de données Google Ads.
`marketing.GoogleAds.deployCDC`	Déployer la CDC pour Google Ads	`true`	Générer des scripts de traitement CDC Google Ads à exécuter en tant que DAG dans Managed Airflow.
`marketing.GoogleAds.lookbackDays`	Jours de rétrospection pour Google Ads	`180`	Nombre de jours avant de commencer à extraire des 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é-association.

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

Vues de base

Il s'agit des objets bleus du diagramme entité-association. Ce sont des vues sur des tables CDC sans aucune transformation, à 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é-association. Ce sont des vues de rapports 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 de 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 valide next_page_token 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

Suivez ces étapes pour configurer l'authentification du compte :

Dans la Google Cloud console, 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 plus d'informations, consultez Description de l'utilisation du protocole OAuth 2.0 pour l'accès 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 section 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 aux identifiants utilisés pour générer le jeton.
Créez un secret à l'aide de Secret Manager :
- Dans la Google Cloud console, cliquez sur Secret Manager.
- Créez un secret appelé cortex-framework-google-ads-yaml au format suivant et modifiez 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 par 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 OAuth à l'étape 2.
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 la connexion en amont autorise, ainsi que par la fréquence d'exécution de votre DAG. Ajustez la fréquence d'exécution de votre DAG pour l'aligner sur la fréquence en amont, les contraintes de ressources et les besoins de votre entreprise.

Les données récupérées à l'aide de l'API Google Ads sont généralement disponibles avec une latence de plus de trois heures. Elles peuvent être ajustées 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 de connexion Managed Service pour Apache Airflow

Créez les connexions suivantes dans Managed Airflow. Pour en savoir plus, consultez la documentation Gérer les 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 de l'ensemble de données brutes > ensemble de données CDC.
`googleads_reporting_bq`	Pour le transfert de l'ensemble de données CDC > ensemble de données de reporting transfert.

Autorisations du compte de service Managed Airflow

Accordez des autorisations Dataflow au compte de service utilisé dans Managed Airflow (tel que configuré dans la connexion googleads_raw_dataflow). Pour obtenir des instructions, consultez la documentation Dataflow.

Paramètres d'ingestion

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

Tables sources vers tables brutes

Cette section décrit les entités extraites par les API et comment. 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 d'exécution d'un DAG pour cette entité afin d'extraire des 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 extraites 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 sur les 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é de 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 Partitionnement des tables.
`cluster_details`	Facultatif : si vous souhaitez que cette table soit mise en cluster pour des raisons de performances. Pour en savoir plus, consultez la section Paramètres du cluster.

Tables brutes vers tables CDC

Cette section décrit les entrées qui contrôlent le déplacement des données des tables brutes vers les tables CDC. Chaque entrée correspond à une table brute (qui à son tour correspond à l'entité de l'API Google Ads, comme mentionné).

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 les données brutes après la transformation CDC sont stockées (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 la table 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 sur les colonnes CDC et le 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 Partitionnement des tables.
`cluster_details`	Facultatif : si vous souhaitez que cette table soit mise en cluster pour des raisons de performances. Pour en savoir plus, consultez la section 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 finale de Google Ads à l'aide du fichier de paramètres de reporting src/GoogleAds/config/reporting_settings.yaml. Ce fichier contrôle la génération des objets BigQuery de la couche de reporting (tables, vues,fonctions ou procédures stockées).

Pour en savoir plus, consultez la section Personnaliser le fichier de paramètres de reporting.

Étape suivante

Pour en savoir plus sur les autres sources de données et charges de travail, consultez la section Sources de données et charges de travail.
Pour en savoir plus sur les étapes de déploiement dans les environnements de production, consultez la section Prérequis pour le déploiement de Cortex Framework Data Foundation.