Guide d'intégration de l'API Google Ads

Ce guide décrit le processus de bout en bout pour l'intégration, l'authentification et le premier appel à l'API Google Ads.

1. Conditions préalables et hiérarchie des comptes

Avant d'interagir avec l'API Google Ads, vous devez comprendre la hiérarchie des comptes et disposer de la structure de compte de premier niveau appropriée.

  • Compte administrateur (CM) : un compte administrateur Google Ads (anciennement appelé Centre multicompte) est un compte principal utilisé pour afficher et gérer plusieurs comptes client. Vous devez disposer d'un compte administrateur pour demander un jeton de développeur de l'API Google Ads.
  • Compte client : compte standard dans lequel les campagnes, les groupes d'annonces et les annonces sont créés, et la facturation est configurée.

Action à effectuer : si vous ne disposez pas d'un compte administrateur, créez-en un sur la page Comptes administrateur Google Ads.

2. Obtenir un jeton de développeur

Le jeton de développeur identifie de manière unique votre application auprès de l'API Google Ads et contrôle votre niveau d'accès au volume d'appels.

Étapes à suivre

  1. Connectez-vous à votre compte administrateur Google Ads.
  2. Accédez à Outils et paramètres > Configuration > Centre API (ou Admin > Centre API).
  3. Remplissez le formulaire d'informations sur le développeur et acceptez les conditions d'utilisation de l'API.
  4. Envoyez votre demande d'inscription.

Niveaux d'accès

  • En attente d'approbation : les jetons nouvellement créés sont immédiatement mis en état "En attente". Vous pouvez utiliser un jeton en attente pour vous connecter immédiatement à des comptes de test, mais il ne fonctionnera pas avec les comptes de production.
  • Accès de base : permet d'effectuer jusqu'à 15 000 opérations d'API par jour une fois l'accès approuvé.
  • Accès standard : opérations d'API quotidiennes illimitées pour les applications qui répondent aux fonctionnalités minimales requises (RMF).

3. Configurer des comptes de test

Le développement et les tests sur des comptes de production risquent d'entraîner des dépenses publicitaires indésirables et des modifications de campagne. Il est fortement recommandé d'effectuer tous les développements actifs sur des comptes de test.

Créer un compte administrateur de test

  1. Accédez à la page de création d'un compte administrateur de test Google Ads.
  2. Connectez-vous avec un compte Google qui n'est pas déjà associé à votre compte administrateur Google Ads de production.
  3. Saisissez un nom de compte descriptif (par exemple, MyCompany Test MCC).
  4. Sélectionnez l'utilisation principale comme Gérer les comptes d'autres personnes.
  5. Choisissez votre pays de facturation, votre fuseau horaire et votre devise. Cliquez sur Enregistrer et continuer.

Créer un compte client de test

Une fois votre compte administrateur de test créé, vous devez créer au moins un compte client enfant pour diffuser des campagnes de test.

  1. Connectez-vous à votre compte administrateur de test nouvellement créé.
  2. Dans le menu de navigation de gauche, cliquez sur Comptes, puis sélectionnez Paramètres du sous-compte (ou Performances).
  3. Cliquez sur le bouton bleu + (Plus), puis sélectionnez Créer un compte.
  4. Sélectionnez Compte Google Ads.
  5. Saisissez un nom de compte (par exemple, Test Client Account A).
  6. Sélectionnez un fuseau horaire et une devise, puis cliquez sur Enregistrer et continuer.
  7. Notez l'ID client à 10 chiffres (par exemple, 1234567890 sans tirets) de ce nouveau compte client.

Règles importantes pour les comptes de test

  • Utilisation du jeton de développeur : ne demandez pas de jeton de développeur à partir de votre compte administrateur de test. Utilisez toujours le jeton de développeur en attente ou approuvé de votre compte administrateur de production.
  • Facturation : les comptes de test ne diffusent pas d'annonces réelles. Vous n'avez donc pas besoin de saisir de véritables informations de facturation.

4. Configurer un projet Google Cloud

Toutes les requêtes d'API doivent être authentifiées à l'aide d'un projet Google Cloud pour lequel l'API Google Ads est activée.

Activation de l'API

  1. Accédez à la console Google Cloud.
  2. Créez un projet ou sélectionnez-en un.
  3. Accédez à API et services > Bibliothèque.
  4. Recherchez API Google Ads , puis cliquez sur Activer.

Tarification et facturation

  • Aucun frais d'API : la création d'un projet Google Cloud, l'activation de l'API Google Ads et la génération d'identifiants OAuth 2.0 sont 100% sans frais. Google ne facture aucun frais pour l'appel ou l'utilisation de l'API Google Ads elle-même.
  • Autres ressources Cloud : vous n'encourez des frais Google Cloud que si vous utilisez activement d'autres services Google Cloud payants (tels que Compute Engine, Cloud Run ou BigQuery) au-delà des limites de leur niveau sans frais pour héberger votre application ou stocker vos données publicitaires.

