Structure d'API

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.

Modèle de campagne

  • 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:

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.

Précédent
Vue d'ensemble
Suivant
Relations entre entités