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. 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.
[Préféré] Créer le corps de la requête en tant que tampon de protocole, l'envoyer au serveur à l'aide de HTTP/2, désérialiser la réponse à un tampon de protocole et interpréter les résultats. La majeure partie de notre documentation décrit l'utilisation de gRPC.
[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. Pour en savoir plus sur l'utilisation de REST, consultez le guide de l'interface REST.
Noms de ressources
Dans l'API, la plupart des objets sont identifiés par les chaînes de nom de ressource associées. Ces chaînes servent également d'URL lorsque vous utilisez l'interface REST. Consultez la section Noms des ressources de l'interface REST pour connaître leur structure.
ID composites
Si l'ID d'un objet n'est pas unique, un ID composite pour cet objet est construit en ajoutant son ID parent et un tilde (~).
Par exemple, comme un identifiant d'annonce de groupe d'annonces n'est pas unique au niveau mondial, nous y ajoutons son ID d'objet parent (groupe d'annonces) pour créer un ID composite unique:
AdGroupId
de123
+~
+AdGroupAdId
de45678
= ID d'annonce du groupe d'annonces composite de123~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 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.
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
.
login-customer-id
Il s'agit du numéro client du client autorisé à utiliser dans la requête, sans tirets (-
). Si vous avez accès 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.
https://googleads.googleapis.com/v16/customers/1234567890/campaignBudgets:mutate
Définir login-customer-id
revient à choisir un compte dans l'interface utilisateur Google Ads après vous être connecté ou après 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 d'exploitation.
numéro-client-associé
Cet en-tête n'est utilisé que par les fournisseurs de solutions d'analyse d'applications tiers lors de l'importation de conversions dans un compte Google Ads associé.
Imaginez le scénario dans lequel 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 pour le compte A
sont déterminées par l'association tierce au compte B
, plutôt que par la relation de compte administrateur à un 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 de solution d'analyse d'applications tierce qui importe les données (compteB
).customer-id
: compte Google Ads dans lequel les données sont importées (compteA
).- En-tête
login-customer-id
etAuthorization
: combinaison de valeurs permettant d'identifier un utilisateur ayant accès au compteB
.
En-têtes de réponse
Les en-têtes suivants (ou grpc bottom-metadata) 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.