Modifica e ispezione degli oggetti

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

Come descritto nella guida alla struttura dell'API, ogni risorsa di primo livello nell'API Google Ads ha un servizio corrispondente specifico per un 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 per 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, mentre Campaign.NetworkSettings non lo è.

Modifica degli oggetti

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

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

Ad esempio, il metodo MutateCampaigns di CampaignService accetta una MutateCampaignsRequest che consiste di:

• 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 è un campo unico composto 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 è impostato, devi impostare anche il update_mask dell'operazione, che indica all'API Google Ads quali attributi modificare durante l'operazione di aggiornamento. Ogni libreria client dispone di un'utilità o di un metodo helper che genererà update_mask automaticamente, come dimostrato nelle nostre librerie client.

remove

Rimuove la risorsa.

Poiché il campo operation è di tipo 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 di raggruppamento

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

Ad esempio, se vuoi creare dieci campagne, devi inviare un singolo MutateCampaignsRequest con dieci oggetti CampaignOperation.

Modifica risposte

Ciò che viene restituito nella risposta dipende da ciò che è stato inviato nel response_content_type della richiesta di modifica. Ad esempio, se MUTABLE_RESOURCE è stato specificato, la risposta conterrà solo i campi modificabili della campagna. Puoi quindi apportare modifiche di follow-up all'oggetto risorsa senza doverlo ricostruire.

Errori di modifica

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 un elenco di errori comuni e come risolverli.

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

Ispezione di oggetti con get (deprecato)

Oltre a modificare gli oggetti, ogni servizio specifico del tipo di risorsa dispone anche di 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 vantaggi offerti dall'API Google Ads per semplificare il recupero di tutti gli attributi di un singolo oggetto. Sebbene questo sia un ottimo strumento per imparare l'API o ispezionare un singolo oggetto per il debug o a scopo didattico, l'app non dovrebbe usare metodi GET per recuperare gli oggetti per l'elaborazione o la generazione di report. Utilizza invece GoogleAdsService, poiché consente di recuperare solo attributi specifici degli oggetti, supporta il recupero di metriche delle prestazioni e consente lo streaming attraverso grandi set di risultati. Se la tua app invia un numero elevato di richieste get, potresti incorrere in limiti di frequenza.