La plupart des ressources sont modifiées (créées, mises à jour ou supprimées) à l'aide d'une méthode Mutate
. La méthode Mutate
est appelée en tant que POST
HTTP vers une URL spécifique à une ressource qui correspond au modèle de nom de ressource, sans l'ID de ressource final.
Les ID des ressources à modifier sont plutôt envoyés dans le corps de la requête JSON. Cela vous permet d'envoyer un seul appel d'API contenant plusieurs opérations sur différentes ressources.
Par exemple, le nom de ressource d'une campagne utilise le format suivant:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Pour obtenir l'URL utilisée pour la mutation des campagnes, omettez l'ID de ressource à la fin et ajoutez :mutate
:
https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/campaigns:mutate
Un message Mutate
contient un objet JSON de premier niveau avec un tableau operations
pouvant contenir de nombreux objets operation
. Chaque opération peut être l'une des suivantes: create
, update
ou remove
. Ce sont les seules opérations mutate possibles.
POST /v17/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ ... ] }
La plupart des services peuvent gérer des milliers d'opérations via un seul appel d'API. Le guide sur les limites du système décrit les limites de taille des requêtes.
Les opérations d'une même requête API sont exécutées par défaut sous la forme d'un seul ensemble d'actions, ce qui signifie qu'elles réussissent toutes ensemble ou que l'ensemble du lot échoue en cas d'échec d'une opération unique. Certains services acceptent un attribut partialFailure
pour modifier ce comportement. Pour en savoir plus sur la sémantique des opérations mutate, consultez la section Mutation des ressources.
Créer
Les opérations de création génèrent de nouvelles entités et doivent inclure une représentation JSON complète de la ressource que vous souhaitez créer.
POST /v17/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "create": { "name": "An example campaign", "status": "PAUSED", "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/CAMPAIGN_BUDGET_ID", "advertisingChannelType": "SEARCH", "networkSettings": { "targetGoogleSearch": true, "targetSearchNetwork": true, "targetContentNetwork": true, "targetPartnerSearchNetwork": false }, "target_spend": {} } } ] }
Mettre à jour
Les opérations de mise à jour effectuent des mises à jour creuses sur une ressource existante. Il vous suffit de spécifier les champs que vous souhaitez modifier.
Pour spécifier les champs que vous souhaitez mettre à jour, définissez l'attribut updateMask
sur une liste de noms de champs séparés par une virgule. Cela est particulièrement utile si vous disposez déjà d'une représentation JSON complète d'un objet (par exemple, renvoyée par un appel d'API précédent), mais que vous ne souhaitez modifier que certains champs.
Au lieu d'éliminer l'objet JSON, vous pouvez simplement répertorier les noms de champs à modifier dans updateMask
et envoyer l'intégralité de l'objet JSON.
L'exemple ci-dessous modifie les name
et status
d'une campagne existante ayant l'resourceName
donnée.
POST /v17/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "updateMask": "name,status", "update": { "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID", "name": "My renamed campaign", "status": "PAUSED", } } ] }
Supprimer
Les opérations de suppression suppriment efficacement un objet, en définissant son état Google Ads sur REMOVED
. Seul le resourceName
à supprimer est nécessaire.
POST /v17/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID" } ] }