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 niveau supérieur 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 de manière logique.
Une annonce de groupe d'annonces représente une annonce que vous diffusez dans un groupe d'annonces. À 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.
Les campagnes Performance Max utilisent une structure différente des autres types de campagnes : au lieu de groupes d'annonces et d'annonces de groupes d'annonces, une campagne Performance Max contient des groupes de composants. Vous associez des assets de création à un groupe de composants à l'aide de AssetGroupAsset et vous associez des signaux d'audience ou de thème de recherche à l'aide de AssetGroupSignal.
Vous pouvez associer une ou plusieurs ressources AdGroupCriterion ou CampaignCriterion à un groupe d'annonces ou à une campagne. Il s'agit de critères qui définissent la façon dont les annonces sont déclenchées.
Il existe de nombreux types de critères, tels que 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, ainsi que des dates et heures de début et de fin pour les campagnes ou pour des annonces individuelles à l'aide de AdGroupAd.start_date_time et AdGroupAd.end_date_time.
Enfin, vous pouvez associer des composants au niveau du compte, de la campagne, du groupe d'annonces ou du groupe de composants. Les composants vous permettent d'ajouter des informations supplémentaires à vos annonces, comme des numéros de téléphone, des adresses postales ou des promotions. Consultez Présentation des composants.
Ressources
Les ressources représentent les entités de votre compte Google Ads.
Campaign et AdGroup sont deux exemples de ressources.
ID d'objets
Chaque objet dans Google Ads est identifié par son propre ID. Certains de ces ID sont uniques au niveau mondial pour tous les comptes Google Ads, tandis que d'autres ne sont uniques que dans un champ d'application limité.
| ID d'objet | Périmètre de l'unicité | Unique au niveau global ? |
|---|---|---|
| ID du budget | Monde | Oui |
| ID de la campagne | Global | Oui |
| ID du groupe d'annonces | Global | Oui |
| Identifiant de l'annonce | Ad group | Non, mais la paire (AdGroupId, AdId) est unique au niveau mondial. Il est interdit de partager un AdId entre plusieurs groupes d'annonces. |
| ID du critère de groupe d'annonces | Ad group | Non, mais la paire (AdGroupId, CriterionId) est unique au monde |
| ID du critère de campagne | Campagne | Non, mais la paire (CampaignId, CriterionId) est unique au monde |
| ID du libellé | Client | Non, mais la paire (CustomerId, LabelId) est unique au monde |
| ID de liste d'utilisateurs | Monde | Oui |
| ID d'élément | Monde | Oui |
Ces règles d'ID peuvent être utiles lors de la conception d'un espace de 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 responsive sur le Réseau de Recherche, une annonce d'hôtel ou une annonce Demand Gen. Cette valeur est accessible via le champ AdGroupAd.ad.type et renvoie une valeur dans l'énumération AdType. Notez que la mutabilité peut varier selon la version (par exemple, VideoResponsiveAdInfo sur Ad est modifiable dans la version 24 et les versions ultérieures).
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 sous la forme suivante :
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 serait :
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, les services de récupération d'objets et de statistiques, et les services de récupération de métadonnées.
Modifier (muter) des objets
Les services spécifiques aux ressources modifient les instances d'un type de ressource associé à l'aide d'une requête mutate. Vous pouvez également utiliser GoogleAdsService.Mutate pour effectuer des mutations atomiques sur plusieurs types de ressources dans une même requête (par exemple, créer un budget de campagne, une campagne et un groupe d'annonces en même temps).
Exemples de services spécifiques aux ressources :
CustomerServicepour modifier des clients.CampaignServicepour modifier des campagnes.AdGroupServicepour modifier des 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 des objets.
Modifications 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 d'applications différentes (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.
Modifications 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'une fois les objets modifiés, ce qui vous oblige à attendre une réponse à 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 contraints 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 qu'ils soient terminés. Une fois qu'un job par lot est envoyé, les serveurs de l'API Google Ads exécutent les opérations de manière asynchrone, ce qui libère les processus pour effectuer d'autres opérations. Vous pouvez vérifier régulièrement l'état du job pour voir s'il est terminé.
Pour en savoir plus sur le traitement asynchrone, consultez le guide sur le traitement par lot.
Validation de la modification
La plupart des requêtes de modification peuvent être validées sans exécuter l'appel sur des données réelles. Vous pouvez tester la requête pour détecter les paramètres manquants et les valeurs de champ incorrectes sans exécuter 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 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, la réponse est renvoyée sans aucun résultat modifié (results est vide). Si la validation échoue, la requête échoue avec une erreur RPC GoogleAdsFailure par défaut (partial_failure = false) ou renvoie une réponse normale avec des erreurs spécifiques à l'opération dans partial_failure_error lorsque partial_failure = true.
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 des mots, une ponctuation, des majuscules ou une longueur spécifiques. Une seule annonce indésirable peut entraîner l'échec de l'ensemble du lot. Tester une nouvelle annonce dans une requête validate_only peut révéler de telles infractions. Pour voir comment cela fonctionne, consultez l'exemple de code pour gérer les erreurs de non-respect des règles.
Obtenir des objets et des statistiques de performances
GoogleAdsService est le service unique et unifié permettant de récupérer des objets et des statistiques de 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 ventiler davantage les statistiques de performances. Pour en savoir plus sur le format des requêtes, consultez le guide sur le langage de requête Google Ads.
Récupérer des métadonnées
GoogleAdsFieldService récupère les métadonnées des ressources de l'API Google Ads, telles que les attributs disponibles pour une ressource et son type de données. Pour en savoir plus sur l'interrogation de ce service, consultez le guide sur les métadonnées de ressources.
Ce service fournit les informations nécessaires à la construction d'une requête vers GoogleAdsService. Pour plus de commodité, les informations renvoyées par GoogleAdsFieldService sont également disponibles dans la documentation de référence sur les champs.