Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

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. Consultez le guide sur le modèle d'accès Google Ads.

Workflows OAuth

Il existe trois workflows courants lorsque vous utilisez l'API Google Ads.

Parcours 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. Pour configurer cela, créez et téléchargez le fichier de clé JSON dans la console Google Cloud, puis copiez google_ads_config.rb dans votre répertoire personnel et modifiez-le pour spécifier l'emplacement de votre fichier de clé de compte de service (et l'adresse e-mail facultative de l'utilisateur à emprunter lors de l'utilisation de la délégation à l'échelle du domaine Google Workspace) :

# You can also authenticate using a service account. If "keyfile" is
# specified below, then service account authentication will be assumed and
# the above authentication fields ignored. Read more about service account
# authentication here:
# https://developers.google.com/google-ads/api/docs/oauth/service-accounts
c.keyfile = 'path/to/keyfile.json'
# Optional unless using Google Workspace domain-wide delegation:
c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Si vous préférez ne pas stocker ces informations dans un fichier et utiliser des variables d'environnement, vous pouvez définir GOOGLE_ADS_JSON_KEY_FILE_PATH (et GOOGLE_ADS_IMPERSONATED_EMAIL facultatif) :

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
# Optional unless using Google Workspace domain-wide delegation:
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Vous pouvez également transmettre le chemin d'accès au fichier de clé du compte de service (et l'adresse e-mail empruntée facultative) de manière programmatique au moment de l'exécution :

require 'google/ads/google_ads'

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.keyfile = '/path/to/your/service-account-key.json'
  # Optional unless using Google Workspace domain-wide delegation:
  config.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'
end

Vous pouvez également utiliser le gem googleauth pour créer des identifiants de compte de service et transmettre credentials.updater_proc à config.authentication :

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file.
key_file = '/path/to/your/service-account-key.json'

# Define the scopes needed for the Google Ads API.
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials.
credentials = File.open(key_file) do |io|
  Google::Auth::ServiceAccountCredentials.make_creds(
    json_key_io: io,
    scope: scopes
  )
end

# Initialize the Google Ads API client with these credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  # Inject the service account credential updater proc.
  config.authentication = credentials.updater_proc
end

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

Flux d'authentification pour un seul utilisateur

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

Accordez à un seul utilisateur l'accès à 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.
L'utilisateur exécute un outil de ligne de commande tel que l'outil de ligne de commande Google Cloud ou l'exemple de code GenerateUserCredentials pour autoriser votre application à gérer tous ses comptes Google Ads en son nom.

Vous pouvez configurer les identifiants OAuth 2.0 pour Ruby en copiant le fichier google_ads_config.rb dans votre répertoire personnel et en le modifiant pour inclure votre ID client, votre code secret client et votre jeton d'actualisation :

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

Le client lit automatiquement le fichier de configuration à partir du répertoire d'accueil s'il est instancié sans arguments :

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Si vous préférez stocker le fichier ailleurs, vous pouvez instancier le client en transmettant le chemin d'accès à l'emplacement où vous conservez ce fichier :

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Si vous préférez ne pas stocker ces informations dans un fichier et utiliser des variables d'environnement, vous pouvez définir chacune d'elles :

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

Vous pouvez également transmettre les informations de manière programmatique au moment de l'exécution :

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

Pour en savoir plus, consultez le guide du workflow d'authentification à utilisateur unique.

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. Ce workflow peut être configuré de la même manière que le workflow à utilisateur unique, avec le login_customer_id spécifié également.

Il est recommandé d'utiliser un fichier de configuration. Copiez le fichier google_ads_config.rb dans votre répertoire d'accueil et modifiez-le pour inclure votre ID client, votre code secret du client, votre jeton d'actualisation et votre numéro client :

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

# Required for manager accounts only: Specify the login customer ID used to
# authenticate API calls. This will be the customer ID of the authenticated
# manager account. If you need to use different values for this field, then
# make sure to fetch a new copy of the service after each time you change the
# value.
c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

Le client lit automatiquement le fichier de configuration à partir du répertoire d'accueil s'il est instancié sans arguments :

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Si vous préférez stocker le fichier ailleurs, vous pouvez instancier le client en transmettant le chemin d'accès à l'emplacement où vous conservez ce fichier :

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Si vous préférez ne pas stocker ces informations dans un fichier et utiliser des variables d'environnement, vous pouvez définir chacune d'elles :

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

Vous pouvez également transmettre les informations de manière programmatique au moment de l'exécution :

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Pour en savoir plus, consultez le guide du workflow d'authentification multi-utilisateur. La bibliothèque cliente Ruby inclut un exemple de code à titre de référence. L'exemple de code en ligne de commande GenerateUserCredentials illustre comment obtenir l'authentification de l'utilisateur au moment de l'exécution pour gérer ses comptes Google Ads en son nom. Vous pouvez utiliser cet exemple de code comme référence pour créer des applications de bureau nécessitant l'authentification des utilisateurs.

Gérer 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 Ruby fournit les exemples de code suivants qui illustrent la façon de gérer ces cas :

L'exemple de code GetAccountHierarchy montre comment récupérer la liste de tous les comptes d'un compte administrateur Google Ads.
L'exemple de code ListAccessibleCustomers 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.

Identifiants par défaut de l'application

La bibliothèque cliente Ruby (version 36.1.0 et ultérieure) est également compatible avec l'authentification à l'aide des identifiants par défaut de l'application (ADC). Il vous permet de définir les identifiants par défaut de votre application sans avoir à configurer les informations OAuth 2.0 dans la configuration de votre application.

Cela est particulièrement utile pour le développement local ou pour le développement avec différentes API Google, car vous pouvez réutiliser les mêmes identifiants, à condition qu'ils puissent accéder aux champs d'application OAuth 2.0 requis.

Pour l'API Google Ads, assurez-vous que les identifiants par défaut de votre application peuvent accéder au champ d'application OAuth 2.0 https://www.googleapis.com/auth/adwords.

Pour utiliser les identifiants par défaut de l'application, utilisez l'outil de ligne de commande Google Cloud et authentifiez-vous pour ADC :

gcloud auth application-default login

Cette commande ouvre un navigateur Web pour terminer le processus d'authentification de votre compte Google. Une fois autorisé, il stocke les identifiants dans un emplacement standard. Vous devez ensuite mettre à jour votre application pour utiliser ADC.

Copiez le fichier google_ads_config.rb dans votre répertoire personnel et définissez use_application_default_credentials sur true :

# You can also authenticate using Application Default Credentials (ADC).
# To understand how ADC discovers credentials in a given environment, see:
# https://developers.google.com/identity/protocols/application-default-credentials
c.use_application_default_credentials = true

Si vous préférez ne pas stocker ces informations dans un fichier et utiliser des variables d'environnement, vous pouvez définir GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS :

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

Vous pouvez également transmettre les informations de manière programmatique au moment de l'exécution. Lorsque vous initialisez le client dans votre code Ruby, définissez config.use_application_default_credentials = true et ne fournissez pas d'identifiants OAuth 2.0 explicites. La bibliothèque détecte et utilise automatiquement les identifiants configurés par l'outil de ligne de commande Google Cloud :

# Initialize the client using Application Default Credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.use_application_default_credentials = true

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = 'YOUR_LOGIN_CUSTOMER_ID'

  # Do NOT include client_id, client_secret, or refresh_token here.
end

Consultez la page de configuration pour en savoir plus sur les options disponibles pour configurer la bibliothèque cliente Ruby.