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 de la requête sous-jacentes. Toutefois, en savoir un peu plus à leur sujet peut s'avérer utile lors des tests et du débogage.

L'API Google Ads est une API gRPC, des liaisons REST. Cela signifie qu'il existe deux façons d'appeler l'API.

1. [À privilégier] Créez le corps de la requête en tant que tampon de protocole, envoyez-le au serveur en utilisant HTTP/2, désérialise la réponse à un protocole un tampon et interpréter les résultats. La majeure partie de notre documentation décrit l'utilisation 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. Consultez le guide de l'interface REST pour en savoir plus sur l'utilisation REST.

Remarque :Ce guide décrit les en-têtes de structure et 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 les chaînes servent également d'URL lors de l'utilisation de l'interface REST. Voir l'API REST Noms de ressources de l'interface structure.

Important :Consultez la documentation sur les ressources, pour 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 identifiant composite pour cet objet est construite en ajoutant un préfixe à son identifiant parent suivi d'un tilde (~).

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

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

En-têtes de requête

Il s'agit des en-têtes HTTP (ou grpc de métadonnées) 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 un Compte administrateur agissant directement au nom d'un client ou d'un annonceur gérer leur propre compte. Instructions pour récupérer un jeton d'accès consultez le guide OAuth2. Une Le jeton d'accès est valide pendant une heure après son obtention. lorsqu'il lorsque le jeton 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.

developer-token

Un jeton de développeur est une chaîne de 22 caractères qui identifie de façon unique 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 dans 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 traits d'union (-). Si vous accédez au compte du client via un compte administrateur, cet en-tête est obligatoire et doit être défini sur le numéro client du le 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érateur dans la requête CampaignBudgetService suivante est 1234567890 :

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

Définir login-customer-id revient à choisir un compte dans le UI Google Ads après que vous vous êtes connecté ou que vous avez cliqué sur l'image de votre profil en haut de l'écran à droite. Si vous n'incluez pas cet en-tête, le système d'exploitation client.

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

linked-customer-id

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

Prenons l'exemple d'un utilisateur du compte A qui octroie un accès en lecture et en modification. à ses entités pour le compte B par le biais d'un ThirdPartyAppAnalyticsLink Une fois l'association effectuée, un utilisateur du compte B peut effectuer des appels d'API sur le compte A. soumis aux autorisations fournies par le lien. Dans ce cas, l'appel d'API les autorisations accordées au compte A sont déterminées par l'association tierce au compte B. plutôt que 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 à identifier un utilisateur ayant accès au compte B.

En-têtes de réponse

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

request-id

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