Vidéo: présentation de l'atelier 2019 sur les services et ressources
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 compte contient une ou plusieurs campagnes actives.
Chaque
Campaigncontient un ou plusieurs groupes d'annonces permettant de regrouper vos annonces dans des collections logiques.Chaque
AdGroupcontient une ou plusieurs annonces de groupe d'annonces. UnAdGroupAdreprésente une annonce que vous diffusez.
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 mode de déclenchement des annonces.
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 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 d'ajouter des informations supplémentaires à 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 d'objet
Dans Google Ads, chaque objet 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 sont uniques dans un champ d'application restreint.
| ID d'objet | Portée de l'unicité | Unique au niveau mondial ? |
|---|---|---|
| ID du budget | Mondial | Oui |
| ID de campagne | Mondial | Oui |
| ID du groupe d'annonces | Mondial | Oui |
| Identifiant d'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 flux | Global | Oui |
| ID de l'élément de flux | Mondial | Oui |
| ID de l'attribut du flux | Flux | Non |
| ID de correspondance de flux | Mondial | Oui |
| ID du libellé | Mondial | Oui |
| ID UserList | Mondial | Oui |
Ces règles d'identification peuvent être utiles lors de la conception du 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 à une annonce textuelle, une annonce d'hôtel, une annonce locale, etc. 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, ce qui concaténe la ressource et ses parents dans un chemin. Par exemple, les noms de ressources de la 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 avec le numéro client 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: 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 instance de ressource unique, ce qui peut être utile pour examiner la structure d'une ressource.
Exemples de services:
CustomerServicepour modifier des clientsCampaignServicepour 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 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 mutationz 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 de différentes applications (par exemple, votre application et une session Google Ads simultanée).
L'API ne permet pas de verrouiller un objet avant la mise à jour. Si deux sources tentent de muter simultanément un objet, l'API génère une erreur DatabaseError.CONCURRENT_MODIFICATION_ERROR.
Méthodes mutate synchrones et asynchrones
Les méthodes mutate de l'API Google Ads sont synchrones. Les appels d'API renvoient une réponse uniquement après la mutation des objets, ce qui vous oblige à attendre une réponse à chaque requête. Bien que cette approche soit relativement simple, 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 à 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'une tâche par lot a été envoyée, les serveurs de l'API Google Ads exécutent les opérations de manière asynchrone, libérant ainsi des processus pour d'autres opérations. Vous pouvez vérifier régulièrement l'état de la tâche.
Consultez le guide sur le traitement par lot pour en savoir plus sur le traitement asynchrone.
Validation de mutation
La plupart des requêtes mutate peuvent être validées sans exécuter l'appel sur des données réelles. Vous pouvez tester la requête pour rechercher des paramètres manquants et des 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 serait 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 trouvée, une réponse vide est renvoyée. Si la validation échoue, les messages d'erreur dans la réponse indiquent les points d'échec.
validate_only est particulièrement utile pour tester les annonces en cas de non-respect des règles. Les annonces sont automatiquement refusées si elles ne respectent pas des règles telles que des mots, des signes de ponctuation, des majuscules ou une longueur spécifiques. Une seule annonce indésirable peut entraîner l'échec d'un lot entier. Tester une nouvelle annonce dans une requête validate_only peut révéler de tels cas de non-respect. Reportez-vous à l'exemple de code permettant de gérer les erreurs de non-respect des règles pour voir comment cela fonctionne.
Obtenir des statistiques sur les objets et les 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 du langage de requête Google Ads.
Récupérer les métadonnées
GoogleAdsFieldService récupère les métadonnées sur les ressources dans l'API Google Ads, telles que les attributs disponibles pour une ressource et son type de données.
Ce service fournit les informations dont vous avez besoin pour créer une requête destinée à GoogleAdsService. Pour plus de commodité, les informations renvoyées par GoogleAdsFieldService sont également disponibles dans la documentation de référence sur les champs.