Modifica e ispezione degli oggetti

Obiettivo: capire come modificare e ispezionare gli oggetti utilizzando l'API Google Ads.

Come discusso nella guida alla struttura dell'API, a ogni risorsa di primo livello nell'API Google Ads corrisponde un servizio specifico per il tipo di risorsa che supporta:

• Modifica delle istanze della risorsa
• Recupero di una singola istanza della risorsa per l'ispezione

Questa guida utilizzerà CampaignService per dimostrare la modifica e l'ispezione degli oggetti Campaign, ma gli stessi concetti si applicano a tutti gli altri servizi specifici del tipo di risorsa.

Termine chiave: una risorsa di primo livello è una risorsa il cui nome non include un punto (.). Ad esempio, Campaign è una risorsa di primo livello, al contrario di Campaign.NetworkSettings.

Modifica degli oggetti

Ogni servizio specifico del tipo di risorsa avrà un metodo mutate che accetta una richiesta di modifica. Questa richiesta è costituita da:

• Un customerId
• Una raccolta di operazioni
• Un'impostazione del tipo di contenuto della risposta che determina se dopo la modifica deve essere restituita la risorsa modificabile o solo il nome della risorsa.

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

• Un customerId
• Una raccolta di CampaignOperation oggetti
• Il campo response_content_type che indica il tipo di risposta preferito.

Suite operativa

Un oggetto operazione come CampaignOperation consente di specificare l'azione da eseguire su una singola risorsa impostando il relativo campo operation. Questo campo è un campo unico costituito dai seguenti attributi il cui tipo è il tipo di risorsa:

create

Crea una nuova istanza della risorsa.

update

Aggiorna la risorsa in modo che corrisponda agli attributi della risorsa update. Se questo campo viene impostato, devi anche impostare il update_mask dell'operazione, che indica all'API Google Ads gli attributi da modificare durante l'operazione di aggiornamento. Ogni libreria client prevede un metodo di utilità o helper che genera automaticamente update_mask, come dimostrato nelle nostre librerie client.

remove

Rimuove la risorsa.

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 rimuovere un'altra campagna, aggiungi due istanze di CampaignOperation alla richiesta: una con create impostato e un'altra con remove impostato.

Operazioni di raggruppamento

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 tue 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 con dieci oggetti CampaignOperation.

Modifica risposte

I contenuti restituiti nella risposta dipendono da ciò che è stato inviato nell'elemento response_content_type della richiesta di modifica. Ad esempio, se MUTABLE_RESOURCE è stato specificato, la risposta conterrebbe solo i campi modificabili della campagna. Puoi quindi apportare modifiche di follow-up sull'oggetto risorsa senza doverlo ricostruire.

Modifica errori

Le operazioni in una determinata richiesta di modifica verranno applicate al tuo account Google Ads solo se ogni operazione nella richiesta ha esito positivo. Consulta la guida agli errori comuni per visualizzare un elenco degli errori più comuni e le relative soluzioni.

Avviso: get non è più supportato. Utilizza search o searchStream per recuperare gli oggetti.

Ispezione degli oggetti con get (deprecato)

Oltre a modificare gli oggetti, ogni servizio specifico del tipo di risorsa ha anche un metodo get per recuperare tutti gli attributi di una singola risorsa. Questo metodo accetta una richiesta get il cui unico attributo è resource_name.

Punto chiave: usa get con parsimonia.

I metodi get sono una comodità offerta dall'API Google Ads che semplifica il recupero di tutti gli attributi di un singolo oggetto. Sebbene si tratti di un ottimo strumento per apprendere l'API o ispezionare un singolo oggetto a scopo di debug o didattico, l'app non deve utilizzare metodi get per recuperare oggetti per l'elaborazione o la generazione di report. Usa invece GoogleAdsService, poiché consente di recuperare solo attributi specifici degli oggetti, supporta il recupero di metriche sulle prestazioni e consente l'inserimento di flussi di dati attraverso set di risultati di grandi dimensioni. Se la tua app invia un numero elevato di richieste di recupero, potresti incorrere in limiti di frequenza.