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 s'avérer 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'appeler l'API.

Préféré :

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.

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 leur chaîne 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.

Point clé : 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 les autres services.

ID composites

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

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

• AdGroupId de 123 + ~ + AdGroupAdId de 45678 = ID de l'annonce composite du groupe d'annonces 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 au format Authorization: Bearer YOUR_ACCESS_TOKEN qui identifie un compte administrateur agissant au nom d'un client ou 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 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.

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 de l'ID 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 l'ID client du compte administrateur.

Terme clé : l'utilisateur opérationnel est l'ID client dans le corps de la requête. Par exemple, le client opérationnel dans la requête CampaignBudgetService suivante est 1234567890 :

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

Définir login-customer-id équivaut à choisir un compte dans l'UI Google Ads après s'ê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 operating_customer.

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

linked-customer-id

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

Prenons l'exemple où les utilisateurs du compte A accordent un accès en lecture et en modification à ses entités au compte B via un ThirdPartyAppAnalyticsLink. Une fois l'association établie, un utilisateur du compte B peut effectuer des appels d'API sur le compte A, sous réserve des autorisations accordées par l'association. Dans ce cas, les autorisations d'appel d'API pour le compte A sont déterminées par l'association tierce au compte B, plutôt que par la relation de compte administrateur 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 tierces 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 métadonnées de fin 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

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