Video: dai un'occhiata al discorso su servizi e risorse del workshop 2019
Questa guida illustra 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 visualizzato come una gerarchia di oggetti.
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 i tuoi 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 a livello di gruppo di annunci, ogni gruppo di annunci contiene uno o più annunci di gruppo.
Puoi collegare uno o più elementi 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, ad esempio 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 informazioni aggiuntive ai 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
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.
ID oggetto | Ambito dell'univocità | Unicità 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 ) è univoca a livello globale |
ID criterio del gruppo di annunci | Gruppo di annunci | No, ma la coppia (AdGroupId , CriterionId ) è univoca a livello globale |
ID criterio campagna | Priorità | No, ma la coppia (CampaignId , CriterionId ) è univoca a livello globale |
Estensioni annuncio | Priorità | No, ma la coppia (CampaignId , AdExtensionId ) è univoca a livello globale |
ID feed | Globale | Sì |
ID elemento del feed | Globale | Sì |
ID attributo 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 dello spazio di 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 i contenuti. Ad esempio, AdGroupAd
può fare riferimento a un oggetto, come un annuncio di testo, un annuncio per hotel o un annuncio locale. Questo valore è accessibile 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 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
Di conseguenza, per una campagna con ID 987654
nell'account Google Ads con ID cliente
1234567
, resource_name
sarà:
customers/1234567/campaigns/987654
Servizi
I servizi consentono di recuperare e modificare le entità Google Ads. Esistono tre tipi di servizi: servizi di modifica, recupero di oggetti e statistiche e servizi di recupero dei metadati.
Modificare (mutare) gli 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, utile per esaminare la struttura di una risorsa.
Esempi di servizi:
CustomerService
per la modifica dei clienti.CampaignService
per modificare le campagne.AdGroupService
per modificare i gruppi di annunci.
Ogni richiesta mutate
deve includere oggetti operation
corrispondenti. Ad esempio, il metodo CampaignService.MutateCampaigns
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 verificarsi 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 UI di Google Ads simultanea.
L'API non fornisce un modo per bloccare un oggetto prima dell'aggiornamento. Se due origini provano a modificare contemporaneamente un oggetto, l'API genera un valore 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 aver modificato gli oggetti, quindi devi attendere una risposta per ogni richiesta. Sebbene questo approccio sia relativamente semplice per la programmazione, potrebbe avere un impatto negativo sul bilanciamento del carico e spreco di 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. Dopo l'invio di 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 completarlo.
Per saperne di più sull'elaborazione asincrona, consulta la guida all'elaborazione batch.
Convalida delle modifiche
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 errati senza eseguire effettivamente l'operazione.
Per utilizzare questa funzionalità, imposta il campo booleano facoltativo validate_only
della richiesta su
true
. La richiesta verrebbe quindi completamente convalidata come se stessi per essere eseguita, ma l'esecuzione finale viene saltata. Se non vengono rilevati errori, viene restituita una risposta vuota. Se la convalida non va a buon fine, i messaggi nella risposta indicheranno i punti di errore.
validate_only
è particolarmente utile per testare gli annunci alla ricerca di violazioni comuni delle norme. Gli annunci vengono rifiutati automaticamente se violano norme, ad esempio quelle relative a parole, punteggiatura, lettere maiuscole o lunghezza specifiche. Un singolo annuncio non valido
potrebbe causare la mancata riuscita di un intero batch. Il test di un nuovo annuncio all'interno di una richiesta validate_only
può rivelare tali violazioni. Per vedere come funziona, consulta l'esempio di codice per la gestione degli errori di violazione delle norme.
Visualizza le statistiche sugli oggetti e sul rendimento
GoogleAdsService
è il servizio unico e unificato per il recupero di oggetti e
statistiche sulle prestazioni.
Tutte le richieste Search
e SearchStream
per GoogleAdsService
richiedono una query che specifichi la risorsa su cui eseguire la query, gli attributi delle risorse e le metriche relative alle prestazioni 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.
Recupero dei metadati
GoogleAdsFieldService
recupera
i metadati sulle risorse nell'API Google Ads, come gli attributi disponibili per
una risorsa e il tipo di dati.
Questo servizio fornisce le informazioni necessarie per creare una query in GoogleAdsService
. Per praticità, le informazioni restituite da GoogleAdsFieldService
sono disponibili anche nella documentazione di riferimento dei campi.