Structure d'API

Vidéo : Découvrez la présentation sur les services et ressources de l'atelier 2019

Ce guide présente les principaux composants de l'API Google Ads. L'API Google Ads se compose de ressources et de services. Une ressource représente une entité Google Ads, tandis que les services récupèrent et manipulent les entités Google Ads.

Hiérarchie des objets

Un compte Google Ads peut être considéré comme une hiérarchie d'objets.

• La ressource de premier niveau d'un compte est le client.

• Chaque client contient une ou plusieurs campagnes actives.

• Chaque campagne contient un ou plusieurs groupes d'annonces, qui permettent de regrouper vos annonces dans des collections logiques.

• Une annonce au niveau du groupe d'annonces représente une annonce que vous diffusez. À l'exception des campagnes pour applications, qui ne peuvent comporter qu'une seule annonce par groupe d'annonces, chaque groupe d'annonces contient une ou plusieurs annonces.

Vous pouvez associer un ou plusieurs AdGroupCriterion ou CampaignCriterion à un groupe d'annonces ou à une campagne. Il s'agit de critères qui définissent le déclenchement des annonces.

Il existe de nombreux types de critères, comme les mots clés, les tranches d'âge et les zones géographiques. Les critères définis au niveau de la campagne affectent toutes les autres ressources de la campagne. Vous pouvez également spécifier des budgets et des dates pour l'ensemble de la campagne.

Enfin, vous pouvez associer des extensions au niveau du compte, de la campagne ou du groupe d'annonces. Les extensions vous permettent de fournir des informations supplémentaires dans vos annonces, comme un numéro de téléphone, une adresse ou des promotions.

Ressources

Les ressources représentent les entités de votre compte Google Ads. Campaign et AdGroup sont deux exemples de ressources.

ID des objets

Chaque objet dans Google Ads est identifié par son propre ID. Certains de ces ID sont uniques à l'échelle mondiale dans tous les comptes Google Ads, tandis que d'autres ne le sont que dans un champ d'application limité.

ID d'objet	Champ d'application de l'unicité	Unique au niveau mondial ?
ID du budget	Monde	Oui
ID de la campagne	Global	Oui
ID du groupe d'annonces	Global	Oui
ID de l'annonce	Groupe d'annonces	Non, mais la paire (AdGroupId, AdId) est unique au niveau mondial
ID du critère de groupe d'annonces	Groupe d'annonces	Non, mais la paire (AdGroupId, CriterionId) est unique au niveau mondial
ID du critère de campagne	Campagne	Non, mais la paire (CampaignId, CriterionId) est unique au niveau mondial
Extensions d'annonce	Campagne	Non, mais la paire (CampaignId, AdExtensionId) est unique au niveau mondial
ID du libellé	Monde	Oui
ID de la liste d'utilisateurs	Monde	Oui
ID d'élément	Monde	Oui

Ces règles d'ID peuvent être utiles lorsque vous concevez un stockage local pour vos objets Google Ads.

Certains objets peuvent être utilisés pour plusieurs types d'entités. Dans ce cas, l'objet contient un champ type qui décrit son contenu. Par exemple, AdGroupAd peut faire référence à un objet tel qu'une annonce textuelle, une annonce d'hôtel ou une annonce locale. Cette valeur est accessible via le champ AdGroupAd.ad.type et renvoie une valeur dans l'énumération AdType.

Noms de ressources

Chaque ressource est identifiée de manière unique par une chaîne resource_name qui concatène la ressource et ses parents dans un chemin d'accès. Par exemple, les noms de ressources de campagne se présentent comme suit :

customers/customer_id/campaigns/campaign_id

Ainsi, pour une campagne dont l'ID est 987654 dans le compte Google Ads dont le numéro client est 1234567, le resource_name sera le suivant :

customers/1234567/campaigns/987654

Services

Les services vous permettent de récupérer et de modifier vos entités Google Ads. Il existe trois types de services : les services de modification, de récupération d'objets et de statistiques, et de récupération de métadonnées.

Modifier (muter) des objets

Ces services modifient les instances d'un type de ressource associé à l'aide d'une requête mutate. Ils fournissent également une requête get qui récupère une seule instance de ressource, ce qui peut être utile pour examiner la structure d'une ressource.

