Ottimizzare le prestazioni

Questo documento illustra alcune tecniche che puoi utilizzare per migliorare le prestazioni dell'applicazione. In alcuni casi, vengono utilizzati esempi di altre API o di API generiche per illustrare le idee presentate. Tuttavia, gli stessi concetti sono applicabili all'API Google Ad Experience Report.

Compressione utilizzando gzip

Un modo semplice e comodo per ridurre la larghezza di banda necessaria per ogni richiesta è attivare la compressione gzip. Sebbene questo richieda più tempo di CPU per decomprimere i risultati, in genere è vantaggioso ottenere un compromesso con i costi di rete.

Per ricevere una risposta con codifica gzip devi svolgere due operazioni: impostare un'intestazione Accept-Encoding e modificare lo user agent in modo che contenga la stringa gzip. Ecco un esempio di intestazioni HTTP formattate correttamente per attivare la compressione gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)

Utilizzo delle risorse parziali

Un altro modo per migliorare le prestazioni delle chiamate API consiste nel richiedere soltanto la parte di dati che ti interessa. Ciò consente alla tua applicazione di evitare di trasferire, analizzare e archiviare i campi non necessari, in modo da poter utilizzare le risorse come rete, CPU e memoria in modo più efficiente.

Risposta parziale

Per impostazione predefinita, il server restituisce la rappresentazione completa di una risorsa dopo l'elaborazione delle richieste. Per ottenere prestazioni migliori, puoi chiedere al server di inviare solo i campi di cui hai davvero bisogno e ottenere invece una risposta parziale.

Per richiedere una risposta parziale, utilizza il parametro di richiesta fields per specificare i campi da restituire. Puoi utilizzarlo per qualsiasi richiesta che restituisca dati di risposta.

Esempio

L'esempio seguente mostra l'utilizzo del parametro fields con un'API "Demo" generica (di fantasia).

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

https://www.googleapis.com/demo/v1

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

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

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

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Risposta parziale: in risposta alla richiesta riportata sopra, il server restituisce una risposta contenente solo le informazioni del tipo insieme a un array di elementi essenziali che include solo il titolo HTML e le informazioni sulla lunghezza di ogni elemento.

200 OK
{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Tieni presente che la risposta è un oggetto JSON che include solo i campi selezionati e i relativi oggetti padre.

Più avanti troverai informazioni dettagliate su come formattare il parametro fields, seguito da maggiori dettagli sul contenuto esatto della risposta.

Riepilogo della sintassi del parametro dei campi

Il formato del valore del parametro di richiesta fields è liberamente basato sulla sintassi XPath. La sintassi supportata è riepilogativa di seguito e ulteriori esempi sono forniti nella sezione seguente.

  • 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.

    Eccezione: per le risposte API che utilizzano "wrapper" dei dati, in cui la risposta è nidificata all'interno di un oggetto data simile a data: { ... }, non includere "data" nella specifica fields. L'inclusione dell'oggetto dati con una specifica dei campi come data/a/b causa un errore. Devi solo utilizzare una specifica fields come a/b.

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

    Ad esempio: fields=items(id,author/email) restituisce solo l'ID articolo e l'indirizzo email dell'autore per ogni elemento nell'array di articoli. Puoi anche specificare un singolo sottocampo, dove fields=items(id) equivale a fields=items/id.

  • Se necessario, utilizza i caratteri jolly nelle selezioni di campi.

    Ad esempio: fields=items/pagemap/* seleziona tutti gli oggetti in una mappa pagine.

Altri esempi di utilizzo del parametro campi

Gli esempi di seguito includono descrizioni di come il valore del parametro fields influisce sulla risposta.

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

Identifica i campi da restituire o seleziona campi selezionati.
Il valore del parametro di richiesta fields è un elenco di campi separato da virgole e ogni campo è specificato in relazione alla radice della risposta. Pertanto, se stai eseguendo un'operazione list, la risposta è una raccolta e generalmente include un array di risorse. Se stai eseguendo un'operazione che restituisce una singola risorsa, i campi vengono specificati per quella risorsa. Se il campo selezionato è (o fa parte) di un array, il server restituisce la parte selezionata di tutti gli elementi nell'array.

Ecco alcuni esempi a livello di raccolta:
Esempi Effetto
items Restituisce tutti gli elementi nell'array di elementi, inclusi tutti i campi in ogni elemento, ma nessun altro campo.
etag,items Restituisce sia il campo etag che tutti gli elementi nell'array di elementi.
items/title Restituisce solo il campo title per tutti gli elementi nell'array di articoli.

Quando viene restituito un campo nidificato, la risposta include gli oggetti principali che le contengono. I campi principali non includono altri campi secondari, a meno che non siano selezionati esplicitamente.
context/facets/label Restituisce solo il campo label per tutti i membri dell'array facets, che è a sua volta nidificato sotto l'oggetto context.
items/pagemap/*/title Per ogni elemento nell'array di articoli, restituisce solo il campo title (se presente) di tutti gli oggetti secondari di pagemap.

Ecco alcuni esempi a livello di risorsa:
Esempi Effetto
title Restituisce il campo title della risorsa richiesta.
author/uri Restituisce il sottocampo uri dell'oggetto author nella risorsa richiesta.
links/*/href
 Restituisce il campo href di tutti gli oggetti secondari di links.
Richiedi solo parti di campi specifici utilizzando le selezioni secondarie.
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 alcuni sottocampi. A tale scopo, utilizza la sintassi di sottoselezione "( )", come nell'esempio riportato di seguito.
Esempio Effetto
items(title,author/uri) Restituisce solo i valori di title e uri di autore per ogni elemento nell'array di elementi.

Gestione delle risposte parziali

Dopo che un server elabora una richiesta valida che include il parametro di ricerca fields, restituisce un codice di stato HTTP 200 OK, insieme ai dati richiesti. Se il parametro di ricerca fields contiene un errore o non è altrimenti valido, il server restituisce un codice di stato HTTP 400 Bad Request e un messaggio di errore che indica all'utente che cosa era sbagliato nella selezione dei campi (ad es. "Invalid field selection a/b").

Ecco un esempio di risposta parziale mostrato nella sezione introduttiva riportata sopra. La richiesta utilizza il parametro fields per specificare i campi da restituire.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

La risposta parziale ha il seguente aspetto:

200 OK
{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Nota: per le API che supportano i parametri di ricerca per l'impaginazione dei dati (ad esempio, maxResults e nextPageToken), utilizza tali parametri per ridurre i risultati di ogni query a una dimensione gestibile. In caso contrario, i miglioramenti delle prestazioni possibili con una risposta parziale potrebbero non essere realizzati.