Autorisation et en-têtes HTTP

Remarque : Si vous débutez avec l'API Google Ads, nous vous recommandons de lire d'abord le guide Premiers pas, qui explique comment configurer votre compte et effectuer votre premier appel d'API. Veillez à suivre l'onglet curl.

Vous avez besoin d'identifiants OAuth 2.0 et d'un jeton de développeur lorsque vous appelez l'API Google Ads. Si vous effectuez des appels d'API avec un compte administrateur Google Ads, vous devez également spécifier un en-tête login-customer-id pour chaque requête. Cette page explique comment définir ces valeurs et décrit plusieurs en-têtes HTTP supplémentaires spécifiques à l'API qui sont envoyés et reçus lorsque vous utilisez l'interface REST.

Identifiants OAuth 2.0

L'API Google Ads utilise OAuth 2.0 pour autoriser les requêtes d'API. Le flux d'authentification des utilisateurs OAuth 2.0 et le flux de compte de service sont tous deux compatibles. Pour en savoir plus, consultez la section OAuth 2.0 dans l'API Google Ads.

Si vous débutez avec les API Google, vous pouvez utiliser gcloud CLI ou la plate-forme OAuth 2.0 Playground pour tester les identifiants OAuth 2.0 et l'API Google Ads avant d'écrire le code de votre application.

Nous vous recommandons d'utiliser l'une des bibliothèques OAuth 2.0 disponibles sur https://oauth.net/code/ pour implémenter les workflows d'autorisation OAuth 2.0. Toutefois, nous avons listé les instructions curl au cas où vous devriez les implémenter vous-même.

Comptes de service

Suivez les étapes pour configurer un projet Google Cloud pour l'API Google Ads. Notez l'adresse e-mail du compte de service et la clé du compte de service. Ensuite, suivez les instructions générales du guide Comptes de service pour configurer le compte de service afin d'accéder à votre compte Google Ads.

Authentification des utilisateurs

Suivez les étapes pour configurer un projet de console Google Cloud pour l' API Google Ads. Notez l'ID client et le code secret du client. Ensuite, suivez les instructions du flux d'application de bureau ou les instructions du flux d'application Web pour générer un jeton d'actualisation et un jeton d'accès. Le scope à utiliser pour accéder à l'API Google Ads est https://www.googleapis.com/auth/adwords.

Générer de nouveaux jetons d'accès

Comptes de service

Lorsque vous disposez de l'adresse e-mail du compte de service et de la clé du compte de service, suivez le guide Utiliser OAuth 2.0 pour les applications de serveur à serveur afin de générer un ensemble de revendications JWT, qui peut ensuite être échangé pour obtenir un jeton d'accès OAuth 2.0. Veillez à sélectionner l'onglet HTTP/REST lorsque vous suivez le guide. Le scope OAuth 2.0 à utiliser pour accéder à l'API Google Ads est https://www.googleapis.com/auth/adwords. De plus, vous pouvez ignorer le paramètre sub lorsque vous créez l'ensemble de revendications JWT, car les étapes de configuration accordent au compte de service un accès direct au compte Google Ads, ce qui évite d'avoir à se faire passer pour un utilisateur Google Ads.

Vous utilisez ensuite le jeton d'accès dans l'en-tête HTTP Authorization de chaque appel d'API à l'API Google Ads :

GET /v24/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

Authentification des utilisateurs

Une fois que vous disposez d'un ID client, d'un code secret du client et d'un jeton d'actualisation OAuth 2.0, vous pouvez générer un jeton d'accès à utiliser dans les appels d'API avec l' curl outil de ligne de commande :

Remarque : La version v3 dans l'URL du point de terminaison OAuth n'est pas liée à la version de l'API Google Ads et ne doit pas changer lors de la migration vers des versions plus récentes de l'API Google Ads.

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://www.googleapis.com/oauth2/v3/token

Vous utilisez ensuite le jeton d'accès renvoyé par la requête curl dans l'en-tête HTTP Authorization de chaque appel d'API à l'API Google Ads :

GET /v24/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

En-têtes de requête

Les sections suivantes décrivent les en-têtes HTTP requis ou utilisés lors de l'envoi de requêtes à l'API Google Ads.

Jeton de développeur

L'API Google Ads nécessite également un jeton de développeur pour effectuer des appels à l'API. Si vous disposez déjà d'un jeton de développeur, vous pouvez le trouver en accédant à https://ads.google.com/aw/apicenter. Connectez-vous à votre compte administrateur Google Ads si vous y êtes invité. Si vous n'en avez pas, suivez les instructions pour vous inscrire et obtenir un jeton de développeur.

Vous devez inclure la valeur de votre jeton de développeur dans l'en-tête HTTP developer-token de chaque appel d'API à l'API Google Ads :

GET /v24/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

Numéro client utilisé pour la connexion

Pour les appels d'API Google Ads effectués par un administrateur vers un compte client (c'est-à-dire lorsque vous vous connectez en tant qu'administrateur pour effectuer des appels d'API vers l'un de ses comptes clients), vous devez également fournir l'en-tête HTTP login-customer-id. Cette valeur représente le numéro client Google Ads de l'administrateur qui effectue l'appel d'API.

L'inclusion de cet en-tête équivaut à choisir un compte dans l'interface utilisateur Google Ads après vous être connecté ou avoir cliqué sur votre image de profil en haut à droite de la page. Lorsque vous spécifiez le numéro client, veillez à supprimer les tirets (—). Par exemple : 1234567890 et non 123-456-7890. Pour en savoir plus sur le numéro client utilisé pour la connexion, consultez le guide Modèle d'accès Google Ads.

GET /v24/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID

Point important : Si vous ne vous authentifiez pas en tant que compte administrateur (en d'autres termes, si vos identifiants OAuth 2.0 concernent directement un utilisateur du compte client Google Ads cible), vous n'avez pas besoin de fournir d'en-tête login-customer-id

.

Numéro client associé

L'en-tête "Numéro client associé" n'est utilisé que par les [fournisseurs de solutions d'analyse d'applications tiers lorsque vous importez des conversions dans un compte Google Ads associé. Pour en savoir plus, consultez le guide Structure des appels d'API.

...
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
linked-customer-id: LINKED_CUSTOMER_ID

En-têtes de réponse

Les en-têtes suivants sont renvoyés dans les réponses HTTP de l'API.

Identifiant de la demande

request-id est une chaîne qui identifie de manière unique la requête d'API. Lors du débogage ou de la résolution de problèmes liés à des appels d'API spécifiques, request-id est un identifiant important à avoir sous la main lorsque vous contactez l'assistance Google pour les développeurs.

Conseil : Pour afficher les en-têtes de réponse, y compris google-ads-request-id, lorsque vous utilisez curl, ajoutez l'option -i ou --include à votre commande.

request-id: 2a5Cj89VV7CNhya1DZjjrC