Modifier des objets

**Objectif** : Comprendre comment modifier des objets à l'aide de l'API Google Ads.

Comme indiqué dans le guide sur la structure de l'API, chaque ressource de premier niveau de l'API Google Ads dispose d'un service spécifique au type de ressource correspondant qui permet de modifier les instances de la ressource. Vous pouvez également utiliser GoogleAdsService.Mutate pour modifier plusieurs types de ressources de manière atomique dans une seule requête.

Ce guide utilise CampaignService pour montrer comment modifier des objets Campaign, mais les mêmes concepts s'appliquent à tous les autres services spécifiques au type de ressource.

Terme clé : Une ressource de premier niveau est une ressource dont le nom n'inclut pas de point (.). Par exemple, Campaign est une ressource de premier niveau, mais Campaign.NetworkSettings n'en est pas une.

Requêtes de mutation

Chaque service spécifique au type de ressource dispose d'une méthode mutate qui accepte une requête de mutation. Cette requête se compose des éléments suivants :

• Un customer_id (ou customerId dans les URL REST)
• Une collection d'operations
• Des paramètres d'exécution facultatifs tels que partial_failure, validate_only et response_content_type (qui détermine si la ressource mutable ou uniquement le nom de la ressource est renvoyé après la mutation)

Par exemple, la MutateCampaigns méthode de CampaignService accepte un MutateCampaignsRequest qui se compose des éléments suivants :

• Un customer_id
• Une collection d'objets CampaignOperation (operations)
• Des paramètres d'exécution facultatifs (partial_failure, validate_only et response_content_type indiquant le type de réponse préféré)

Remarque : Les services et méthodes disponibles peuvent varier selon les versions de l'API. Par exemple, pour configurer les objectifs de cycle de vie des clients et des campagnes, utilisez les Mutate* méthodes sur GoalService et CampaignGoalConfigService dans la version 25 et ultérieure, ou les Configure* méthodes sur CustomerLifecycleGoalService et CampaignLifecycleGoalService dans la version 24 et antérieure.

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 oneof champ composé des attributs suivants :

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 le update_mask de l'opération, qui indique à l'API Google Ads les attributs à modifier lors de l'opération de mise à jour. Chaque bibliothèque cliente inclut un utilitaire de masque de champ ou une méthode d'assistance qui génère le update_mask pour vous.

remove

Supprime la ressource spécifiée par sa chaîne de nom de ressource (par exemple, customers/1234567890/campaigns/987654321).

É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 requête : une avec create défini et une autre avec remove défini.

Opérations par lot

Bien qu'une seule opération ne puisse créer, mettre à jour ou supprimer qu'une seule ressource, une seule requête de mutation peut contenir plusieurs opérations. Vous devez combiner vos opérations dans une seule requête de modification au lieu d'envoyer plusieurs requêtes de modification contenant chacune une seule opération.

Par exemple, si vous souhaitez créer dix campagnes, vous devez envoyer une seule MutateCampaignsRequest comportant dix objets CampaignOperation. Pour regrouper des opérations sur différents types de ressources dans une seule requête, utilisez GoogleAdsService.Mutate ou la modification de ressources.

Réponses de mutation

Ce qui est renvoyé dans la réponse dépend de ce qui a été envoyé dans le response_content_type champ de la requête de modification. Par exemple, si MUTABLE_RESOURCE est spécifié, alors la réponse contient à la fois le resource_name de la ressource et les champs mutables de la campagne dans campaign. Par défaut (RESOURCE_NAME_ONLY), seul le resource_name est renseigné dans chaque MutateCampaignResult.

Erreurs de mutation

Par défaut (partial_failure = false), les opérations d'une requête de modification ne sont appliquées à votre compte Google Ads que si chaque opération de la requête réussit. Si une opération échoue, l'ensemble de la requête est annulé. Pour les requêtes de mutation qui acceptent les échecs partiels (celles qui comportent un champ partial_failure dans le message de requête), la définition de partial_failure = true valide les opérations valides, tandis que les opérations ayant échoué renvoient des erreurs spécifiques à l'opération dans le champ partial_failure_error de la réponse. Pour en savoir plus sur la gestion des erreurs, consultez le guide sur les échecs partiels et le guide sur les erreurs courantes.

Suivre les modifications

Pour suivre les modifications apportées aux objets de votre compte Google Ads ou pour récupérer l'état actuel des objets, vous pouvez utiliser les ressources change_status et change_event.

• change_status fournit un résumé des ressources qui ont été modifiées au cours d'une période donnée.
• change_event fournit un historique détaillé des modifications, y compris les anciennes et les nouvelles valeurs des champs modifiés.

Pour interroger ces ressources, utilisez la GoogleAdsService.SearchStream ou GoogleAdsService.Search méthode. En savoir plus sur le streaming de rapports à l'aide de GoogleAdsService.