5. Configurer l'authentification OAuth 2.0

L'API Google Ads utilise OAuth 2.0 pour authentifier et autoriser les requêtes.

Procédure pour le flux d'application de bureau

  1. Dans votre projet Google Cloud, accédez à API et services > Écran de consentement OAuth et configurez l'écran de consentement. Ajoutez votre adresse e-mail à la section Utilisateurs test lorsque l'application est en état "Test" pour éviter les erreurs d'accès lors de l'autorisation.
  2. Accédez à API et services > Identifiants.
  3. Cliquez sur Créer des identifiants > ID client OAuth.
  4. Sélectionnez le type d'application Application de bureau.
  5. Cliquez sur Créer, puis téléchargez le fichier d'identifiants OAuth au format client_secret.json (ou copiez votre Client ID et votre Client Secret).

Générer un jeton d'actualisation

Une fois que vous disposez de votre ID client et de votre code secret client, vous devez générer un jeton d'actualisation. Vous pouvez le faire à l'aide de Google OAuth 2.0 Playground ou d'un script de bibliothèque cliente.

Méthode A : Utiliser Google OAuth 2.0 Playground

  1. Accédez à Google OAuth 2.0 Playground.
  2. Cliquez sur l'icône en forme de roue dentée (configuration OAuth 2.0) en haut à droite.
  3. Cochez la case Utiliser vos propres identifiants OAuth.
  4. Saisissez votre Client ID et votre Client Secret OAuth2, puis cliquez sur Fermer.
  5. À l'étape 1 (Sélectionner et autoriser des API) à gauche, saisissez le champ d'application de l'API Google Ads dans le champ "Saisir vos propres champs d'application" : https://www.googleapis.com/auth/adwords
  6. Cliquez sur Autoriser les API. Lorsque vous y êtes invité, connectez-vous avec le compte Google qui a accès à votre compte administrateur Google Ads (ou compte de test).
  7. Cliquez sur Continuer sur l'écran de consentement.
  8. À l'étape 2 (Échanger le code d'autorisation contre des jetons), cliquez sur le bouton bleu Échanger le code d'autorisation contre des jetons.
  9. Vos Refresh token et Access token s'affichent dans le panneau de réponse. Copiez et enregistrez le Refresh token.

Méthode B : Utiliser un script de bibliothèque cliente (exemple Python)

La bibliothèque cliente Python officielle fournit un script d'assistance intégré pour générer des identifiants. Vous pouvez également télécharger votre fichier client_secret.json depuis la console Google Cloud et exécuter le script Python autonome suivant :

  1. Installez la bibliothèque OAuth requise :
pip install google-auth-oauthlib
  1. Créez un script nommé generate_refresh_token.py dans le même répertoire que client_secret.json et exécutez-le :
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. Configurer la bibliothèque cliente et les identifiants

Google fournit des bibliothèques clientes officiellement compatibles qui gèrent l'authentification, la sérialisation et la communication avec les points de terminaison gRPC.

Langues disponibles

  • Python : pip install google-ads
  • Java : disponible via Maven ou Gradle
  • PHP : composer require googleads/google-ads-php
  • .NET : Install-Package Google.Ads.GoogleAds
  • Ruby : gem install google-ads-googleads
  • Perl : cpanm Google::Ads::GoogleAds::Client

Fichier de configuration (google-ads.yaml)

Créez un fichier de configuration contenant vos identifiants. Par défaut, la méthode d'initialisation de la bibliothèque cliente (par exemple, GoogleAdsClient.load_from_storage()) recherche automatiquement google-ads.yaml à deux emplacements :

  1. Le répertoire de travail actuel à partir duquel votre script est exécuté.
  2. Votre répertoire personnel (~ sous Linux/macOS ou %HOMEPATH% sous Windows).

Si vous stockez le fichier dans un emplacement personnalisé, vous pouvez transmettre explicitement le chemin d'accès à la méthode d'initialisation (par exemple, load_from_storage("path/to/google-ads.yaml")).

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. Effectuer votre premier appel d'API

Pour vérifier la configuration de votre intégration, exécutez un script de démarrage rapide pour récupérer les campagnes existantes de votre compte de test.

Exemple de script Python (quickstart.py)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. Bonnes pratiques et ressources

  • Journalisation : activez la journalisation détaillée dans votre bibliothèque cliente pour capturer les ID de requête et de réponse (request-id), qui sont essentiels lorsque vous demandez l'assistance de Google.
  • Gestion des erreurs : mettez en œuvre une gestion robuste des erreurs pour GoogleAdsException, en particulier pour gérer les limites de débit (RESOURCE_TEMPORARILY_EXHAUSTED).
  • Documentation officielle : documentation pour les développeurs de l'API Google Ads
  • Bibliothèques clientes et exemples de code : dépôts GitHub Google Ads
Précédent
Présentation
Suivant
Guide de démarrage rapide