Comme indiqué dans le guide de structure de l'API, chaque ressource de premier niveau de l'API Google Ads dispose d'un service correspondant spécifique au type de ressource, compatible avec:
- Modifier les instances de la ressource
- Récupérer une seule instance de la ressource pour inspection
Dans ce guide, nous utilisons CampaignService pour démontrer la modification et l'inspection des objets Campaign, mais les mêmes concepts s'appliquent à tous les autres services spécifiques à un type de ressource.
Modifier des objets
Chaque service propre à un type de ressource possède une méthode mutate qui accepte une demande de mutation. Cette requête comprend les éléments suivants:
- Une chaîne (
customerId) - Un ensemble d'opérations
- Paramètre de type de contenu de la réponse qui détermine si la ressource modifiable ou uniquement le nom de la ressource doit être renvoyée après la mutation.
Par exemple, la méthode MutateCampaigns de CampaignService accepte un MutateCampaignsRequest constitué des éléments suivants:
- Une chaîne (
customerId) - Une collection d'objets
CampaignOperation - Le champ
response_content_typeindiquant le type de réponse préféré.
Opérations
Un objet d'opération tel qu'un CampaignOperation vous permet de spécifier l'action que vous souhaitez effectuer sur une seule ressource en définissant son champ operation. Ce champ est un champ oneof contenant les attributs suivants dont le type est le type de ressource:
create- Crée une instance de la ressource.
update- Met à jour la ressource pour qu'elle corresponde aux attributs de la ressource
update. Lorsque ce champ est défini, vous devez également définir leupdate_maskde l'opération, qui indique à l'API Google Ads les attributs à modifier lors de l'opération de mise à jour. Chaque bibliothèque cliente dispose d'un utilitaire ou d'une méthode d'assistance qui générera automatiquement leupdate_mask, comme indiqué dans nos bibliothèques clientes. remove- Supprime la ressource.
Étant donné que le champ operation est un champ oneof, vous ne pouvez pas utiliser une seule opération pour modifier plusieurs objets. Par exemple, si vous souhaitez créer une campagne et en supprimer une autre, ajoutez deux instances de CampaignOperation à votre demande: l'une avec create défini et l'autre avec remove.
Opérations de traitement par lot
Bien qu'une seule opération ne puisse créer, mettre à jour ou supprimer qu'une seule ressource, une requête mutate unique peut contenir plusieurs opérations. Vous devez combiner vos opérations en une seule requête mutate au lieu d'envoyer plusieurs requêtes mutate contenant chacune une seule opération.
Par exemple, si vous souhaitez créer 10 campagnes, vous devez envoyer un seul élément MutateCampaignsRequest contenant dix objets CampaignOperation.
Modifier les réponses
Le contenu renvoyé dans la réponse dépend de ce qui a été envoyé dans le champ response_content_type de la requête mutate. Par exemple, si MUTABLE_RESOURCE a été spécifié, la réponse ne contiendra que les champs modifiables de la campagne. Vous pouvez ensuite effectuer des mutates de suivi sur cet objet ressource sans avoir à le reconstruire.
Erreurs de mutation
Les opérations d'une demande mutate donnée ne sont appliquées à votre compte Google Ads que si chaque opération de la requête aboutit. Consultez le guide des erreurs courantes pour obtenir la liste des erreurs courantes et découvrir comment les résoudre.
Inspecter des objets avec get (obsolète)
Outre la modification des objets, chaque service spécifique au type de ressource possède également une méthode get pour récupérer tous les attributs d'une seule ressource.
Cette méthode accepte une requête get dont le seul attribut est resource_name.
Les méthodes get sont proposées par l'API Google Ads pour faciliter la récupération de tous les attributs d'un même objet. Bien qu'il s'agisse d'un excellent outil pour apprendre l'API ou inspecter un objet individuel à des fins de débogage ou d'enseignement, votre application ne doit pas utiliser de méthodes get pour récupérer des objets à traiter ou à créer des rapports. Utilisez plutôt GoogleAdsService, car il vous permet de ne récupérer que des attributs d'objets spécifiques, de récupérer des métriques de performances et de diffuser des ensembles de résultats volumineux. Si votre application envoie un grand nombre de requêtes GET, des limites de débit peuvent s'appliquer.