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 visualizzato come una gerarchia di oggetti.

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

• Ogni cliente contiene una o più campagne attive.

• 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 pubblichi 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 dei gruppi di annunci, una campagna Performance Max contiene gruppi di asset. Collega gli asset delle creatività a un gruppo di asset utilizzando AssetGroupAsset e allega gli indicatori dei segmenti di pubblico o dei temi di ricerca utilizzando AssetGroupSignal.

Puoi allegare una o più risorse AdGroupCriterion o CampaignCriterion a un gruppo di annunci o a una campagna. Questi rappresentano i criteri che definiscono l'attivazione degli 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 di fine per le campagne o per i 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 ai tuoi annunci, come numeri di telefono, indirizzi o promozioni. Consulta la 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 da un 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 ID possono essere utili quando progetti l'archiviazione locale per gli oggetti Google Ads.

Alcuni oggetti possono essere utilizzati per più tipi di entità. In questi casi, l'oggetto contiene un campo type che descrive i suoi 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 e restituisce un valore nell'enumerazione AdType. Tieni presente che la mutabilità 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 padre 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 sarebbe:

customers/1234567/campaigns/987654

Servizi

I servizi ti 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 (mutare) 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 risorsa:

• CustomerService per la modifica dei clienti.

• CampaignService per la modifica delle campagne.

• AdGroupService per modificare i gruppi di annunci.

Ogni richiesta mutate deve includere gli oggetti operation corrispondenti. Ad esempio, il metodo CampaignService.MutateCampaigns prevede una o più istanze di CampaignOperation. Per una discussione dettagliata delle operazioni, vedi Modifica 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 modifichi 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 mutate dell'API Google Ads sono sincroni. Le chiamate API restituiscono una risposta solo dopo la mutazione degli oggetti, il che ti costringe ad 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 loro 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 il completamento.

Per saperne di più sull'elaborazione asincrona, consulta la guida all'elaborazione batch.

Convalida della modifica

La maggior parte delle richieste di modifica può essere convalidata senza eseguire effettivamente la chiamata sui dati reali. Puoi testare la richiesta per parametri mancanti e valori dei campi 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 trovati errori, la risposta viene restituita senza risultati modificati (results è vuoto). Se la convalida non va a buon fine, la richiesta non va a buon fine con un errore RPC GoogleAdsFailure 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 in relazione alle violazioni comuni delle norme. Gli annunci vengono rifiutati automaticamente se violano norme come l'utilizzo di parole, punteggiatura, maiuscole o lunghezza specifiche. Un singolo annuncio non conforme potrebbe causare il fallimento dell'intero batch. Il test di un nuovo annuncio all'interno di una richiesta validate_only può rivelare eventuali violazioni di questo tipo. Per vedere questo in azione, consulta l'esempio di codice per la gestione degli errori di violazione delle norme.

Visualizzare le statistiche sugli oggetti e sul rendimento

GoogleAdsService è l'unico servizio 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 di 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, ad esempio 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.