La maggior parte delle risorse viene modificata (creata, aggiornata o rimossa) utilizzando un metodo Mutate. Il metodo Mutate viene richiamato come POST HTTP su un URL specifico della risorsa che corrisponde al pattern del nome della risorsa, senza l'ID risorsa finale.
Gli ID delle risorse da modificare vengono inviati nel corpo della richiesta JSON. Questo consente di inviare una singola chiamata API che contiene più operazioni su risorse diverse.
Ad esempio, il nome della risorsa di una campagna utilizza il seguente formato:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Per ricavare l'URL utilizzato per le campagne mutanti, ometti l'ID risorsa finale e aggiungi :mutate:
https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/campaigns:mutate
Un messaggio Mutate contiene un oggetto JSON di primo livello con un array operations che può contenere molti oggetti operation. Ogni operazione, a sua volta, può essere una delle seguenti: create, update o remove. Queste sono le uniche
operazioni di mutazione possibili.
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 maggior parte dei servizi supporta migliaia di operazioni in una singola chiamata API. La guida Limiti di sistema documenta le limitazioni relative alle dimensioni delle richieste.
Le operazioni all'interno di una singola richiesta API vengono eseguite come un insieme di azioni per impostazione predefinita, vale a dire che hanno tutte esito positivo insieme o l'intero batch non riesce in caso di errore di una singola operazione. Alcuni servizi supportano un attributo partialFailure per modificare questo comportamento. Per informazioni più dettagliate sulla semantica delle operazioni di modifica, consulta la sezione Mutazione delle risorse.
Creazione
Le operazioni di creazione producono nuove entità e devono includere una rappresentazione JSON completa della risorsa che intendi creare.
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": {}
}
}
]
}
Aggiornamento
Le operazioni di aggiornamento eseguono aggiornamenti sparsi per una risorsa esistente. Devi solo specificare i campi che vuoi modificare.
Per specificare i campi da aggiornare, imposta l'attributo updateMask su un elenco separato da virgole di nomi di campo. Ciò è particolarmente utile se disponi già di una rappresentazione JSON in formato completo di un oggetto (ad esempio, come restituito da una precedente chiamata API), ma vuoi modificare solo alcuni campi.
Anziché eliminare l'oggetto JSON, puoi semplicemente elencare i nomi dei campi da modificare in updateMask e inviare l'intero oggetto JSON.
L'esempio riportato di seguito modifica name e status di una campagna esistente con
resourceName specificati.
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",
}
}
]
}
Rimuovi
Le operazioni di rimozione eliminano in modo efficace un oggetto, impostando il relativo stato di Google Ads su
REMOVED. È necessario solo il resourceName da rimuovere.
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"
}
]
}