Structure de l'appel d'API

Ce guide décrit la structure commune de tous les appels d'API.

Si vous utilisez une bibliothèque cliente pour interagir avec l'API, vous n'aurez pas besoin de connaître les détails de la requête sous-jacente. Toutefois, certaines connaissances sur la structure des appels d'API peuvent être utiles lors des tests et du débogage.

L'API Google Ads est une API gRPC avec des liaisons REST. Cela signifie qu'il existe deux façons d'effectuer des appels à l'API.

Méthode recommandée :

  1. Créez le corps de la requête en tant que tampon de protocole.

  2. Envoyez-le au serveur à l'aide de HTTP/2.

  3. Désérialisez la réponse dans un tampon de protocole.

  4. Interprétez les résultats.

La plupart de notre documentation décrit l'utilisation de gRPC.

Facultatif :

  1. Créez le corps de la requête en tant qu'objet JSON.

  2. Envoyez-le au serveur à l'aide de HTTP 1.1.

  3. Désérialisez la réponse en tant qu'objet JSON.

  4. Interprétez les résultats.

Pour en savoir plus sur l'utilisation de REST, consultez le guide de l'interface REST.

Noms de ressources

La plupart des objets de l'API sont identifiés par des chaînes de nom de ressource. Ces chaînes servent également d'URL lorsque vous utilisez l'interface REST. Pour connaître leur structure, consultez la section Noms de ressources de l'interface REST.

ID composites

Si l'ID d'un objet n'est pas globalement unique, un ID composite pour cet objet est créé en ajoutant son ID parent et un tilde (~).

Par exemple, étant donné que l'ID d'une annonce dans un groupe d'annonces n'est pas globalement unique, nous ajoutons l'ID de son objet parent (groupe d'annonces) pour créer un ID composite unique :

  • AdGroupId de 123 + ~ + AdGroupAdId de 45678 = ID composite d'annonce dans un groupe d'annonces de 123~45678.

En-têtes de requête

Il s'agit des en-têtes HTTP (ou des métadonnées grpc) qui accompagnent le corps de la requête :

Autorisation

Vous devez inclure un jeton d'accès OAuth2 au format Authorization: Bearer YOUR_ACCESS_TOKEN qui identifie un compte administrateur agissant au nom de un client ou un annonceur gérant directement son propre compte. Vous trouverez des instructions pour récupérer un jeton d'accès dans le guide OAuth2. Un jeton d'accès est valide pendant une heure après son acquisition. Lorsqu'il expire, actualisez-le pour en récupérer un nouveau. Notez que nos bibliothèques clientes actualisent automatiquement les jetons expirés.

Si vous rencontrez des erreurs d'autorisation, assurez-vous d'utiliser les identifiants appropriés et de disposer des autorisations suffisantes. Une erreur USER_PERMISSION_DENIED indique que l'utilisateur authentifié n'a peut-être pas accès au compte client spécifié dans la requête. Pour en savoir plus sur la gestion des autorisations, consultez Niveaux d'accès Google Ads.

developer-token

Un jeton de développeur est une chaîne de 22 caractères qui identifie de manière unique un développeur de l'API Google Ads. Voici un exemple de chaîne de jeton de développeur : ABcdeFGH93KL-NOPQ_STUv. Le jeton de développeur doit être inclus au format developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

Il s'agit du numéro client du client autorisé à utiliser dans la requête, sans tirets (-). Si vous accédez au compte client via un compte administrateur, cet en-tête est obligatoire et doit être défini sur le numéro client du compte administrateur. Si vous n'incluez pas login-customer-id lorsque vous vous authentifiez via un compte administrateur, une erreur AuthorizationError.USER_PERMISSION_DENIED se produit. Pour en savoir plus sur ce type d'erreur , consultez Erreurs courantes. Pour obtenir une explication détaillée de la résolution de l'accès au compte, consultez le guide sur le modèle d'accès OAuth.

https://googleads.googleapis.com/v24/customers/1234567890/campaignBudgets:mutate

Définir login-customer-id revient à 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. Si vous n'incluez pas cet en-tête, la valeur par défaut est le client opérationnel.

linked-customer-id

Cet en-tête est obligatoire et utilisé par les partenaires (tels que les fournisseurs d'analyse d'applications tiers ou les partenaires pour les données) lorsqu'ils agissent sur un compte Google Ads associé. Cet en-tête doit spécifier le numéro client du compte Google Ads qui contient le lien produit.

Prenons l'exemple d'un partenaire qui doit effectuer des appels d'API vers un compte Google Ads en fonction d'un lien produit.

  • Annonceur : compte Google Ads géré ou mis à jour par l'appel d'API. L'ID du compte annonceur est spécifié dans la requête. Dans REST, il s'agit du paramètre de chemin customerId (par exemple, customers/1111111111/...), et dans gRPC, il s'agit du champ customer_id de la requête.
  • Partenaire : compte partenaire (par exemple, un fournisseur d'analyse d'applications tiers ou un partenaire pour les données).
  • Compte associé : compte Google Ads qui a établi un lien produit avec le partenaire, ce qui lui donne accès à l'annonceur.

Un utilisateur ayant accès au partenaire effectue des appels d'API pour agir sur des entités de l'annonceur (par exemple, pour importer des conversions ou gérer des listes d'utilisateurs). Le compte associé peut être l'annonceur lui-même ou un compte administrateur de l'annonceur.

Les en-têtes de requête doivent être définis comme suit :

  • Authorization: jeton OAuth2 pour un utilisateur ayant accès au partenaire.
  • developer-token: jeton de développeur de l'application API, généralement associé au partenaire.
  • login-customer-id: numéro client du partenaire. L'utilisateur authentifié doit avoir accès à ce compte.
  • linked-customer-id: numéro client du compte associé. Cet en-tête indique que l'autorisation de cette requête repose sur le lien produit du compte associé avec le partenaire.

Il existe deux scénarios d'association :

  • Si l'annonceur dispose d'un lien produit direct avec le partenaire, le compte associé est l'annonceur, et linked-customer-id doit être défini sur le numéro client de l'annonceur.
  • Si l'annonceur est géré par un compte administrateur qui dispose d'un lien produit avec le partenaire, le compte associé est le compte administrateur, et linked-customer-id doit être défini sur le numéro client de l'administrateur.

Exemple 1 : Lien direct

Si l'annonceur 1111111111 dispose d'un lien direct avec le partenaire 2222222222 et que l'appel d'API cible customers/1111111111/... :

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Exemple 2 : Lien administrateur

Si l'annonceur 1111111111 est géré par l'administrateur 3333333333, que l'administrateur 3333333333 dispose d'un lien avec le partenaire 2222222222 et que l'appel d'API cible customers/1111111111/... :

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

En-têtes de réponse

Les en-têtes suivants (ou grpc métadonnées de fin) sont renvoyés avec le corps de la réponse. Nous vous recommandons de consigner ces valeurs à des fins de débogage.

request-id

L'élément request-id est une chaîne qui identifie de manière unique cette requête.

Précédent
Métadonnées de ressources