Vidéo: découvrez la discussion sur les services et les ressources de l'atelier 2019
Ce guide présente les principaux composants de l'API Google Ads. La L'API Google Ads se compose de ressources et de services. Une ressource représente d'entité, 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 la clientèle.
Chaque client comporte un ou plusieurs campagnes.
Chaque campagne contient un ou plusieurs groupes d'annonces, utilisés pour regrouper vos annonces en collections logiques.
Une annonce de groupe d'annonces représente une annonce en cours d'exécution. Sauf pour les campagnes pour applications, qui ne peuvent comporter qu'une annonce de groupe d'annonces par annonce groupe d'annonces, chaque groupe d'annonces contient une ou plusieurs annonces.
Vous pouvez joindre un ou plusieurs AdGroupCriterion
ou CampaignCriterion
à un groupe d'annonces ou
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, mots clés, tranches d'âge et zones géographiques, par exemple. Critères définis au niveau de la campagne affecte toutes les autres ressources de la campagne. Vous pouvez également spécifier les budgets et les dates pour l'ensemble de la campagne.
Enfin, vous pouvez joindre des extensions au niveau au niveau du compte, de la campagne ou du groupe d'annonces. Les extensions vous permettent d'offrir des informations complémentaires à vos annonces, telles que votre numéro de téléphone, votre adresse postale ou vos promotions.
Ressources
Les ressources représentent les entités au sein de votre compte Google Ads. Campaign
et AdGroup
en sont deux exemples.
de ressources.
ID des objets
Dans Google Ads, chaque objet est identifié par son propre ID. Certains de ces identifiants sont est unique au niveau mondial dans tous les comptes Google Ads, tandis que d'autres le sont uniquement au sein d’une portée limitée.
ID d'objet | Portée 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 |
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 | Global | Oui |
ID de l'attribut du flux | Flux | Non |
ID de correspondance de flux | Global | Oui |
ID du libellé | Monde | Oui |
ID de liste d'utilisateurs | Monde | Oui |
Ces règles basées sur les identifiants peuvent s'avérer utiles lorsque vous concevez un espace de stockage local pour vos comptes Google Ads d'objets.
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, comme une annonce textuelle,
annonce d'hôtel ou annonce locale. Cette valeur est accessible via la
AdGroupAd.ad.type
et renvoie une valeur du paramètre
AdType
enum.
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, la campagne
les noms de ressources se présentent comme suit:
customers/customer_id/campaigns/campaign_id
Pour une campagne associée à l'ID 987654
dans le compte Google Ads associé au 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: modification, récupération d'objets et de statistiques, et récupération de métadonnées services.
Modifier (mutate) des objets
Ces services modifient les instances d'un type de ressource associé à l'aide d'un mutate
requête. Ils fournissent également une requête get
qui récupère une seule ressource.
ce qui peut être utile pour examiner la structure d'une ressource.
Exemples de services:
CustomerService
pour modifier clients.CampaignService
pour modifier campagnes.AdGroupService
pour modifier des groupes d'annonces
Chaque requête mutate
doit inclure les objets operation
correspondants. Pour
Par exemple, la méthode CampaignService.MutateCampaigns
attend un ou plusieurs
Instances de CampaignOperation
. Voir
Modifier et inspecter des objets pour une
sur les opérations.
Modifications simultanées
Un objet Google Ads ne peut pas être modifié simultanément par plusieurs sources. Ce 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 les threads. Cela inclut la mise à jour de l'objet à partir de plusieurs threads au sein d'une même application ou à partir de différentes applications (par exemple, votre application et un session simultanée dans l'interface utilisateur Google Ads).
L'API ne permet pas de verrouiller un objet avant sa mise à jour. si deux sources
lorsque vous essayez de modifier un objet simultanément, l'API génère une
DatabaseError.CONCURRENT_MODIFICATION_ERROR
Méthodes mutate asynchrones et synchrones
Les méthodes mutate de l'API Google Ads sont synchrones. Les appels d'API ne renvoient une réponse 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 pourrait ont un impact négatif sur l'équilibrage de charge et gaspillent des ressources si les processus doivent attendre que les appels soient terminés.
Une autre approche consiste à muter les objets de manière asynchrone à l'aide de
BatchJobService
, qui effectue des lots de
des opérations sur plusieurs services
sans attendre leur achèvement. Une fois qu'un
par lot est envoyé, les serveurs de l'API Google Ads exécutent les opérations de manière asynchrone.
libérant ainsi des processus
pour effectuer d'autres opérations. Vous pouvez vérifier régulièrement
l'état du job à terminer.
Pour en savoir plus sur le traitement par lot, consultez le guide sur le traitement par lot le traitement asynchrone.
Validation de la mutation
La plupart des requêtes mutate peuvent être validées sans exécuter réellement l'appel. à des données réelles. Vous pouvez tester la requête pour identifier les paramètres manquants et les erreurs 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 demande serait alors entièrement validée
comme si elle était
mais l'exécution finale est ignorée. Si aucune erreur n'est détectée, une valeur
est renvoyée. Si la validation échoue, les messages d'erreur dans la réponse
indiquent les points de défaillance.
validate_only
est particulièrement utile pour tester la conformité des annonces avec les règles les plus courantes
les cas de non-respect. Les annonces qui ne respectent pas les règles suivantes sont automatiquement refusées :
des mots, des signes de ponctuation, des majuscules ou des longueurs spécifiques. Une seule annonce indésirable
peut entraîner l'échec
d'un lot entier. Tester une nouvelle annonce dans un validate_only
peut révéler de tels cas de non-respect. Reportez-vous à l'exemple de code pour la gestion
les erreurs de non-respect des règles
en action.
Obtenir des objets et des statistiques de performances
GoogleAdsService
est l'unité unique et unifiée
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 à laquelle
les attributs de ressources et les métriques de performances à récupérer,
les prédicats à utiliser pour filtrer la requête et les segments à utiliser pour
ventiler 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
des 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 nécessaires à la construction d'une requête pour
GoogleAdsService
Pour plus de commodité,
les informations renvoyées par
GoogleAdsFieldService
est également disponible
dans la documentation de référence sur les champs.