Vidéo: Regardez la vidéo "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 des 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 de 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 du groupe d'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 la façon dont les annonces sont déclenchées.
Il existe de nombreux types de critères, tels que des mots clés, des tranches d'âge et des 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 dates et des budgets pour toute 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 postale 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
Dans Google Ads, chaque objet est identifié par son propre ID. Certains de ces identifiants sont uniques au niveau mondial dans tous les comptes Google Ads, tandis que d'autres ne sont uniques que dans un champ d'application restreint.
ID d'objet | Périmètre de l'unicité | Unique à l'échelle mondiale ? |
---|---|---|
ID du budget | Globaux | Oui |
ID de campagne | Globaux | Oui |
ID du groupe d'annonces | Globaux | Oui |
Identifiant d'annonce | Groupe d'annonces | Non, mais la paire (AdGroupId , AdId ) est unique |
ID du critère de groupe d'annonces | Groupe d'annonces | Non, mais la paire (AdGroupId , CriterionId ) est unique |
ID du critère de campagne | Campagne | Non, mais la paire (CampaignId , CriterionId ) est unique |
Extensions d'annonce | Campagne | Non, mais la paire (CampaignId , AdExtensionId ) est unique |
ID du flux | Global | Oui |
ID de l'élément de flux | Globaux | Oui |
ID de l'attribut du flux | Flux | Non |
ID de correspondance de flux | Globaux | Oui |
ID du libellé | Globaux | Oui |
ID UserList | Globaux | Oui |
Ces règles d'identifiant 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 textuelle, une annonce d'hôtel ou une annonce locale. Cette valeur est accessible via le champ AdGroupAd.ad.type
et renvoie une valeur de 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 sous la forme suivante:
customers/customer_id/campaigns/campaign_id
Ainsi, pour une campagne portant l'ID 987654
dans le compte Google Ads ayant le numéro client 1234567
, 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: la modification, la récupération d'objets et de statistiques, et les services de récupération de métadonnées.
Modifier (mutate) 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.
Exemples de services:
CustomerService
pour modifier les clients.CampaignService
pour modifier les campagnesAdGroupService
pour 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 la page Modifier et inspecter des objets.
mutates 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 de la même application ou de différentes applications (par exemple, votre application et une session simultanée d'UI Google Ads).
L'API ne fournit pas de moyen de verrouiller un objet avant la mise à jour. Si deux sources tentent de modifier un objet simultanément, l'API génère une DatabaseError.CONCURRENT_MODIFICATION_ERROR
.
Méthodes mutate synchrones ou asynchrones
Les méthodes mutate de l'API Google Ads sont synchrones. Les appels d'API ne renvoient une réponse qu'après la modification des objets, 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 doivent 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 fin. Une fois qu'une tâche par lot est envoyée, les serveurs d'API Google Ads exécutent les opérations de manière asynchrone, libérant ainsi les processus pour d'autres opérations. Vous pouvez vérifier régulièrement l'état de la tâche.
Pour en savoir plus sur le traitement asynchrone, consultez le guide sur le traitement par lot.
Validation de mutation
La plupart des requêtes mutate peuvent être validées sans exécuter réellement 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 réellement l'opération.
Pour utiliser cette fonctionnalité, définissez le champ booléen validate_only
facultatif 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 dans la réponse indiqueront les points d'échec.
validate_only
est particulièrement utile pour tester les annonces pour des cas courants de non-respect des règles. Les annonces sont automatiquement refusées si elles ne respectent pas nos règles (mots, ponctuation, majuscules ou longueur, par exemple). Une seule annonce indésirable peut
entraîner l'échec d'un lot entier. Le fait de tester une nouvelle annonce dans une demande validate_only
peut révéler de tels cas de non-respect. Reportez-vous à l'exemple de code pour gérer les erreurs de non-respect des règles pour voir comment cela se passe.
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 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 les métadonnées
GoogleAdsFieldService
récupère les métadonnées sur les ressources de l'API Google Ads, telles que 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.