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.
Ce guide explique comment configurer la bibliothèque cliente Java pour l'authentification de l'API Google Ads à l'aide des trois flux OAuth 2.0 les plus courants, et détaille les identifiants requis.
Pour une présentation détaillée du modèle d'accès à l'API Google Ads, consultez le guide sur le modèle d'accès à Google Ads.
Identifiants
Pour accéder à l'API Google Ads, vous devez disposer d'identifiants OAuth 2.0 et, dans certains cas, d'un ID client de connexion.
Identifiants OAuth 2.0
Pour vous autoriser en tant qu'utilisateur d'un compte Google ayant accès à des comptes Google Ads, vous devez fournir un ensemble d'identifiants OAuth 2.0. Le type d'identifiants requis varie en fonction du flux OAuth 2.0 utilisé.
La bibliothèque est compatible avec trois flux :
- Flux de compte de service
- Flux d'authentification pour un seul utilisateur
- Flux d'authentification multi-utilisateur
Consultez la présentation d'OAuth pour en savoir plus sur les flux OAuth de l'API Google Ads, puis suivez les instructions correspondant au flux qui répond le mieux à vos besoins pour obtenir les identifiants requis.
Numéro client utilisé pour la connexion
Vous pouvez éventuellement spécifier le numéro client d'un compte administrateur qui permet d'accéder au compte de diffusion. Vous devez spécifier cet ID si vous accédez au compte client via un compte administrateur. Il n'est pas nécessaire de spécifier tous les comptes administrateur sur le chemin d'accès au numéro client, mais uniquement l'ID administrateur de niveau supérieur que vous utilisez pour les autorisations d'accès. Pour en savoir plus, consultez la documentation associée.
Dans la bibliothèque cliente, le numéro client de connexion est spécifié par la clé api.googleads.loginCustomerId dans votre fichier ads.properties.
Configuration
Vous pouvez configurer la bibliothèque cliente avec un fichier ads.properties, des variables d'environnement ou de manière programmatique. Ce guide se concentre sur l'utilisation d'un fichier ads.properties. Pour en savoir plus sur toutes les options, consultez le guide de configuration.
Si vous utilisez un fichier ads.properties, placez-le dans votre répertoire d'accueil : ~/ads.properties.
Workflows OAuth
Il existe trois workflows courants pour utiliser l'API Google Ads.
Flux de 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.
Une fois que vous disposez du fichier JSON de la clé privée, ajoutez les éléments suivants à votre fichier ads.properties :
api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE
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 cibles à ce compte administrateur.
- L'utilisateur exécute un outil de ligne de commande tel que la CLI
gcloudou l'exemple de codeGenerateUserCredentialspour autoriser votre application à gérer tous ses comptes Google Ads en son nom.
Une fois que vous disposez de ces identifiants, ajoutez les éléments suivants à votre fichier ads.properties :
api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
Pour en savoir plus, consultez le guide sur le workflow d'authentification d'un seul utilisateur.
Flux d'authentification multi-utilisateur
Il s'agit du workflow recommandé si votre application permet aux utilisateurs de se connecter et de l'autoriser à gérer leurs comptes Google Ads en leur nom. L'exemple de code GenerateUserCredentials est un outil de 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 ou des applications Web nécessitant l'authentification des utilisateurs.
Pour les applications multi-utilisateurs, stockez l'ID client et le code secret du client OAuth 2.0 de votre application dans ads.properties (ou un autre magasin de configuration), tout en stockant de manière sécurisée le jeton d'actualisation de chaque utilisateur final dans la base de données de votre application et en le transmettant de manière programmatique au moment de l'exécution lors de la compilation de UserCredentials et GoogleAdsClient :
api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
Pour en savoir plus, consultez le guide du workflow d'authentification multi-utilisateur.
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 Java fournit les exemples de code suivants qui illustrent comment gérer ces cas :
- L'exemple de code
GetAccountHierarchymontre comment récupérer la liste de tous les comptes d'un compte administrateur Google Ads. - L'exemple de code
ListAccessibleCustomersmontre 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ètreloginCustomerId.
Identifiants par défaut de l'application
La bibliothèque cliente Java est également compatible avec l'authentification à l'aide des identifiants par défaut de l'application.
Cette approche est particulièrement utile pour le développement local ou pour le développement avec différentes Google APIs, 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 vos identifiants par défaut de l'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, définissez l'option api.googleads.useApplicationDefaultCredentials sur true dans votre fichier ads.properties (ou appelez .enableApplicationDefaultCredentials() sur GoogleAdsClient.newBuilder()). Lorsque vous utilisez les identifiants par défaut de l'application, l'ID client, le code secret du client et le jeton d'actualisation ne doivent pas être définis.