Struttura dell'API

Questa guida introduce i componenti principali che costituiscono 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 in un gruppo di annunci. 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.

Le campagne Performance Max utilizzano una struttura diversa rispetto ad altri tipi di campagne: anziché gruppi di annunci e annunci del gruppo di annunci, una campagna Performance Max contiene gruppi di asset. Collega gli asset della creatività a un gruppo di asset utilizzando AssetGroupAsset e associa i segmenti di pubblico o i segnali del tema di ricerca utilizzando AssetGroupSignal.

Puoi collegare una o più risorse 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 influiscono su tutte le altre risorse all'interno della campagna. Puoi anche specificare i budget, nonché le date e gli orari di inizio e fine delle campagne o dei singoli annunci utilizzando AdGroupAd.start_date_time e AdGroupAd.end_date_time.

Infine, puoi collegare gli asset a livello di account, campagna, gruppo di annunci o gruppo di asset. Gli asset ti consentono di fornire informazioni aggiuntive agli annunci, come numeri di telefono, indirizzi o promozioni. Consulta la panoramica sugli 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 da un proprio ID. Alcuni di questi ID sono univoci a livello globale in tutti gli account Google Ads, mentre altri sono univoci solo in un ambito limitato.

Queste regole ID possono essere utili per progettare l'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 adattabile della rete di ricerca, un annuncio per hotel o un annuncio Demand Gen. È possibile accedere a questo valore tramite il campo AdGroupAd.ad.type, che restituisce un valore nell'enumerazione AdType. Tieni presente che la modificabilità può variare in base alla versione (ad esempio, VideoResponsiveAdInfo su Ad è modificabile nella versione 24 e successive).

Nomi delle risorse

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

customers/customer_id/campaigns/campaign_id

Quindi, 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 ti consentono di recuperare e modificare le entità Google Ads. Esistono tre tipi di servizi: servizi di modifica, di recupero di oggetti e statistiche e di recupero di metadati.

Modificare (mutate) gli oggetti

I servizi specifici per le risorse modificano le istanze di un tipo di risorsa associato utilizzando una richiesta mutate. Puoi anche utilizzare GoogleAdsService.Mutate per eseguire mutazioni atomiche su più tipi di risorse in una singola richiesta (ad esempio, creare insieme un budget della campagna, una campagna e un gruppo di annunci).

Esempi di servizi specifici per le risorse:

• CustomerService per modificare i clienti.

• CampaignService per modificare le campagne.

• AdGroupService per modificare i 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 Modificare gli 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 saperne di più sull' elaborazione asincrona, consulta la guida all'elaborazione batch.

Convalida della mutazione

La maggior parte delle richieste di modifica 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 viene convalidata completamente come se dovesse essere eseguita, ma l'esecuzione finale viene ignorata. Se non vengono rilevati errori, la risposta viene restituita senza risultati di mutazione (results è vuoto). Se la convalida non riesce, la richiesta non va a buon fine con un GoogleAdsFailure RPC errore per impostazione predefinita (partial_failure = false) oppure restituisce una risposta normale con errori specifici dell'operazione in partial_failure_error quando partial_failure = true.

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 unico e unificato per il recupero di oggetti e statistiche sul rendimento.

Tutte le Search e SearchStream richieste 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 saperne di più sul formato delle query, consulta la guida a Google Ads Query Language.

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. Per informazioni dettagliate sull'esecuzione di query su questo servizio, consulta la guida ai metadati delle risorse.

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.