Important : Les requêtes get sont limitées à 1 000 par jour. Dans la plupart des cas d'utilisation réels, vous devez plutôt demander des rapports à l'aide de GoogleAdsService.

Exemples de services :

• CustomerService pour modifier les clients.

• CampaignService pour modifier les campagnes.

• AdGroupService pour modifier les groupes d'annonces.

Chaque requête mutate doit inclure les objets operation correspondants. Par exemple, la méthode CampaignService.MutateCampaigns attend une ou plusieurs instances de CampaignOperation. Pour en savoir plus sur les opérations, consultez Modifier et inspecter des objets.

Mutations simultanées

Un objet Google Ads ne peut pas être modifié simultanément par plusieurs sources. Cela peut entraîner des erreurs si plusieurs utilisateurs mettent à jour le même objet avec votre application ou si vous modifiez des objets Google Ads en parallèle à l'aide de plusieurs threads. Cela inclut la mise à jour de l'objet à partir de plusieurs threads dans la même application ou à partir de différentes applications (par exemple, votre application et une session simultanée de l'UI Google Ads).

L'API ne permet pas de verrouiller un objet avant de le mettre à jour. Si deux sources tentent de modifier simultanément un objet, l'API génère une erreur DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Mutations asynchrones et synchrones

Les méthodes de mutation de l'API Google Ads sont synchrones. Les appels d'API ne renvoient une réponse qu'après la mutation des objets, ce qui vous oblige à attendre une réponse pour chaque requête. Bien que cette approche soit relativement simple à coder, elle peut avoir un impact négatif sur l'équilibrage de charge et gaspiller des ressources si les processus sont forcés d'attendre la fin des appels.

Une autre approche consiste à modifier les objets de manière asynchrone à l'aide de BatchJobService, qui effectue des lots d'opérations sur plusieurs services sans attendre leur achèvement. Une fois un job par lot envoyé, les serveurs de l'API Google Ads exécutent les opérations de manière asynchrone, ce qui permet aux processus d'effectuer d'autres opérations. Vous pouvez vérifier régulièrement l'état du job pour savoir s'il est terminé.

Pour en savoir plus sur le traitement asynchrone, consultez le guide sur le traitement par lots.

Validation des mutations

La plupart des requêtes de mutation peuvent être validées sans exécuter réellement l'appel sur des données réelles. Vous pouvez tester la requête pour les paramètres manquants et les valeurs de champ incorrectes sans exécuter réellement l'opération.

Pour utiliser cette fonctionnalité, définissez le champ booléen facultatif validate_only de la requête sur true. La requête est ensuite entièrement validée comme si elle allait être exécutée, mais l'exécution finale est ignorée. Si aucune erreur n'est détectée, une réponse vide est renvoyée. Si la validation échoue, les messages d'erreur de la réponse indiquent les points d'échec.

validate_only est particulièrement utile pour tester les annonces afin de détecter les cas courants de non-respect des règles. Les annonces sont automatiquement refusées si elles ne respectent pas les règles (par exemple, si elles contiennent certains mots, une ponctuation, une mise en majuscules ou une longueur spécifiques). Une seule annonce non conforme peut entraîner l'échec de l'ensemble d'un lot. Tester une nouvelle annonce dans une validate_onlydemande peut révéler de telles infractions. Pour voir comment cela fonctionne, consultez l'exemple de code pour la gestion des erreurs de non-respect des règles.

Obtenir des objets et des statistiques de performances

GoogleAdsService est le seul service unifié permettant de récupérer des objets et des statistiques sur les performances.

Toutes les requêtes Search et SearchStream pour GoogleAdsService nécessitent une requête qui spécifie la ressource à interroger, les attributs de ressource et les métriques de performances à récupérer, les prédicats à utiliser pour filtrer la requête et les segments à utiliser pour affiner les statistiques de performances. Pour en savoir plus sur le format des requêtes, consultez le guide du langage de requête Google Ads.

Récupérer des métadonnées

GoogleAdsFieldService récupère les métadonnées sur les ressources de l'API Google Ads, comme les attributs disponibles pour une ressource et son type de données.

Ce service fournit les informations nécessaires à la construction d'une requête pour GoogleAdsService. Pour plus de commodité, les informations renvoyées par GoogleAdsFieldService sont également disponibles dans la documentation de référence sur les champs.