Migliorare le prestazioni

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

Compressione con gzip

Un modo semplice e comodo per ridurre la larghezza di banda necessaria per ogni richiesta è attivare la compressione gzip. Anche se ciò richiede più tempo di CPU per decomprimere i risultati, il compromesso con i costi di rete lo rende solitamente vantaggioso.

Per ricevere una risposta con codifica gzip devi eseguire 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 di risorse parziali

Un altro modo per migliorare il rendimento delle tue chiamate API consiste nel richiedere solo la parte dei dati che ti interessano. Ciò consente alla tua applicazione di evitare il trasferimento, l'analisi e l'archiviazione di campi non necessari, in modo da poter utilizzare risorse come la rete, la CPU e la 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 di ricevere 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 (fittizia).

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

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

Risposta completa alle risorse: i dati completi sulle risorse 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 di cui sopra, il server restituisce una risposta contenente solo le informazioni relative al tipo, insieme a un array di elementi essenziali che include solo informazioni su titoli e caratteristiche di lunghezza HTML 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 padre.

La prossima parte dei dettagli su come formattare il parametro fields è seguita da ulteriori dettagli su cosa viene restituito esattamente nella risposta.

Riepilogo della sintassi dei parametri dei campi

Il formato del valore del parametro di richiesta fields è generico sulla sintassi XPath. La sintassi supportata è riassunta di seguito e esempi aggiuntivi sono forniti nella seguente sezione.

  • Utilizza un elenco separato da virgole per selezionare più campi.
  • Utilizza a/b per selezionare un campo b nidificato all'interno del campo a; usa a/b/c per selezionare un campo c nidificato all'interno di b.

    Eccezione: per le risposte dell'API che utilizzano i wrapper "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. È sufficiente utilizzare una specifica di fields come a/b.

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

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

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

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

Altri esempi di utilizzo del parametro dei campi

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

Nota: come per tutti i valori dei parametri di ricerca, il valore 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 effettua una selezione dei campi.
Il valore parametro di richiesta fields è un elenco di campi separati da virgole e ogni campo viene specificato in relazione alla radice della risposta. Pertanto, se esegui 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 sono specificati in relazione alla 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 nella matrice di elementi, inclusi tutti i campi di ogni elemento, ma nessun altro campo.
etag,items Restituisce sia il campo etag che tutti gli elementi nella matrice di elementi.
items/title Restituisce solo il campo title per tutti gli elementi nella matrice dell'elemento.

Ogni volta che viene restituito un campo nidificato, la risposta include gli oggetti principali che li 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 che sono figli 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 le parti di campi specifici utilizzando le sottosezioni.
Per impostazione predefinita, se la tua richiesta specifica alcuni campi, il server restituisce per intero gli oggetti o gli elementi dell'array. Puoi specificare una risposta che includa solo alcuni campi secondari. A tale scopo, utilizza la sintassi di sottoselezione "( )", come nell'esempio di seguito.
Esempio Effetto
items(title,author/uri) Restituisce solo i valori di title e di uri dell'autore per ogni elemento nella matrice di elementi.

Gestione delle risposte parziali

Dopo che un server ha elaborato 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 presenta un errore o non è valido, il server restituisce un codice di stato HTTP 400 Bad Request e un messaggio di errore che indica all'utente i problemi di selezione dei campi (ad esempio "Invalid field selection a/b").

Ecco un esempio di risposta parziale mostrato nella sezione introduttiva di cui 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 questi parametri per ridurre i risultati di ogni query a una dimensione gestibile. In caso contrario, i miglioramenti di prestazioni possibili con una risposta parziale potrebbero non essere ottenuti.