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 à la ressource qui correspond au format de nom de ressource, sans l'ID de ressource à la fin.
Les ID des ressources à modifier sont plutôt envoyés dans le corps de la requête JSON. Vous pouvez ainsi 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 dériver l'URL utilisée pour modifier les campagnes, omettez l'ID de ressource à la fin et ajoutez :mutate:
https://googleads.googleapis.com/v19/customers/CUSTOMER_ID/campaigns:mutate
Un message Mutate contient un objet JSON de niveau supérieur avec un tableau operations pouvant contenir de nombreux objets operation. Chaque opération peut être l'une des suivantes: create, update ou remove. Il s'agit des seules opérations de modification possibles.
POST /v19/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 acceptent des milliers d'opérations dans un seul appel d'API. Le guide Limites système décrit les limites concernant les tailles de requêtes.
Par défaut, les opérations d'une seule requête d'API sont exécutées en tant qu'ensemble d'actions. Cela signifie qu'elles réussissent toutes ensemble ou que l'ensemble du lot échoue si une seule opération échoue. Certains services acceptent un attribut partialFailure pour modifier ce comportement. Pour en savoir plus sur la sémantique des opérations de modification, consultez la section Modifier 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 /v19/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 sporadiques d'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, comme renvoyé par un appel d'API précédent), mais que vous ne souhaitez modifier que certains champs.
Au lieu d'élaguer l'objet JSON, vous pouvez simplement lister les noms de champ à modifier dans updateMask et envoyer l'objet JSON entier.
L'exemple ci-dessous modifie les name et status d'une campagne existante ayant le resourceName donné.
POST /v19/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 effectivement un objet, en définissant son état Google Ads sur REMOVED. Seul l'resourceName à supprimer est obligatoire.
POST /v19/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" } ] }