Modificare oggetti

Come descritto nella guida alla struttura dell'API, ogni risorsa di primo livello nell'API Google Ads ha un servizio corrispondente specifico per il tipo di risorsa che supporta la modifica delle istanze della risorsa. Puoi anche utilizzare GoogleAdsService.Mutate per modificare più tipi di risorse in modo atomico in una singola richiesta.

Questa guida utilizza CampaignService per dimostrare la modifica degli oggetti Campaign, ma gli stessi concetti si applicano a tutti gli altri servizi specifici per il tipo di risorsa.

Richieste di modifica

Ogni servizio specifico per il tipo di risorsa ha un metodo mutate che accetta una richiesta di modifica. Questa richiesta è composta da:

• Un customer_id (o customerId negli URL REST)
• Una raccolta di operations
• Impostazioni di esecuzione facoltative come partial_failure, validate_only e response_content_type (che determina se dopo la mutazione viene restituita la risorsa modificabile o solo il nome della risorsa)

Ad esempio, il metodo MutateCampaigns di CampaignService accetta un MutateCampaignsRequest composto da:

• customer_id
• Una raccolta di CampaignOperation oggetti (operations)
• Impostazioni di esecuzione facoltative (partial_failure, validate_only e response_content_type che indicano il tipo di risposta preferito)

Operazioni

Un oggetto operazione come CampaignOperation consente di specificare l'azione che vuoi eseguire su una singola risorsa impostando il campo operation. Questo campo è un campo oneof composto dai seguenti attributi:

create

Crea una nuova istanza della risorsa.

update

Aggiorna la risorsa in modo che corrisponda agli attributi della risorsa update. Quando questo campo è impostato, devi impostare anche il campo update_mask dell'operazione, che indica all'API Google Ads quali attributi modificare durante l'operazione di aggiornamento. Ogni libreria client include un'utilità per la maschera di campo o un metodo helper che genera update_mask per te.

remove

Rimuove la risorsa specificata dalla stringa del nome della risorsa (ad esempio, customers/1234567890/campaigns/987654321).

Poiché il campo operation è un campo oneof, non puoi utilizzare una singola operazione per modificare più oggetti. Ad esempio, se vuoi creare una campagna e rimuoverne un'altra, aggiungi due istanze di CampaignOperation alla richiesta: una con create impostato e un'altra con remove impostato.

Operazioni batch

Sebbene una singola operazione possa solo creare, aggiornare o rimuovere una singola risorsa, una singola richiesta di modifica può contenere più operazioni. Dovresti combinare le operazioni in un'unica richiesta di modifica anziché inviare più richieste di modifica, ciascuna contenente una singola operazione.

Ad esempio, se vuoi creare dieci campagne, devi inviare una singola MutateCampaignsRequest contenente dieci oggetti CampaignOperation. Per raggruppare le operazioni tra diversi tipi di risorse in un'unica richiesta, utilizza GoogleAdsService.Mutate o risorse di mutazione.

Risposte di modifica

Ciò che viene restituito nella risposta dipende da ciò che è stato inviato nel campo response_content_type della richiesta di modifica. Ad esempio, se viene specificato MUTABLE_RESOURCE, la risposta contiene sia il campo resource_name della risorsa sia i campi modificabili della campagna in campaign. Per impostazione predefinita (RESOURCE_NAME_ONLY), viene compilato solo resource_name in ogni MutateCampaignResult.

Errori di modifica

Per impostazione predefinita (partial_failure = false), le operazioni in una richiesta di modifica vengono applicate al tuo account Google Ads solo se ogni operazione nella richiesta va a buon fine. Se un'operazione non va a buon fine, viene eseguito il rollback dell'intera richiesta. Per le richieste di modifica che supportano l'errore parziale (quelle con un campo partial_failure nel messaggio di richiesta), l'impostazione di partial_failure = true esegue il commit delle operazioni valide, mentre le operazioni non riuscite restituiscono errori specifici dell'operazione nel campo partial_failure_error della risposta. Per informazioni dettagliate sulla gestione degli errori, consulta la guida agli errori parziali e la guida agli errori comuni.

Monitora le modifiche

Per monitorare le modifiche apportate agli oggetti nel tuo account Google Ads o per recuperare lo stato attuale degli oggetti, puoi utilizzare le risorse change_status e change_event.

• change_status fornisce un riepilogo delle risorse che sono state modificate in un determinato periodo di tempo.
• change_event fornisce una cronologia dettagliata delle modifiche, inclusi i valori precedenti e nuovi dei campi modificati.

Per eseguire query su queste risorse, utilizza il metodo GoogleAdsService.SearchStream o GoogleAdsService.Search. Scopri di più sullo streaming dei report utilizzando GoogleAdsService.