Authentification et autorisation

Comme les autres API Google, l'API Google Ads utilise le protocole OAuth 2.0 pour l'authentification et l'autorisation. OAuth 2.0 permet à votre application cliente de l'API Google Ads d'accéder au compte Google Ads d'un utilisateur sans avoir à gérer ni à stocker ses informations de connexion.

Comprendre le modèle d'accès Google Ads

Pour utiliser efficacement l'API Google Ads, vous devez comprendre le fonctionnement du modèle d'accès Google Ads. Nous vous recommandons de lire le guide sur le modèle d'accès Google Ads.

Workflows OAuth

Trois workflows courants sont utilisés lorsque vous travaillez avec l'API Google Ads.

Flux du compte de service

Il s'agit du workflow recommandé si votre workflow ne nécessite aucune interaction humaine. Ce workflow nécessite une étape de configuration, au cours de laquelle l'utilisateur ajoute un compte de service à son compte Google Ads. L'application peut ensuite utiliser les identifiants du compte de service pour gérer le compte Google Ads de l'utilisateur. La bibliothèque Python est configurée comme suit :

  • Si vous utilisez un fichier google-ads.yaml ou une chaîne YAML, ajoutez les éléments suivants à votre configuration pour définir le chemin d'accès au fichier JSON de clé privée dans votre environnement local :

    json_key_file_path: JSON_KEY_FILE_PATH

    Appelez ensuite les méthodes load_from_storage ou load_from_string :

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

  • Si vous utilisez un dict pour configurer la bibliothèque, incluez la paire clé-valeur suivante et appelez la méthode load_from_dict en transmettant le dict de configuration :

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "json_key_file_path": JSON_KEY_FILE_PATH
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

  • Si vous utilisez des variables d'environnement, ajoutez les éléments suivants à votre configuration ou environnement bash :

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

    Appelez ensuite la méthode load_from_env :

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()
  ```

Si l'option de configuration json_key_file_path est présente dans l'une de ces méthodes de configuration et que l'option use_application_default_credentials est définie sur False ou n'est pas définie, la bibliothèque s'autorise automatiquement à l'aide du flux de compte de service.

Pour en savoir plus, consultez le guide sur le workflow des comptes de service.

Flux d'authentification mono-utilisateur

Vous pouvez utiliser ce workflow si vous ne pouvez pas utiliser de comptes de service. Ce workflow nécessite deux étapes de configuration :

  1. Autorisez un seul utilisateur à accéder à tous les comptes à gérer à l'aide de l'API Google Ads. Une approche courante consiste à accorder à l'utilisateur l'accès à un compte administrateur de l'API Google Ads et à associer tous les comptes Google Ads à ce compte administrateur.

  2. L'utilisateur exécute un outil tel que la gcloud CLI ou l'exemple de code generate_user_credentials pour autoriser votre application à gérer tous ses comptes Google Ads en son nom.

La bibliothèque peut être initialisée à l'aide des identifiants OAuth 2.0 de l'utilisateur comme suit :

Si vous utilisez l'outil gcloud CLI (recommandé)

  1. Suivez la documentation Générer des identifiants pour configurer les identifiants par défaut de l'application (ADC) dans votre environnement local.

  2. Ajoutez la configuration suivante à votre chaîne google-ads.yaml ou YAML :

    use_application_default_credentials: true

    Appelez ensuite la méthode load_from_storage ou load_from_string :

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    Si vous utilisez un dict pour configurer la bibliothèque, incluez la paire clé-valeur suivante et appelez la méthode load_from_dict :

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "use_account_default_credentials": True
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    Si vous utilisez des variables d'environnement, ajoutez les éléments suivants à votre configuration ou environnement bash :

    export GOOGLE_ADS_USE_ACCOUNT_DEFAULT_CREDENTIALS=true

    Appelez ensuite la méthode load_from_env :

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

Si vous gérez directement les jetons OAuth

  1. Suivez les étapes pour configurer un projet de console et téléchargez le fichier JSON qui inclut l'ID client et le code secret du client de votre projet.

  2. Clonez la bibliothèque cliente Python sur votre machine et accédez à son répertoire :

    $ git clone https://github.com/googleads/google-ads-python.git
$ cd google-ads-python

  3. Exécutez l'exemple en fournissant un chemin d'accès absolu au fichier JSON téléchargé à l'étape 1 :

    $ python examples/authentication/generate_user_credentials.py -c PATH_TO_CREDENTIALS_JSON

    Une fois l'opération terminée, un jeton d'actualisation s'affiche dans la console. Copiez-le et enregistrez-le pour l'étape suivante.

  4. Configurez la bibliothèque en ajoutant les paramètres suivants à la configuration de votre choix :

    Ajoutez la configuration suivante à votre chaîne google-ads.yaml ou YAML :

    client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE

    Appelez ensuite la méthode load_from_storage ou load_from_string :

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    Si vous utilisez un dict pour configurer la bibliothèque, incluez les paires clé-valeur suivantes et appelez la méthode load_from_dict :

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": INSERT_OAUTH2_CLIENT_ID_HERE
  "client_secret": INSERT_OAUTH2_CLIENT_SECRET_HERE
  "refresh_token": INSERT_REFRESH_TOKEN_HERE
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    Si vous utilisez des variables d'environnement, ajoutez les éléments suivants à votre configuration ou environnement bash :

    export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE

    Appelez ensuite la méthode load_from_env :

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

Pour en savoir plus, consultez le guide du workflow d'authentification pour un seul utilisateur.

Flux d'authentification multi-utilisateur

Il s'agit du workflow recommandé si votre application permet aux utilisateurs de se connecter et d'autoriser votre application à gérer leurs comptes Google Ads en leur nom. Votre application crée et gère les identifiants utilisateur OAuth 2.0. La bibliothèque peut être initialisée à l'aide des identifiants de l'utilisateur comme suit, ce qui suppose que votre application obtient les identifiants au moment de l'exécution, soit en exécutant un flux d'autorisation, soit en les chargeant à partir d'un datastore :

Un dict est le mécanisme de configuration le plus simple à utiliser pour obtenir des identifiants au moment de l'exécution :

from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": client_id
  "client_secret": client_secret
  "refresh_token": refresh_token
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

Pour en savoir plus, consultez le guide du workflow d'authentification multi-utilisateur.

Authentification manuelle

Vous pouvez générer des identifiants d'authentification avec n'importe quelle approche et les fournir à GoogleAdsClient manuellement en instanciant directement la classe cliente. En supposant que l'objet d'identifiants que vous créez soit une instance de google.auth.credentials.Credentials, vous pouvez le transmettre comme suit :

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`
credentials = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
  credentials=credentials,
  # ... insert remaining parameters
)

Que se passe-t-il si mon utilisateur gère plusieurs comptes ?

Il est courant qu'un utilisateur gère plusieurs comptes Google Ads, soit en y accédant directement, soit via un compte administrateur Google Ads. La bibliothèque cliente Python fournit les exemples de code suivants qui illustrent comment gérer de tels cas.

  1. L'exemple de code get_account_hierarchy montre comment récupérer la liste de tous les comptes d'un compte administrateur Google Ads.
  2. L'exemple de code list_accessible_customers montre comment récupérer la liste de tous les comptes auxquels un utilisateur a un accès direct. Ces comptes peuvent ensuite être utilisés comme valeurs valides pour le paramètre login_customer_id.