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 campaigns.
Chaque campagne contient un ou plusieurs groupes d'annonces, qui permettent de regrouper vos annonces dans des collections logiques.
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 de groupe d'annonces par groupe d'annonces, chaque groupe d'annonces contient une ou plusieurs annonces de groupe d'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 groupe d'annonces, une campagne Performance Max contient des groupes de composants. Vous
associez des composants de création à un groupe de composants à l'aide de
AssetGroupAsset et vous ajoutez 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. Elles représentent des critères qui définissent le déclenchement des annonces.
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 de fournir des informations supplémentaires à vos annonces, comme des numéros de téléphone, des adresses postales ou des promotions. Consultez la 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'objet
Chaque objet de Google Ads est identifié par son propre ID. Certains de ces ID sont uniques au niveau mondial dans tous les comptes Google Ads, tandis que d'autres ne le sont que dans une portée limitée.
| ID de l'objet | Périmètre de l'unicité | Unique au niveau global ? |
|---|---|---|
| ID du budget | Monde | Oui |
| ID de 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 niveau mondial. |
| ID du critère de campagne | Campagne | Non, mais la paire (CampaignId, CriterionId) est unique au niveau mondial. |
| ID du libellé | Client | Non, mais la paire (CustomerId, LabelId) est unique au niveau mondial. |
| ID de liste utilisateur | Monde | Oui |
| ID d'élément | Monde | Oui |
Ces règles d'ID peuvent être utiles lors de la conception d'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 responsive sur le Réseau de Recherche, une annonce d'hôtel ou une annonce Demand Gen. Vous pouvez accéder à cette valeur
via le AdGroupAd.ad.type champ, qui renvoie une
valeur dans l'AdType énumération. Notez que
la mutabilité peut varier selon la version (par exemple, VideoResponsiveAdInfo sur Ad est
mutable dans la version 24 et ultérieure).
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 serait 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 : modification, récupération d'objets et de statistiques, et 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 seule requête (par exemple, créer un
budget de campagne, une campagne et un groupe d'annonces en même temps).
Voici quelques exemples de services spécifiques aux ressources :
CustomerServicepour modifier les clients.CampaignServicepour modifier les campagnes.AdGroupServicepour 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 la section
Modifier 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 mutez 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'interface utilisateur Google Ads).
L'API ne permet pas de verrouiller un objet avant de le mettre à jour. Si deux sources
tentent de muter 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'une fois les objets muté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 obligés d'attendre la fin des appels.
Une autre approche consiste à muter les objets de manière asynchrone à l'aide de
BatchJobService, qui effectue des lots d'
opérations sur plusieurs services sans attendre leur fin. 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 permet aux processus d'effectuer d'autres opérations. Vous pouvez vérifier régulièrement l'état du traitement pour savoir quand il est terminé.
Pour en savoir plus sur le traitement asynchrone, consultez le guide sur le traitement par lot.
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 vérifier si des paramètres sont manquants et si les valeurs des champs sont 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 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 résultat muté (results est vide). Si la validation échoue, la
requête échoue avec une GoogleAdsFailure RPC
erreur 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 d'infraction au règlement. Les annonces sont automatiquement refusées si elles enfreignent le règlement, par exemple si elles contiennent des mots, une ponctuation, une mise en majuscules ou une longueur spécifiques. Une seule annonce non conforme peut entraîner l'échec d'un lot entier. Le test d'une nouvelle annonce dans une requête validate_only peut révéler de telles infractions. Pour voir
cela en action, consultez l'exemple de code pour gérer
les erreurs de non-respect des règles.
Obtenir des objets et des statistiques sur les performances
GoogleAdsService est le service unique et unifié permettant de récupérer des objets et des statistiques sur les performances.
Toutes les Search et
SearchStream requêtes 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 sur les 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 des ressources.
Ce service fournit les informations nécessaires à la création 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.