La maggior parte delle risorse viene modificata (creata, aggiornata o rimossa) utilizzando un metodo Mutate. Il metodo Mutate viene richiamato come POST HTTP verso un URL specifico della risorsa che corrisponde al pattern nome risorsa, senza l'ID risorsa finale.
Gli ID delle risorse da modificare vengono invece inviati nel corpo della richiesta JSON. Ciò consente di inviare una singola chiamata API contenente 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/v16/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 create, update o remove. Queste sono le uniche operazioni
mutate possibili.
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 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 per impostazione predefinita come un insieme di azioni, il che significa che vengono eseguite tutte insieme oppure l'intero batch non va a buon fine se una singola operazione non va a buon fine. Alcuni servizi supportano un attributo partialFailure per modificare questo comportamento. Per informazioni più dettagliate sulla semantica delle operazioni di modifica, consulta Mutating delle risorse.
Crea
Le operazioni di creazione producono nuove entità e devono includere una rappresentazione JSON completa della risorsa che intendi creare.
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": {}
}
}
]
}
Aggiorna
Le operazioni di aggiornamento eseguono aggiornamenti sparsi su una risorsa esistente. Devi solo specificare i campi da modificare.
Per specificare i campi da aggiornare, imposta l'attributo updateMask su un elenco di nomi di campi separati da virgole. Ciò è particolarmente utile se hai già una rappresentazione JSON completa di un oggetto (ad esempio, come restituito da una chiamata API precedente), ma vuoi modificare solo determinati 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 i valori name e status di una campagna esistente con lo resourceName specificato.
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",
}
}
]
}
Rimuovi
La rimozione delle operazioni elimina un oggetto in modo efficace, impostando lo stato di Google Ads su REMOVED. È necessario solo l'elemento resourceName da rimuovere.
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"
}
]
}