Structure des appels à l'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'avez pas à vous soucier des détails de la requête sous-jacente. Il peut toutefois être utile de savoir ce qu'il en est lorsque vous effectuez des tests et des débogages.

L'API Google Ads est une API gRPC avec des liaisons REST. Il existe deux manières d'effectuer des appels vers l'API.

1. [Preferred] Créez le corps de la requête en tant que tampon de protocole, envoyez-le au serveur à l'aide de HTTP/2, désérialisez la réponse à un tampon de protocole et interprétez les résultats. La plupart de notre documentation décrit l'utilisation de gRPC.

2. [Facultatif] Créez le corps de la requête en tant qu'objet JSON, envoyez-le au serveur à l'aide du protocole HTTP 1.1, désérialisez la réponse en tant qu'objet JSON et interprétez les résultats. Consultez le guide de l'interface REST pour en savoir plus sur l'utilisation de REST.

Remarque : Ce guide décrit la structure et les en-têtes de transport communs aux protocoles gRPC et REST.

Noms de ressources

La plupart des objets de l'API sont identifiés par leurs chaînes de noms de ressources. Ces chaînes servent également d'URL lorsque vous utilisez l'interface REST. Reportez-vous à la section Noms des ressources de l'interface REST pour connaître leur structure.

Point clé : Consultez la documentation sur les ressources pour découvrir toutes les ressources compatibles et leur représentation de chemin (resource_name). Le même format est utilisé pour d'autres services.

ID composites

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

Par exemple, comme l'ID d'une annonce de groupe d'annonces n'est pas unique, nous y ajoutons son ID d'objet parent (groupe d'annonces) pour en créer un unique:

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

En-têtes de requête

Voici les en-têtes HTTP (ou métadonnées grpc) qui accompagnent le corps dans la requête:

Autorisation

Vous devez inclure un jeton d'accès OAuth2 sous la forme Authorization: Bearer YOUR_ACCESS_TOKEN qui identifie un compte administrateur agissant pour le compte d'un client ou d'un annonceur qui gère 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. Au-delà, il doit être actualisé. Notez que nos bibliothèques clientes actualisent automatiquement les jetons arrivés à expiration.

jeton de développeur

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. Exemple de chaîne de jeton de développeur : ABcdeFGH93KL-NOPQ_STUv. Le jeton de développeur doit être inclus sous la forme developer-token : ABcdeFGH93KL-NOPQ_STUv.

ID client client de connexion

Il s'agit du numéro client du client autorisé, sans les traits d'union (-), que vous pouvez utiliser dans la requête. 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.

Terme clé:le client actif correspond au numéro client de la charge utile de la requête. Par exemple, le client opérationnel dans la requête CampaignBudgetService suivante est 1234567890 :

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

Définir login-customer-id revient à choisir un compte dans l'UI Google Ads après vous être connecté ou en cliquant sur l'image de votre profil en haut à droite. Si vous n'incluez pas cet en-tête, il sera défini par défaut sur le client d'exploitation.

Remarque:Vous pouvez récupérer la liste des comptes qui sont directement accessibles à l'aide de vos identifiants OAuth en envoyant une requête CustomerService.ListAccessibleCustomers. login-customer-id n'est pas obligatoire pour ce type de requête et n'a aucun effet sur la liste de clients renvoyée.

Numéro client associé

Cet en-tête n'est utilisé que par les fournisseurs de solution d'analyse d'applications tiers qui importent des conversions dans un compte Google Ads associé.

Considérons le scénario dans lequel les utilisateurs du compte A fournissent un accès en lecture et en modification à ses entités pour le compte B via un ThirdPartyAppAnalyticsLink. Une fois l'association effectuée, un utilisateur du compte B peut effectuer des appels d'API sur le compte A, sous réserve des autorisations fournies par l'association. Dans ce cas, les autorisations d'appel d'API au compte A sont déterminées par l'association tierce au compte B, plutôt que par la relation du compte administrateur utilisée dans les autres appels d'API.

Le fournisseur tiers de solutions d'analyse d'applications effectue un appel d'API comme suit:

• linked-customer-id: compte d'analyse d'applications tiers qui importe les données (compte B).
• customer-id: compte Google Ads dans lequel les données sont importées (compte A).
• En-tête login-customer-id et Authorization: combinaison de valeurs permettant d'identifier un utilisateur ayant accès au compte B.

En-têtes de réponse

Les en-têtes suivants (ou grpc background-metadata) sont renvoyés avec le corps de la réponse. Nous vous recommandons d'enregistrer ces valeurs à des fins de débogage.

id de demande

Le request-id est une chaîne qui identifie de manière unique cette requête.