Ottimizzare le prestazioni

Questo documento illustra alcune tecniche che puoi utilizzare per migliorare le prestazioni della tua applicazione. In alcuni casi, per illustrare le idee presentate vengono utilizzati esempi tratti da altre API o API generiche. Tuttavia, gli stessi concetti sono validi per l'API Google Classroom.

Compressione mediante gzip

Un modo semplice e pratico 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 di solito ne rende molto utile.

Per ricevere una risposta con codifica gzip, devi eseguire due operazioni: impostare un'intestazione Accept-Encoding e modificare il tuo user agent affinché contenga la stringa gzip. Di seguito è riportato un esempio di intestazioni HTTP formattate correttamente per abilitare 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 solo la porzione di dati che ti interessa. Ciò consente all'applicazione di evitare il trasferimento, l'analisi e l'archiviazione dei campi non necessari, in modo da poter utilizzare 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 migliorare le prestazioni, puoi chiedere al server di inviare solo i campi effettivamente necessari e di ottenere 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 sulla 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, 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 una risposta parziale: la seguente richiesta per questa 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 invia una risposta che contiene solo le informazioni sul tipo insieme a un array di elementi essenziali che include solo il titolo HTML e le informazioni sulla caratteristica di 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 padre che contengono.

Di seguito vengono illustrati i dettagli su come formattare il parametro fields, seguiti 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 si basa a grandi linee sulla sintassi XPath. La sintassi supportata è riassunta di seguito; altri 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 dell'API che utilizzano 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. Usa invece una specifica fields come a/b.
Utilizza un selettore secondario per richiedere un insieme di campi secondari specifici di matrici o oggetti inserendo espressioni tra parentesi "( )".
Ad esempio: fields=items(id,author/email) restituisce solo l'ID articolo e l'email dell'autore per ogni elemento nell'array items. Puoi anche specificare un singolo campo secondario, dove fields=items(id) equivale a fields=items/id.
Se necessario, utilizza caratteri jolly nella selezione dei campi.
Ad esempio: fields=items/pagemap/* seleziona tutti gli oggetti in una mappa di pagine.

Altri esempi di utilizzo del parametro dei campi

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 come URL. Per una migliore leggibilità, gli esempi in questo documento omettono la codifica.

Identifica i campi che vuoi restituire o effettua le selezioni dei campi.

Il valore del parametro di richiesta fields è un elenco di campi separati da virgole e ogni campo viene specificato in base alla radice della risposta. Di conseguenza, 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 vengono specificati in relazione 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:

Esempi	Effetto
`items`	Restituisce tutti gli elementi nell'array di elementi, inclusi tutti i campi di ogni elemento, ma nessun altro campo.
`etag,items`	Restituisce il campo `etag` e tutti gli elementi nell'array di elementi.
`items/title`	Restituisce solo il campo `title` per tutti gli elementi nell'array di elementi. Ogni volta che viene restituito un campo nidificato, la risposta include gli oggetti padre che 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 sotto l'oggetto `context`.
`items/pagemap/*/title`	Per ogni elemento nell'array di elementi, 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 tua 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 sottoselezione "( )", come nell'esempio riportato di seguito.

Esempio	Effetto
`items(title,author/uri)`	Restituisce solo i valori di `title` e `uri` dell'autore per ciascun elemento nell'array 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 query fields contiene un errore o non è valido per altri motivi, il server restituisce un codice di stato HTTP 400 Bad Request e un messaggio di errore che indica all'utente il problema nella selezione dei campi (ad esempio, "Invalid field selection a/b").

Ecco l'esempio di risposta parziale mostrato nella sezione introduttiva sopra riportata. La richiesta utilizza il parametro fields per specificare quali campi restituire.

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

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