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 requête HTTP POST pour une URL spécifique à une ressource correspondant au modèle de nom de ressource, sans l'ID de ressource de fin.
À la place, les ID des ressources à modifier sont 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 respecte le format suivant:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Pour obtenir l'URL utilisée pour les campagnes en mutation, omettez l'ID de ressource à la fin et ajoutez :mutate:
https://googleads.googleapis.com/v16/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. Il s'agit des seules opérations mutate possibles.
POST /v16/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 permettent d'effectuer des milliers d'opérations via un seul appel d'API. Les limites du système décrivent les limites applicables à la taille des requêtes.
Par défaut, les opérations d'une même requête API sont exécutées comme un 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 seule opération. 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 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 /v16/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 à 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 (renvoyée par un appel d'API précédent, par exemple), mais que vous ne souhaitez modifier que certains champs.
Au lieu de supprimer l'objet JSON, vous pouvez simplement répertorier les noms des champs à modifier dans updateMask et envoyer l'objet JSON dans son intégralité.
L'exemple ci-dessous modifie les valeurs name et status d'une campagne existante ayant l'attribut resourceName donné.
POST /v16/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 permettent de supprimer efficacement un objet en définissant son état Google Ads sur REMOVED. Seul le paramètre resourceName à supprimer est obligatoire.
POST /v16/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"
}
]
}