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 correspondant spécifique au type de ressource 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 illustrer la modification des objets Campaign, mais les mêmes concepts s'appliquent à tous les autres services spécifiques à un type de ressource.

Requêtes de modification

Chaque service spécifique à un type de ressource dispose d'une méthode mutate qui accepte une requête de modification. Cette requête comprend les éléments suivants :

• customer_id (ou customerId dans les URL REST)
• 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 modifiable ou uniquement le nom de la ressource est renvoyé après la mutation)

Par exemple, la méthode MutateCampaigns de CampaignService accepte un MutateCampaignsRequest composé 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).

Le champ operation étant 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 même requête de modification 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 requête MutateCampaignsRequest contenant dix objets CampaignOperation. Pour regrouper des opérations sur différents types de ressources dans une seule requête, utilisez GoogleAdsService.Mutate ou des ressources de mutation.

Réponses de mutation

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 le champ 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 toutes les opérations de la requête aboutissent. Si une opération échoue, l'intégralité de la requête est annulée. Pour les requêtes de modification compatibles avec l'échec partiel (celles comportant 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 changé 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.