Ottimizzazione delle prestazioni

Questo documento illustra alcune tecniche che puoi utilizzare per migliorare il rendimento della tua applicazione. In alcuni casi, vengono utilizzati esempi di altre API implementate per illustrare le idee presentate. Tuttavia, gli stessi concetti sono applicabili all'API Display & Video 360.

Lavorare con risorse parziali

Un altro modo per migliorare il rendimento delle chiamate API è richiedere solo la parte di dati che ti interessa. In questo modo, l'applicazione può evitare di trasferire, analizzare e memorizzare campi non necessari, in modo da utilizzare più efficacemente risorse come rete, CPU e memoria.

Risposta parziale

Per impostazione predefinita, il server restituisce la rappresentazione completa di una risorsa dopo aver elaborato le richieste. Per migliorare le prestazioni, puoi chiedere al server di inviare solo i campi di cui hai realmente bisogno e ricevere una risposta parziale.

Per richiedere una risposta parziale, utilizza il parametro di richiesta fields per specificare i campi da restituire. Puoi utilizzare questo parametro con qualsiasi richiesta che restituisce dati di risposta.

Esempio

L'esempio seguente mostra l'utilizzo del parametro fields con l'API Display & Video 360.

Richiesta semplice: questa richiesta HTTP GET omette il parametro fields e restituisce la risorsa completa.

GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1

Risposta completa della risorsa:i dati completi della risorsa includono i seguenti campi, insieme a molti altri che sono stati omessi per brevità.

200 OK

{
 "advertisers": [
  {
   "name": "advertisers/1",
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  {
   "name": "advertisers/2",
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  ...
 ],
 "nextPageToken": "..."
}

Richiesta di una risposta parziale: la seguente richiesta per la stessa risorsa utilizza il parametro fields per ridurre in modo significativo la quantità di dati restituiti.

GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)

Risposta parziale: in risposta alla richiesta precedente, il server invia una risposta contenente un array di inserzionisti ridotto che include solo l'ID inserzionista, il nome visualizzato e la proprietà ID partner di ciascun inserzionista, se presente.

200 OK

{
 "advertisers": [
  {
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1"
  },
  {
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2"
  },
  ...
 ]
}

Tieni presente che la risposta è un oggetto JSON che include solo i campi selezionati e gli oggetti principali che li contengono.

Di seguito sono riportati i dettagli su come formattare il parametro fields, seguiti da maggiori dettagli su cosa viene restituito esattamente nella risposta.

Riepilogo della sintassi del parametro Fields

Il formato del valore del parametro di richiesta fields si basa liberamente sulla sintassi XPath. La sintassi supportata è riassunta di seguito e altri esempi sono forniti nella sezione successiva.

• Utilizza un elenco separato da virgole per selezionare più campi.

• Utilizza a/b per selezionare un campo b nidificato all'interno del campo a; utilizza a/b/c per selezionare un campo c nidificato all'interno di b.

• Utilizza un selettore secondario per richiedere un insieme di sottocampi specifici di array o oggetti inserendo le espressioni tra parentesi "( )".

  Ad esempio: fields=advertisers(advertiserId,generalConfig/domainUrl) restituisce solo l'ID inserzionista e l'URL del dominio per ogni elemento nell'array degli inserzionisti. Puoi anche specificare un singolo sottocampo, dove fields=advertisers(advertiserId) è equivalente a fields=advertisers/advertiserId.

Altri esempi di utilizzo del parametro fields

Gli esempi riportati di seguito includono descrizioni dell'effetto del valore del parametro fields sulla risposta.

Nota: come per tutti i valori dei parametri di query, il valore del parametro fields deve essere codificato in URL. Per una maggiore leggibilità, gli esempi in questo documento omettono la codifica.

Identifica i campi che vuoi che vengano restituiti o effettua selezioni di campi.

Il valore del parametro di richiesta fields è un elenco di campi separati da virgole e ciascun campo è specificato in base alla radice della risposta. Pertanto, se stai eseguendo un'operazione list, la risposta è una raccolta e in genere include un array di risorse. Se stai eseguendo un'operazione che restituisce una singola risorsa, i campi vengono specificati in base a quella risorsa. Se il campo selezionato è (o fa parte di) un array, il server restituisce la parte selezionata di tutti gli elementi dell'array.

Ecco alcuni esempi a livello di raccolta:

Esempio	Effetto
advertisers	Restituisce tutti gli elementi nell'array advertisers, inclusi tutti i campi di ogni elemento, ma nessun altro campo.
advertisers,nextPageToken	Restituisce sia il campo nextPageToken sia tutti gli elementi dell'array advertisers.
advertisers/advertiserId	Restituisce solo advertiserId per tutti gli elementi dell'array advertisers. Ogni volta che viene restituito un campo nidificato, la risposta include gli oggetti principali che lo contengono. I campi principali non includono altri campi secondari, a meno che non siano selezionati anche esplicitamente.
advertisers/generalConfig/domainUrl	Restituisce il campo domainUrl per l'oggetto generalConfig, che è nidificato nell'array advertisers.

Ecco alcuni esempi a livello di risorsa:

Esempio	Effetto
advertiserId	Restituisce il campo advertiserId della risorsa richiesta.
generalConfig/domainUrl	Restituisce il campo domainUrl per l'oggetto generalConfig nella risorsa richiesta.

Richiedi solo parti di campi specifici utilizzando le sottoselezioni.

Per impostazione predefinita, se la richiesta specifica campi specifici, il server restituisce gli oggetti o gli elementi dell'array nella loro interezza. Puoi specificare una risposta che includa solo determinati campi secondari. A tale scopo, utilizza la sintassi di selezione secondaria "( )", come nell'esempio seguente.

Esempio	Effetto
advertisers(advertiserId,generalConfig/domainUrl)	Restituisce solo i valori di advertiserId e generalConfigdomainUrl per ogni elemento nell'array advertisers.

Gestione delle risposte parziali

Dopo che un server ha elaborato una richiesta valida che include il parametro di query fields, restituisce un codice di stato HTTP 200 OK insieme ai dati richiesti. Se il parametro di query fields presenta un errore o non è valido, il server restituisce un codice di stato HTTP 400 Bad Request, insieme a un messaggio di errore che indica il problema con la selezione dei campi (ad esempio, "Invalid field selection a/b").

Nota: per le API che supportano i parametri di query per la paginazione dei dati (maxResults e nextPageToken, ad esempio), utilizza questi parametri per ridurre i risultati di ogni query a dimensioni gestibili. In caso contrario, i miglioramenti del rendimento possibili con una risposta parziale potrebbero non essere realizzati.