Struttura dell'API

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

Questa guida presenta i componenti principali che compongono l'API Google Ads. La L'API Google Ads è composta da risorse e servizi. Una risorsa rappresenta un account 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.

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

• Ogni cliente contiene uno o più account attivi campagne.

• 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 in esecuzione. Fatta eccezione per le campagne per app che possono contenere un solo annuncio del gruppo di annunci per annuncio ogni gruppo di annunci contiene uno o più annunci.

Puoi allegare uno o più AdGroupCriterion o CampaignCriterion a un gruppo di annunci oppure 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à. Criteri definiti a livello di campagna inciderà 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 consentono di offrire informazioni agli 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 univoci a livello globale in tutti gli account Google Ads, mentre gli altri sono univoci solo all'interno in un ambito ristretto.

Queste regole ID possono essere utili durante la progettazione dello spazio di archiviazione locale per Google Ads di oggetti strutturati.

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, ad esempio un annuncio di testo, annuncio locale o per hotel. È possibile accedere a questo valore tramite AdGroupAd.ad.type e restituisce un valore nel campo AdType enum.

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, campagna i nomi delle risorse hanno il seguente formato:

customers/customer_id/campaigns/campaign_id

Ad esempio, 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: modifica, recupero di oggetti e statistiche e recupero di metadati i servizi di machine learning.

Modificare (mutare) oggetti

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

Esempi di servizi:

• CustomerService per la modifica clienti.

• CampaignService per la modifica campagne.

• AdGroupService per modificare i gruppi di annunci.

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

Mutazioni simultanee

Un oggetto Google Ads non può essere modificato contemporaneamente da più di un'origine. Questo potrebbero verificarsi errori se più utenti aggiornano lo stesso oggetto con la tua app o se modifichi gli oggetti Google Ads in parallelo utilizzando i thread. Ciò include l'aggiornamento dell'oggetto da più thread nello stesso o da diverse applicazioni (ad esempio, la tua app e un sessione dell'interfaccia utente di Google Ads).

L'API non fornisce un modo per bloccare un oggetto prima dell'aggiornamento; se due origini o provare 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 solo una risposta o dopo la mutazione degli oggetti, occorre attendere una risposta 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 a attendere il completamento delle chiamate.

Un approccio alternativo consiste nel mutare gli oggetti in modo asincrono utilizzando BatchJobService, che esegue batch di operazioni su più servizi senza attenderne il completamento. Una volta un job batch, i server dell'API Google Ads eseguono le operazioni in modo asincrono dei processi che liberano i processi dall'esecuzione di altre operazioni. Puoi controllare periodicamente lo stato del job per il completamento.

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

Modifica convalida

La maggior parte delle richieste di mutazione può essere convalidata senza eseguire effettivamente la chiamata rispetto ai dati reali. Puoi testare la richiesta per verificare se mancano parametri e se senza eseguire 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 fosse ma l'esecuzione finale viene saltata. Se non vengono rilevati errori, viene visualizzato la risposta predefinita. Se la convalida ha esito negativo, i messaggi di errore nella risposta indicare i punti di errore.

validate_only è particolarmente utile per testare gli annunci per norme comuni violazioni delle norme. Gli annunci vengono rifiutati automaticamente se violano norme quali parole, punteggiatura, lettere maiuscole o lunghezza specifiche. Un solo annuncio non conforme potrebbe causare l'errore di un intero batch. Test di un nuovo annuncio in un validate_only una richiesta può rivelare tali violazioni. Fai riferimento all'esempio di codice per la gestione errori di violazione delle norme per consultare questo in azione.

Ottieni statistiche su oggetti e rendimento

GoogleAdsService è l'unica, unificata per il recupero di oggetti e statistiche sulle prestazioni.

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

Recuperare i metadati

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

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