Modifier des objets

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 les objets Campaign, mais les mêmes concepts s'appliquent à tous les autres services spécifiques aux types de ressources.

Requêtes de mutation

Chaque service spécifique à un type de ressource possède une méthode mutate qui accepte une requête mutate. Cette demande comprend les éléments suivants :

• Un customer_id (ou customerId dans les URL REST)
• Une collection de operations
• 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 méthode MutateCampaigns de CampaignService accepte un MutateCampaignsRequest qui se compose des éléments suivants :

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

Opérations

Un objet d'opération tel que 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 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 demande : une avec create défini et une autre avec remove défini.

Opérations par lot

Bien qu'une seule opération ne puisse que créer, mettre à jour ou supprimer une seule ressource, une seule requête de modification peut contenir plusieurs opérations. Vous devez combiner vos opérations en 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 mutating resources.

Réponses de mutation

Ce qui est renvoyé dans la réponse dépend de ce qui a été envoyé dans le champ response_content_type de la requête de modification. Par exemple, si MUTABLE_RESOURCE est spécifié, la réponse contient à la fois le resource_name de la ressource et les champs modifiables de la campagne dans campaign. Par défaut (RESOURCE_NAME_ONLY), seul 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 avec 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 fréquentes.

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écapitulatif 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 méthode GoogleAdsService.SearchStream ou GoogleAdsService.Search. En savoir plus sur le streaming de rapports à l'aide de GoogleAdsService