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 campob
nidificato all'interno del campoa
; usaa/b/c
per selezionare un campoc
nidificato all'interno dib
.
Eccezione: per le risposte dell'API che utilizzano i wrapper "dati", in cui la risposta è nidificata all'interno di un oggetto
data
simile adata: { ... }
, non includere "data
" nella specificafields
. L'inclusione dell'oggetto dati con una specifica dei campi comedata/a/b
causa un errore. È sufficiente utilizzare una specifica difields
comea/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, dovefields=items(id)
equivale afields=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'arrayfacets
, che è a sua volta nidificato sotto l'oggettocontext
.items/pagemap/*/title
Per ogni elemento nell'array di articoli, restituisce solo il campo title
(se presente) di tutti gli oggetti che sono figli 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 secondari dilinks
. - 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 diuri
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.