Structure des appels 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 besoin de connaître les détails de la requête sous-jacente. Toutefois, il peut être utile de connaître la structure des appels d'API 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 vers l'API.

Préféré :

1. Créez le corps de la requête en tant que tampon de protocole.
2. Envoyez-la au serveur à l'aide de HTTP/2.
3. Désérialiser la réponse dans un tampon de protocole.
4. Interprétez les résultats.

La plupart de nos documents décrivent l'utilisation de gRPC.

Facultatif :

1. Créez le corps de la requête en tant qu'objet JSON.
2. Envoyez-la 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 sur l'interface REST.

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

Identifiants de ressource

Les objets de l'API Google Ads sont adressés à l'aide de noms de ressources structurés et d'identifiants composites.

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 lors de l'utilisation de 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 les autres services.

ID composites

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

Par exemple, un AdGroupAd a le modèle de nom de ressource customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Étant donné que son identifiant composite combine l'ID du groupe d'annonces parent (ad_group.id) et l'identifiant de l'annonce sous-jacente (ad_group_ad.ad.id), nous ajoutons l'ID du groupe d'annonces à l'identifiant de l'annonce :

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

Remarque : Il est interdit de partager un AdId entre plusieurs groupes d'annonces. La création d'un AdGroupAd qui fait référence à un AdId existant dans un autre groupe d'annonces échoue avec l'erreur AdGroupAdError.AD_SHARING_NOT_ALLOWED.

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 OAuth 2.0 sous la forme 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 arrivés à expiration.

Si vous rencontrez des erreurs d'autorisation, assurez-vous d'utiliser les bons identifiants 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. Si votre projet Google Cloud n'est approuvé que pour l'accès Test et que vous envoyez une requête ciblant un compte de production, l'API renvoie AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION dans la version 25 et les versions ultérieures (ou AuthorizationError.ACTION_NOT_PERMITTED dans la version 24 et les versions antérieures). Pour en savoir plus sur la gestion des autorisations, consultez Niveaux d'accès Google Ads.

login-customer-id

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

Terme clé : Le client d'exploitation est le numéro client dans la charge utile de la requête. Par exemple, le client d'exploitation dans la requête CampaignBudgetService suivante est 1234567890 :

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

Définir le login-customer-id équivaut à choisir un compte dans l'interface utilisateur de 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, il est défini par défaut sur le client exploitant.

Remarque : Vous pouvez récupérer la liste des comptes directement accessibles avec vos identifiants OAuth en envoyant une requête CustomerService.ListAccessibleCustomers. Le champ login-customer-id n'est pas obligatoire 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 est obligatoire et utilisé par les partenaires (tels que les fournisseurs de solutions 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 dispose de l'association de produits.

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

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

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

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

• Authorization : jeton d'accès OAuth 2.0 pour un utilisateur ayant accès au partenaire.
• login-customer-id : ID client du compte 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 l'association de produits du compte associé au partenaire.

Il existe deux scénarios d'association :

• Si le compte Annonceur est directement associé au compte Partenaire, le compte associé est Annonceur, et linked-customer-id doit être défini sur le numéro client du compte Annonceur.
• Si le compte Annonceur est géré par un compte administrateur associé au compte 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 le compte d'annonceur 1111111111 est directement associé au compte partenaire 2222222222 et que l'appel d'API cible customers/1111111111/... :

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Exemple 2 : Lien administrateur

Si le compte d'annonceur 1111111111 est géré par le compte administrateur 3333333333, que le compte administrateur 3333333333 est associé au compte partenaire 2222222222 et que l'appel d'API cible customers/1111111111/... :

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

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 cette requête de manière unique. Fournissez cette valeur lorsque vous contactez l'assistance pour résoudre les problèmes de requêtes API ayant échoué ou inattendues.