Configuration

Vous pouvez configurer la bibliothèque cliente Python à l'aide d'un fichier YAML, de variables d'environnement, d'une chaîne YAML ou d'un dict.

Configuration de l'authentification

Il existe plusieurs façons de gérer les identifiants OAuth nécessaires pour accéder à l'API Google Ads. L'approche que vous choisissez a une incidence sur les champs de configuration que vous utilisez. Pour en savoir plus, consultez le guide d'authentification.

Configuration à l'aide d'un fichier YAML

Vous pouvez spécifier un fichier YAML à utiliser lors de l'initialisation du client. Ce fichier contient les informations nécessaires pour envoyer des requêtes à l'API Google Ads. Ce fichier est accessible lorsqu'un client est initialisé à l'aide de la méthode load_from_storage. Le moyen le plus simple de générer ce fichier consiste à copier l' google-ads.yaml exemple du dépôt GitHub et à le modifier pour y inclure vos identifiants, y compris votre jeton d'actualisation, votre ID client et votre code secret du client.

Si vous ne fournissez pas de chemin d'accès, la bibliothèque recherche le fichier dans votre répertoire $HOME :

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

Pour spécifier un emplacement où se trouve le fichier google-ads.yaml, vous pouvez transmettre le chemin d'accès sous forme de chaîne à la méthode lorsque vous l'appelez :

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

Vous pouvez également spécifier le chemin d'accès en définissant une variable d'environnement spécifique :

import os
from google.ads.googleads.client import GoogleAdsClient

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

Si les deux valeurs sont fournies (un chemin d'accès est transmis à la méthode et la variable d'environnement est présente), la bibliothèque donne la priorité au chemin d'accès transmis à la méthode.

Configuration à l'aide de variables d'environnement

Vous pouvez stocker l'ensemble de la configuration de votre client en tant que variables d'environnement, qui sont lues lorsque vous utilisez la méthode load_from_env du client. Les variables d'environnement doivent porter le même nom que celles définies dans le fichier google-ads.yaml, mais doivent être en majuscules et précédées de l'espace de noms GOOGLE_ADS_. Par exemple, client_id doit être stocké sous la forme GOOGLE_ADS_CLIENT_ID.

Les variables d'environnement sont généralement définies dans un fichier de configuration bash tel qu'un fichier .bashrc ou .bash_profile situé dans le répertoire $HOME. Elles peuvent également être définies à l'aide de la ligne de commande.

Voici quelques étapes de base pour définir une variable d'environnement à l'aide d'un fichier .bashrc dans un terminal :

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

Les variables d'environnement peuvent également être définies directement dans votre instance de terminal à partir de la ligne de commande :

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

La méthode load_from_env charge les données de configuration à partir de l'attribut environ du module os intégré de Python. Exemple : os.environ["GOOGLE_ADS_CLIENT_ID"]

Voici un exemple d'initialisation d'une instance de client avec une configuration à partir de variables d'environnement :

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Pour configurer logging via des variables d'environnement, la valeur de configuration doit être un objet JSON qui correspond à la structure des clés YAML dans l'exemple de fichier de configuration google-ads.yaml.

Voici un exemple de configuration à l'aide d'un fichier .bashrc :

export GOOGLE_ADS_LOGGING='{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default_fmt": {
      "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
      "datefmt": "%Y-%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "default_handler": {
      "class": "logging.StreamHandler",
      "formatter": "default_fmt"
    }
  },
  "loggers": {
    "": {
      "handlers": ["default_handler"],
      "level": "INFO"
    }
  }
}'

Point important : Si la variable d'environnement GOOGLE_ADS_CONFIGURATION_FILE_PATH est définie lorsque la méthode load_from_env est appelée, les valeurs de configuration sont récupérées à partir du fichier google-ads.yaml situé au chemin d'accès spécifié, et non à partir des variables d'environnement décrites précédemment.

Configuration à l'aide d'une chaîne YAML

Si vous avez lu un fichier YAML en mémoire, vous pouvez le fournir directement au client lors de l'initialisation. Pour ce faire, utilisez la méthode load_from_string :

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

Configuration à l'aide d'un dict

Vous pouvez transmettre un dict directement à la méthode load_from_dict. Exemple :

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

Champs de configuration

La configuration de la bibliothèque cliente est compatible avec les champs suivants.

Authentification

N'utilisez qu'un seul de ces groupes de champs, en fonction de l'approche d'authentification que vous utilisez :

  • Utilisateur unique avec les identifiants par défaut de l'application (documentation)
    • use_application_default_credentials: indique si la bibliothèque doit utiliser les identifiants par défaut de l'application (ADC) pour l'authentification (compatible avec google-ads v28.3.0 et versions ultérieures).
  • Utilisateur unique avec des jetons OAuth (documentation)
    • client_id : votre ID client OAuth.
    • client_secret : votre code secret du client OAuth.
    • refresh_token : votre jeton d'actualisation OAuth.
  • Compte de service (documentation)
    • json_key_file_path : chemin d'accès à un fichier de clé privée local. Il est utilisé pour l'authentification à l'aide d'un compte de service.
    • impersonated_email: adresse e-mail facultative du compte à emprunter lorsque vous utilisez la délégation à l'échelle du domaine Google Workspace.

Comportement de la bibliothèque

Ces champs dictent le comportement de la bibliothèque :

Configuration au niveau de la requête

Variables d'environnement

Pour configurer la bibliothèque à l'aide de variables d'environnement, procédez comme suit :

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS (compatible avec v28.3.0 et versions ultérieures)

Configuration des journaux

Les champs de journal, qui sont des champs situés sous le champ de configuration logging, sont dérivés directement du module intégré logging.config, car la bibliothèque transmet tous les champs sous l'espace de noms logging directement à la logging.config.dictConfig méthode. Pour en savoir plus, consultez le guide de journalisation.

  • version : valeur entière représentant une version de schéma.
  • disable_existing_loggers: indique si les enregistreurs configurés ailleurs dans l'application doivent être désactivés.
  • formatters : dictionnaires définissant différents types de formatteurs.
  • handlers: dictionnaires définissant différents gestionnaires, qui contrôlent l'emplacement où les journaux sont écrits et les formatteurs à utiliser.
  • loggers: dictionnaires définissant différents types d'enregistreurs, qui incluent un gestionnaire et un niveau de journalisation.