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. 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 de l'utilisateur à emprunter :

  # 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'
  # 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 respectivement.

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Vous pouvez également transmettre les informations de manière programmatique au moment de l'exécution, en utilisant le gem googleauth pour créer des identifiants à partir d'un fichier JSON de compte de service :

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 = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open(key_file),
  scope: scopes
)

# Initialize the Google Ads API client with these credentials
client = Google::Ads::GoogleAds::Client.new do |config|
  config.developer_token = "YOUR_DEVELOPER_TOKEN"
  # Inject the service account credentials
  config.oauth2_client = credentials
end

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 de ligne de commande tel que gcloud ou l'exemple de code GenerateUserCredentials pour autoriser votre application à gérer tous ses comptes Google Ads en son nom.

Les identifiants OAuth 2.0 peuvent être configurés pour Ruby en copiant le fichier google_ads_config.rb dans votre répertoire personnel et en le modifiant pour inclure votre jeton de développeur, votre ID client, votre code secret client et votre jeton d'actualisation :

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # 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 lira automatiquement le fichier de configuration à partir du répertoire personnel 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 plutôt des variables d'environnement, vous pouvez définir chacune d'elles :

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

Nous vous recommandons 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 jeton de développeur, votre ID client, votre code secret client, votre jeton d'actualisation et votre numéro client :

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # 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 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 lira automatiquement le fichier de configuration à partir du répertoire personnel 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 plutôt des variables d'environnement, vous pouvez définir chacune d'elles :

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
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.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  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 pour référence. GenerateUserCredentials est un exemple de code en ligne de commande qui montre 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.

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 Ruby fournit les exemples de code suivants qui illustrent comment gérer de tels cas.

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

Identifiants par défaut de l'application

La bibliothèque cliente Ruby 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 habilitations OAuth 2.0 appropriées.

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, nous vous recommandons d'utiliser l'outil de ligne de commande Google Cloud et de vous authentifier pour les ADC :

gcloud auth application-default login

Cette commande ouvre un navigateur Web pour terminer le flux 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 qu'elle utilise ADC.

Nous vous recommandons d'utiliser un fichier de configuration. Copiez le fichier google_ads_config.rb dans votre répertoire personnel, puis ajoutez votre jeton de développeur et définissez use_application_default_credentials sur "true" :

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # 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_DEVELOPER_TOKEN et GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS :

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
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, ne fournissez pas d'identifiants OAuth2 explicites. La bibliothèque détecte et utilise automatiquement les identifiants configurés par l'outil de ligne de commande Google Cloud. Vous devrez toujours spécifier votre jeton de développeur.

# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
  # Developer Token is mandatory for the Google Ads API.
  config.developer_token = "YOUR_DEVELOPER_TOKEN"

  # 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 oauth2_client_id, oauth2_client_secret, or oauth2_refresh_token here.
end

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