Best practice

Questa pagina descrive varie best practice da prendere in considerazione durante lo sviluppo di applicazioni rispetto all'API Google Ad Manager.

Riutilizza client/stub di servizio nel corso di un'esecuzione

La creazione di un nuovo client/stub di servizio ha un costo marginale associato al recupero del WSDL e all'allocazione delle risorse. Se possibile, crea il client/stub di servizio una volta all'inizio di un'esecuzione e rendilo disponibile per classi e funzioni secondo necessità.

Usa il paging per il recupero degli oggetti

Tutti i servizi supportano un metodo get*ByStatement(), che consente di filtrare i risultati utilizzando la sintassi PQL. Le clausole LIMIT e OFFSET possono essere utilizzate per suddividere set di risultati di grandi dimensioni in pagine, evitando timeout e mantenendo ragionevoli le dimensioni delle pagine di risposta. Le dimensioni di pagina suggerite sono comprese tra 200 e 500, a seconda della complessità degli oggetti.

Richieste di aggiornamento batch

Quando modifichi più oggetti dello stesso tipo, puoi migliorare le prestazioni inviando tutti gli oggetti nella stessa richiesta update*(). Esiste un overhead marginale per il client e il server per ogni richiesta e il raggruppamento in batch può essere un mezzo efficace per ridurre il numero di richieste. Ad esempio, utilizza updateOrders per aggiornare un gruppo di Ordini anziché un singolo ordine in ogni chiamata.

Utilizzare i parametri di associazione in PQL

I parametri di associazione consentono di inserire le variabili in un'istruzione di query PQL. PQL fa riferimento a una variabile di associazione tramite un nome senza spazi che iniziano con i due punti, ad es. :name. Un esempio di codice è disponibile nella pagina sulla sintassi PQL.

Ti consigliamo di utilizzare le variabili di associazione perché migliorano la leggibilità del codice, eliminando la necessità di concatenare stringhe e variabili in un'istruzione di query. Inoltre, semplificano il riutilizzo delle istruzioni PQL, poiché è possibile creare nuove query sostituendo i valori dei parametri di associazione.

Concedi i privilegi utente con parsimonia

Quando utilizzi UserService per creare/aggiornare i ruoli utente, fai attenzione a non concedere agli utenti privilegi non necessari. È possibile accedere a molte funzionalità dell'API con una combinazione di ruoli anziché assegnare all'utente un ruolo di amministratore. Per decidere quali ruoli assegnare a un utente, consulta la documentazione sulle autorizzazioni. Inoltre, in qualità di sviluppatore di applicazioni di terze parti, assicurati di determinare il livello di accesso necessario alla tua applicazione quando chiedi a una rete di creare un utente per te; un ruolo con meno privilegi dell'amministratore potrebbe essere sufficiente.

Rimani entro i limiti di quota

L'API Ad Manager applica diversi limiti di quota per una maggiore affidabilità. È importante mantenere le applicazioni entro questi limiti e sapere come rispondere a tutti gli errori di quota che l'API può restituire.

Quota API

La prima quota applicata alle richieste API è a livello di rete. Per gli account Ad Manager 360 il limite è di 8 richieste al secondo e per gli account Ad Manager il limite è di 2 richieste al secondo. Superare questo limite genera un errore QuotaError.EXCEEDED_QUOTA. Tutte le richieste API effettuate sulla tua rete si applicano a questa quota, incluse le applicazioni di terze parti a cui tu o qualcuno della tua azienda avete concesso l'accesso API alla rete.

Quote specifiche per sistema

La quota API da sola non è sufficiente per proteggere in modo adeguato determinati sistemi all'interno di Ad Manager che richiedono molte risorse. I sistemi di generazione di report e di previsione definiscono le proprie quote che possono causare errori dell'API: QuotaError.REPORT_JOB_LIMIT e ForecastError.EXCEEDED_QUOTA, rispettivamente.

Gestione degli errori di quota

Se l'applicazione riscontra uno degli errori di quota riportati sopra, esegui una strategia per riprovare la richiesta API. Ti consigliamo di attendere almeno 5 secondi e, se continui a ricevere l'errore, utilizza il backoff esponenziale per aumentare il tempo tra un tentativo e l'altro. Se il nuovo tentativo non va a buon fine, esegui un controllo delle applicazioni API per verificare se ci sono utenti sulla rete che stanno svuotando la quota.