Struttura dell'API

Video: guarda la presentazione su servizi e risorse del workshop del 2019

Questa guida presenta i componenti principali che compongono l'API Google Ads. L'API Google Ads è composta 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 visto come una gerarchia di oggetti.

Modello di campagna

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

  • Ciascun 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 stai pubblicando. Ad eccezione delle campagne per app che possono contenere un solo annuncio per gruppo di annunci, ogni gruppo di annunci contiene uno o più annunci.

Puoi collegare uno o più AdGroupCriterion o CampaignCriterion a un gruppo di annunci o a una campagna. Rappresentano i criteri che definiscono le modalità di 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 della campagna. Puoi anche specificare budget e date a livello di campagna.

Infine, puoi collegare le estensioni a livello di account, campagna o gruppo di annunci. Le estensioni ti consentono di fornire ulteriori informazioni sui tuoi annunci, come numero di telefono, indirizzo o promozioni.

Risorse

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

ID oggetto

Ciascun oggetto in Google Ads viene identificato dal 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.

ID oggetto Ambito dell'unicità Univoco a livello globale?
ID budget Globale Sì
ID campagna Globale Sì
ID gruppo di annunci Globale Sì
ID annuncio Gruppo di annunci No, ma la coppia (AdGroupId, AdId) è unica a livello globale
ID criterio gruppo di annunci Gruppo di annunci No, ma la coppia (AdGroupId, CriterionId) è unica a livello globale
ID criterio campagna Priorità No, ma la coppia (CampaignId, CriterionId) è unica a livello globale
Estensioni annuncio Priorità No, ma la coppia (CampaignId, AdExtensionId) è unica a livello globale
ID feed Globale Sì
ID elemento del feed Globale Sì
ID attributo del feed Feed No
ID mappatura feed Globale Sì
ID etichetta Globale Sì
ID elenco utenti Globale Sì

Queste regole ID possono essere utili durante la progettazione dell'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 ne descrive il contenuto. Ad esempio, AdGroupAd può fare riferimento a un oggetto come un annuncio di testo, un annuncio per hotel o un annuncio locale. È possibile accedere a questo valore tramite il campo AdGroupAd.ad.type e restituisce un valore nell'enumerazione AdType.

Nomi delle risorse

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

customers/customer_id/campaigns/campaign_id

Di conseguenza, per una campagna con ID 987654 nell'account Google Ads con ID cliente 1234567, il valore di 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: di modifica, di recupero di oggetti e statistiche e di recupero di metadati.

Modificare (mutare) oggetti

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

Esempi di servizi:

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

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 della UI di Google Ads).

L'API non fornisce un modo per bloccare un oggetto prima dell'aggiornamento; se due origini provano a mutare contemporaneamente un oggetto, l'API genera DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Mutazioni asincrone e sincrone

I metodi di modifica dell'API Google Ads sono sincroni. Le chiamate API restituiscono una risposta solo dopo che gli oggetti sono stati mutati, perciò è necessario attendere una risposta a ogni richiesta. Sebbene questo approccio sia relativamente semplice da programmare, potrebbe avere un impatto negativo 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 attenderne il completamento. Una volta inviato un job batch, i server dell'API Google Ads eseguono le operazioni in modo asincrono, liberando i processi da eseguire altre operazioni. Puoi controllare periodicamente lo stato del job per il completamento.

Consulta la guida all'elaborazione batch per ulteriori informazioni sull'elaborazione asincrona.

Modifica convalida

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

Per utilizzare questa funzionalità, imposta il campo booleano facoltativo validate_only della richiesta su true. La richiesta verrebbe quindi convalidata completamente come se venisse eseguita, ma l'esecuzione finale viene saltata. Se non vengono rilevati errori, viene restituita una risposta vuota. Se la convalida ha esito negativo, i messaggi di errore nella risposta indicheranno i punti di errore.

validate_only è particolarmente utile per testare gli annunci in caso di violazioni comuni delle norme. Gli annunci vengono rifiutati automaticamente se violano le norme relative, ad esempio, a parole specifiche, punteggiatura, lettere maiuscole o lunghezza. Un singolo annuncio non conforme potrebbe causare la mancata riuscita di un intero batch. Il test di un nuovo annuncio in una richiesta validate_only può rivelare eventuali violazioni di questo tipo. Per vedere un esempio pratico, consulta l'esempio di codice sulla gestione degli errori di violazione delle norme.

Ottieni statistiche su oggetti e rendimento

GoogleAdsService è il servizio unico unificato per il recupero di oggetti e statistiche sulle prestazioni.

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

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.

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

Indietro
Panoramica
Avanti
Relazioni di entità