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 di altre API o di API generiche. Tuttavia, gli stessi concetti si applicano all'API Resource Manager.
Compressione con gzip
Un modo semplice e comodo per ridurre la larghezza di banda necessaria per ciascuna richiesta è attivare la compressione gzip. Anche se questo richiede più tempo di CPU per decomprimere i risultati, il compromesso con i costi di rete di solito rende molto utile.
Per ricevere una risposta con codifica gzip devi fare due cose: impostare un'intestazione Accept-Encoding
e modificare il tuo user agent per contenere la stringa gzip
. Ecco un esempio di intestazioni HTTP formattate correttamente per l'attivazione della 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 porzione di dati che ti interessa. Ciò consente alla tua applicazione di evitare il trasferimento, l'analisi e l'archiviazione di campi non necessari, in modo da poter utilizzare in modo più efficiente risorse come rete, CPU e memoria.
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 necessari e di 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 un'API generico (di fantasia; demo).
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 sono i seguenti, 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 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 riportata sopra, il server invia una risposta contenente solo le informazioni relative al tipo, insieme a un array di elementi essenziali che include solo titolo HTML e informazioni sulle caratteristiche della lunghezza di ciascun 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.
Ulteriori informazioni su come formattare il parametro fields
verranno fornite in seguito, seguito da ulteriori dettagli su ciò che viene restituito esattamente nella risposta.
Riepilogo della sintassi dei parametri dei campi
Il formato del valore del parametro di richiesta fields
è a basso orientamento basato sulla sintassi XPath. La sintassi supportata è riepilogata di seguito, mentre ulteriori esempi sono riportati nella sezione seguente.
- Utilizza un elenco separato da virgole per selezionare più campi.
- Utilizza
a/b
per selezionare un campob
nidificato all'interno del campoa
; utilizzaa/b/c
per selezionare un campoc
nidificato all'interno dib
.
Eccezione: per le risposte API che utilizzano "wrapper". L'inclusione dell'oggetto dati con una specifica dei campi come
data/a/b
causa un errore. È sufficiente utilizzare una specificafields
comea/b
. - Utilizza un selettore secondario per richiedere un insieme di sottocampi specifici di array o di oggetti posizionando le espressioni tra parentesi "
( )
".Ad esempio:
fields=items(id,author/email)
restituisce solo l'ID elemento e l'email dell'autore per ogni elemento nell'array di elementi. Puoi anche specificare un singolo sottocampo, in cuifields=items(id)
equivale afields=items/id
. - Se necessario, utilizza i caratteri jolly nelle selezioni dei campi.
Ad esempio:
fields=items/pagemap/*
seleziona tutti gli oggetti in una mappa di pagina.
Altri esempi di utilizzo del parametro campi
Gli esempi 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 del parametro fields
deve essere codificato nell'URL. Per una migliore leggibilità, negli esempi in questo documento non viene codificata la codifica.
- Identifica i campi da restituire o seleziona i campi.
- Il valore parametro di richiesta
fields
è un elenco di campi separato da virgole e ogni campo è specificato in relazione alla radice della risposta. Di conseguenza, se esegui 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 relazione a tale 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 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 elementi.
Ogni volta che viene restituito un campo nidificato, la risposta include gli oggetti principali 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'arrayfacets
, che a sua volta è nidificato sotto l'oggettocontext
.items/pagemap/*/title
Per ogni elemento nell'array di elementi, restituisce solo il campo title
(se presente) di tutti gli oggetti che sono secondari dipagemap
.
Ecco alcuni esempi a livello di risorsa:
Esempi Effetto title
Restituisce il campo title
della risorsa richiesta.author/uri
Restituisce il sottocampo uri
dell'oggettoauthor
nella risorsa richiesta.links/*/href
Restituisce il campo href
di tutti gli oggetti che sono secondari dilinks
. - Richiedi solo le parti di campi specifici utilizzando le sottosezioni.
- Per impostazione predefinita, se la richiesta specifica campi specifici, il server restituisce gli oggetti o gli elementi array nella loro interezza. Puoi specificare una risposta che includa solo determinati sottocampi. Per farlo, utilizza la sintassi"
( )
"sottoselezione, come nell'esempio riportato di seguito.Esempio Effetto items(title,author/uri)
Restituisce solo i valori di title
euri
di autore per ogni elemento nell'array di elementi.
Gestione delle risposte parziali
Dopo aver elaborato una richiesta valida che include il parametro di ricerca fields
, il server restituisce un codice di stato HTTP 200 OK
insieme ai dati richiesti. Se il parametro di ricerca fields
contiene un errore o non è valido, il server restituisce un codice di stato HTTP 400 Bad Request
e un messaggio di errore che comunica all'utente l'errore nella selezione dei campi (ad esempio, "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 in una dimensione gestibile. In caso contrario, i miglioramenti di rendimento possibili con una risposta parziale potrebbero non essere realizzati.