Questo documento illustra alcune tecniche che puoi utilizzare per migliorare le prestazioni della tua applicazione. In alcuni casi, vengono utilizzati esempi di altre API o API generiche per illustrare le idee presentate. Tuttavia, gli stessi concetti sono applicabili all'API Presentazioni Google.
Compressione mediante gzip
Un modo semplice e conveniente per ridurre la larghezza di banda necessaria per ogni richiesta è abilitare la compressione gzip. Sebbene ciò richieda più tempo di CPU per decomprimere i risultati, il compromesso con i costi di rete di solito lo rende molto utile.
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 abilitare la compressione gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)
Utilizzo di risorse parziali
Un altro modo per migliorare le prestazioni delle chiamate API è 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 ottenere prestazioni migliori, puoi chiedere al server di inviare solo i campi di cui hai davvero bisogno e ottenere invece una risposta parziale.
Per richiedere una risposta parziale, utilizza il parametro di richiesta fields
per specificare i campi che devono essere restituiti. Puoi utilizzare questo parametro con qualsiasi richiesta che restituisce dati di risposta.
Esempio
L'esempio seguente mostra l'utilizzo del parametro fields
con una "Demo" generica (fittizia) tramite Google Cloud CLI
o tramite l'API Compute Engine.
Richiesta semplice: questa richiesta GET
HTTP 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 precedente, il server restituisce una risposta contenente solo le informazioni sul tipo insieme a un array di elementi essenziale che include solo il titolo HTML e le informazioni sulle caratteristiche della 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.
Di seguito vengono trattati i dettagli sulla formattazione del parametro fields
, seguiti da ulteriori dettagli su cosa esattamente viene restituito nella risposta.
Riepilogo sintassi dei parametri dei campi
Il formato del valore del parametro di richiesta fields
è basato sulla sintassi XPath. La sintassi supportata è riepilogata di seguito e ulteriori esempi sono forniti 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 dell'API che utilizzano "dati" I wrapper, in cui la risposta è nidificata all'interno di un oggetto
data
simile adata: { ... }
, non includono "data
" nella specificafields
. Se includi l'oggetto dati con una specifica dei campi comedata/a/b
, si verifica un errore. Utilizza invece una specificafields
comea/b
. - Utilizza un sottoselettore per richiedere un insieme di sottocampi specifici di array o oggetti inserendo 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 articoli. Puoi anche specificare un singolo campo secondario, dovefields=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 riportati di seguito includono descrizioni di come il valore parametro fields
influisce sulla risposta.
Nota: come per tutti i valori dei parametri di query, il valore 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 dei campi.
- Il valore parametro di richiesta
fields
è un elenco di campi separati da virgole. Ogni campo è specificato in relazione alla radice della risposta. Pertanto, 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 sono 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 sia il campo etag
sia tutti gli elementi dell'array di elementi.items/title
Restituisce solo il campo title
per tutti gli elementi nell'array di articoli.
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
, a sua volta nidificato sotto l'oggettocontext
.items/pagemap/*/title
Per ogni elemento dell'array di articoli, restituisce solo il campo title
(se presente) di tutti gli oggetti 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 secondari dilinks
. - 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 array nella loro interezza. Puoi specificare una risposta che includa solo alcuni sottocampi. Per farlo utilizzi "
( )
" sintassi di sottoselezione, come nell'esempio riportato di seguito.Esempio Effetto items(title,author/uri)
Restituisce solo i valori di title
e diuri
dell'autore per ogni elemento nell'array di elementi.
Gestione delle 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 qual era il problema nella selezione dei campi (ad esempio, "Invalid field selection a/b"
).
Ecco l'esempio di risposta parziale mostrato nella sezione introduttiva riportata sopra. 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 è 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 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 delle prestazioni possibili con una risposta parziale potrebbero non essere ottenuti.