Ottimizzazione delle prestazioni

Compressione con gzip

Un modo semplice e pratico per ridurre la larghezza di banda necessaria per ogni richiesta è attivare la compressione gzip. Sebbene ciò richieda ulteriore tempo della CPU per decomprimere i risultati, il compromesso con i costi di rete di solito lo rende molto utile.

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

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

Utilizzare risorse parziali

Un altro modo per migliorare il rendimento delle chiamate API consiste nel richiedere solo la parte dei dati che ti interessa. In questo modo, l'applicazione evita di trasferire, analizzare e archiviare campi non necessari, in modo da poter utilizzare le risorse, tra cui 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 prestazioni migliori, puoi chiedere al server di inviare solo i campi di cui hai realmente bisogno e ricevere invece una risposta parziale.

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

Esempio

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

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

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

Risposta completa della risorsa:i dati completi della risorsa includono i seguenti campi, oltre 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 una risposta parziale:la seguente richiesta per la stessa risorsa utilizza il parametro fields per ridurre significativamente la quantità di dati restituiti.

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

Risposta parziale:in risposta alla richiesta precedente, il server invia una risposta che contiene solo le informazioni sul tipo insieme a un array di elementi ridotto che include solo le informazioni sul titolo HTML e sulla lunghezza in 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 principali contenitori.

Di seguito vengono forniti i dettagli su come formattare il parametro fields, seguiti da ulteriori 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 vagamente sulla sintassi XPath. La sintassi supportata è riassunta di seguito e nella sezione successiva vengono forniti ulteriori esempi.

• 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 "data", 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. Utilizza invece una specifica fields come a/b.

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

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

• Utilizza i caratteri jolly nelle selezioni dei campi, se necessario.

  Ad esempio, fields=items/pagemap/* seleziona tutti gli oggetti in una pagemap.

Altri esempi di utilizzo del parametro fields

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

Nota:come per tutti i valori dei parametri di query, 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 che vuoi restituire o effettua selezioni di campi.

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

Ecco alcuni esempi a livello di raccolta:

Esempi	Effetto
items	Restituisce tutti gli elementi dell'array items, inclusi tutti i campi di ogni elemento, ma nessun altro campo.
etag,items	Restituisce sia il campo etag sia tutti gli elementi nell'array items.
items/title	Restituisce solo il campo title per tutti gli elementi dell'array degli elementi. Ogni volta che viene restituito un campo nidificato, la risposta include gli oggetti padre che lo contengono. I campi principali non includono altri campi secondari, a meno che non vengano selezionati esplicitamente.
context/facets/label	Restituisce solo il campo label per tutti i membri dell'array facets, che a sua volta è nidificato nell'oggetto context.
items/pagemap/*/title	Per ogni elemento dell'array items, 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 sotto-campo 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 sotto-selezioni.

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

Esempio	Effetto
items(title,author/uri)	Restituisce solo i valori di title e uri dell'autore per ogni elemento dell'array items.

Gestire le risposte parziali

Dopo che un server elabora 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 all'utente cosa non va nella selezione dei campi (ad esempio, "Invalid field selection a/b").

Ecco l'esempio di risposta parziale mostrato nella sezione introduttiva precedente. 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 è simile alla seguente:

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 query per la paginazione dei dati (ad esempio maxResults e nextPageToken), utilizza questi parametri per ridurre i risultati di ogni query a una dimensione gestibile. In caso contrario, i miglioramenti delle prestazioni possibili con la risposta parziale potrebbero non essere realizzati.