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'avez pas à vous soucier des détails sous-jacents de la requête. Cependant, il peut être utile d'en connaître un peu plus 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'appeler l'API.

1. [À privilégier] Créer le corps de la requête en tant que tampon de protocole, l'envoyer au serveur via HTTP/2, désérialiser la réponse dans un tampon de protocole et interpréter les résultats. La majeure partie 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 de HTTP 1.1, désérialisez la réponse en tant qu'objet JSON et interprétez les résultats. Reportez-vous au guide sur 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 nom de ressource. Ces chaînes servent également d'URL lorsque vous utilisez l'interface REST. Consultez la section Noms de ressources de l'interface REST pour connaître leur structure.

Important :Consultez la documentation sur les ressources pour connaître toutes les ressources compatibles et leur représentation de chemin d'accès (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 pour cet objet est créé en ajoutant un préfixe à son ID parent suivi d'un tilde (~).

Par exemple, comme un ID d'annonce d'un groupe d'annonces n'est pas unique, nous lui ajoutons son ID d'objet parent (groupe d'annonces) afin de créer un ID composite unique:

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

En-têtes de requête

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

Autorisation

Vous devez inclure un jeton d'accès OAuth2 sous la forme Authorization: Bearer YOUR_ACCESS_TOKEN qui identifie soit un compte administrateur agissant pour le compte d'un client, soit un annonceur gérant directement son propre compte. Pour savoir comment récupérer un jeton d'accès, consultez le guide OAuth2. Un jeton d'accès est valide pendant une heure après son obtention. Lorsqu'il expire, actualisez le jeton d'accès pour en récupérer un nouveau. Notez que nos bibliothèques clientes actualisent automatiquement les jetons expirés.

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 API Google Ads. Voici un exemple de chaîne de jeton de développeur : ABcdeFGH93KL-NOPQ_STUv. Le jeton de développeur doit respecter le 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 les traits d'union (-). Si votre accès au compte client s'effectue 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 opérationnel correspond au numéro client figurant dans 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/v17/customers/1234567890/campaignBudgets:mutate

Définir login-customer-id revient à sélectionner un compte dans l'interface utilisateur Google Ads après vous être connecté ou cliqué sur votre image de profil en haut à droite. Si vous n'incluez pas cet en-tête, le client opérationnel est utilisé par défaut.

Remarque :Vous pouvez récupérer la liste des comptes accessibles directement avec vos identifiants OAuth en envoyant une requête CustomerService.ListAccessibleCustomers. L'login-customer-id n'est pas obligatoire pour ce type de requête et n'a aucune incidence sur la liste des clients renvoyés.

ID-client associé

Cet en-tête 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é.

Prenons le scénario où les utilisateurs du compte A fournissent un accès en lecture et en modification à ses entités au 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 sur le compte A sont déterminées par le lien tiers vers le compte B, plutôt que par la relation administrateur-compte utilisée dans d'autres appels d'API.

Le fournisseur de solutions d'analyse d'applications tiers 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 les métadonnées finales grpc) sont renvoyés avec le corps de la réponse. Nous vous recommandons de consigner ces valeurs à des fins de débogage.

request-id

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