Struttura dell'API

ondemand_video Video: Check out the Services and Resources talk from the 2019 workshop

Questa guida presenta i componenti principali che compongono l'API Google Ads. L'API Google Ads è costituita da risorse e servizi. Una risorsa rappresenta un'entità Google Ads, mentre i servizi recuperano e manipolano le entità Google Ads.

Gerarchia degli oggetti

Un account Google Ads può essere considerato una gerarchia di oggetti.

• La risorsa di primo livello di un account è il cliente.

• Ogni cliente contiene una o più campagne attive campaigns.

• Ogni campagna contiene uno o più gruppi di annunci, utilizzati per raggruppare gli annunci in raccolte logiche.

• Un annuncio del gruppo di annunci rappresenta un annuncio che stai pubblicando. Ad eccezione delle campagne per app, che possono avere un solo annuncio del gruppo di annunci per gruppo di annunci, ogni gruppo di annunci contiene uno o più annunci del gruppo di annunci.

Puoi collegare uno o più AdGroupCriterion o CampaignCriterion a un gruppo di annunci o a una campagna. Questi rappresentano i criteri che definiscono come vengono attivati gli annunci.

Esistono molti tipi di criteri, come parole chiave, fasce d'età e località. I criteri definiti a livello di campagna interessano tutte le altre risorse all'interno della campagna. Puoi anche specificare budget e date a livello di campagna.

Infine, puoi collegare gli asset a livello di account, campagna o gruppo di annunci. Gli asset ti consentono di fornire informazioni aggiuntive agli annunci, come numeri di telefono, indirizzi o promozioni. Vedi Panoramica degli asset.

Risorse

Le risorse rappresentano le entità all'interno del tuo account Google Ads. Campaign e AdGroup sono due esempi di risorse.

ID oggetto

Ogni oggetto in Google Ads è identificato dal proprio ID. Alcuni di questi ID sono univoci a livello globale in tutti gli account Google Ads, mentre altri sono univoci solo all'interno di un ambito limitato.

Queste regole di ID possono essere utili per la progettazione dell'archiviazione locale degli oggetti Google Ads.

Alcuni oggetti possono essere utilizzati per più tipi di entità. In questi casi, l'oggetto contiene un campo type che ne descrive i contenuti. Ad esempio, AdGroupAd può fare riferimento a un oggetto come un annuncio di testo, annuncio per hotel o annuncio locale. È possibile accedere a questo valore tramite il AdGroupAd.ad.type campo, che restituisce un valore nell' AdType enumerazione.

Nomi delle risorse

Ogni risorsa è identificata in modo univoco da una stringa resource_name, che concatena la risorsa e i relativi genitori in un percorso. Ad esempio, i nomi delle risorse della campagna hanno il seguente formato:

customers/customer_id/campaigns/campaign_id

Pertanto, per una campagna con ID 987654 nell'account Google Ads con ID cliente 1234567, il resource_name sarà:

customers/1234567/campaigns/987654

Servizi

I servizi consentono di recuperare e modificare le entità Google Ads. Esistono tre tipi di servizi: modifica, recupero di oggetti e statistiche e recupero di metadati.

Modificare (mutate) gli oggetti

Questi servizi modificano le istanze di un tipo di risorsa associato utilizzando una richiesta mutate. Forniscono anche una richiesta get che recupera una singola istanza di risorsa, che può essere utile per esaminare la struttura di una risorsa.

Esempi di servizi:

• CustomerService per la modifica di clienti.

• CampaignService per la modifica delle campagne.

• AdGroupService per la modifica dei gruppi di annunci.

Ogni richiesta mutate deve includere gli oggetti operation corrispondenti. Ad esempio, il CampaignService.MutateCampaigns metodo prevede una o più istanze di CampaignOperation. Per una discussione dettagliata sulle operazioni, consulta Modifica e ispezione degli oggetti.

Mutazioni simultanee

Un oggetto Google Ads non può essere modificato contemporaneamente da più di un'origine. Ciò potrebbe causare errori se più utenti aggiornano lo stesso oggetto con la tua app o se stai modificando gli oggetti Google Ads in parallelo utilizzando più thread. Ciò include l'aggiornamento dell'oggetto da più thread nella stessa applicazione o da applicazioni diverse (ad esempio, la tua app e una sessione simultanea dell'interfaccia utente di Google Ads).

L'API non fornisce un modo per bloccare un oggetto prima dell'aggiornamento; se due origini tentano di modificare simultaneamente un oggetto, l'API genera un DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Mutazioni asincrone e sincrone

I metodi di mutazione dell'API Google Ads sono sincroni. Le chiamate API restituiscono una risposta solo dopo la mutazione degli oggetti, il che significa che devi attendere una risposta a ogni richiesta. Sebbene questo approccio sia relativamente semplice da codificare, potrebbe influire negativamente sul bilanciamento del carico e sprecare risorse se i processi sono costretti ad attendere il completamento delle chiamate.

Un approccio alternativo consiste nel modificare gli oggetti in modo asincrono utilizzando BatchJobService, che esegue batch di operazioni su più servizi senza attendere il completamento. Una volta inviato un job batch, i server dell'API Google Ads eseguono le operazioni in modo asincrono, liberando i processi per eseguire altre operazioni. Puoi controllare periodicamente lo stato del job per verificare se è stato completato.

Per ulteriori informazioni sull' elaborazione asincrona, consulta la guida all'elaborazione batch.

Convalida della mutazione

La maggior parte delle richieste di mutazione può essere convalidata senza eseguire effettivamente la chiamata sui dati reali. Puoi testare la richiesta per verificare la presenza di parametri mancanti e valori di campo errati senza eseguire effettivamente l'operazione.

Per utilizzare questa funzionalità, imposta il campo booleano facoltativo validate_only della richiesta su true. La richiesta verrà convalidata completamente come se dovesse essere eseguita, ma l'esecuzione finale viene ignorata. Se non vengono rilevati errori, viene restituita una risposta vuota. Se la convalida non va a buon fine, i messaggi di errore nella risposta indicheranno i punti di errore.

validate_only è particolarmente utile per testare gli annunci per verificare la presenza di violazioni delle norme comuni. Gli annunci vengono rifiutati automaticamente se violano le norme, ad esempio se contengono parole, punteggiatura, maiuscole o lunghezza specifiche. Un singolo annuncio non conforme potrebbe causare il fallimento di un intero batch. Il test di un nuovo annuncio all'interno di una richiesta validate_only può rivelare eventuali violazioni di questo tipo. Per vedere questa funzionalità in azione, consulta l'esempio di codice per la gestione degli errori di violazione delle norme.

Recuperare oggetti e statistiche sul rendimento

GoogleAdsService è il servizio singolo e unificato per il recupero di oggetti e statistiche sul rendimento.

Tutte le richieste Search e SearchStream per GoogleAdsService richiedono una query che specifichi la risorsa su cui eseguire la query, gli attributi della risorsa e le metriche sul rendimento da recuperare, i predicati da utilizzare per filtrare la richiesta e i segmenti da utilizzare per suddividere ulteriormente le statistiche sul rendimento. Per ulteriori informazioni sul formato delle query, consulta la guida al linguaggio di query di Google Ads.

Recuperare i metadati

GoogleAdsFieldService recupera i metadati sulle risorse nell'API Google Ads, come gli attributi disponibili per una risorsa e il relativo tipo di dati.

Questo servizio fornisce le informazioni necessarie per creare una query per GoogleAdsService. Per comodità, le informazioni restituite da GoogleAdsFieldService sono disponibili anche nella documentazione di riferimento dei campi.