Questo documento illustra alcune tecniche che puoi utilizzare per migliorare il rendimento 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 Google Drive.
Compressione con gzip
Un modo semplice e pratico per ridurre la larghezza di banda necessaria per ogni richiesta è attivare la compressione gzip. Sebbene questo richieda tempo CPU aggiuntivo per decomprimere i risultati, il trade-off con i costi di rete di solito lo rende molto utile.
Per ricevere una risposta con codifica gzip, devi fare due cose: impostare un'intestazione Accept-Encoding e modificare l'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)
Lavorare con risorse parziali
Un altro modo per migliorare le prestazioni delle chiamate API è inviare e ricevere solo la parte di dati che ti interessa. In questo modo, l'applicazione evita di trasferire, analizzare e memorizzare i campi non necessari, in modo da poter utilizzare le risorse, tra cui rete, CPU e memoria, in modo più efficiente.
Esistono due tipi di richieste parziali:
- Risposta parziale: una richiesta in cui specifichi i campi da includere nella risposta (utilizza il parametro di richiesta
fields). - Patch: una richiesta di aggiornamento in cui invii solo i campi che vuoi modificare (utilizza il verbo HTTP
PATCH).
Ulteriori dettagli su come effettuare richieste parziali sono disponibili nelle sezioni seguenti.
Risposta parziale
Per impostazione predefinita, il server restituisce la rappresentazione completa di una risorsa dopo aver elaborato le richieste. Per migliorare le prestazioni, puoi chiedere al server di inviare solo i campi di cui hai effettivamente bisogno e ricevere una risposta parziale.
Per richiedere una risposta parziale, utilizza il parametro di richiesta fields per specificare i campi che vuoi che vengano restituiti. Puoi utilizzare questo parametro con qualsiasi richiesta che restituisce dati di risposta.
Tieni presente che il parametro fields influisce solo sui dati di risposta e non sui dati che devi inviare, se presenti. Per ridurre la quantità di dati inviati durante la modifica delle risorse, utilizza una richiesta patch.
Esempio
Patch (aggiornamento parziale)
Puoi anche evitare di inviare dati non necessari quando modifichi le risorse. Per inviare i dati aggiornati solo per i campi specifici che stai modificando, utilizza il verbo HTTP PATCH. La semantica delle patch descritta in questo documento è diversa (e più semplice) rispetto a quella dell'implementazione precedente di GData dell'aggiornamento parziale.
L'esempio breve riportato di seguito mostra come l'utilizzo di patch riduce al minimo i dati da inviare per apportare un piccolo aggiornamento.
Esempio
Gestione della risposta a un patch
Dopo aver elaborato una richiesta di patch valida, l'API restituisce un codice di risposta HTTP 200 OK insieme alla rappresentazione completa della risorsa modificata. Se l'API utilizza gli ETag, il server aggiorna i valori ETag quando elabora correttamente una richiesta di patch, come avviene con PUT.
La richiesta di patch restituisce l'intera rappresentazione della risorsa, a meno che non utilizzi il parametro fields per ridurre la quantità di dati restituiti.
Se una richiesta di patch genera un nuovo stato della risorsa non valido dal punto di vista sintattico o semantico, il server restituisce un codice di stato HTTP 400 Bad Request o 422 Unprocessable Entity e lo stato della risorsa rimane invariato. Ad esempio, se provi a eliminare il valore di un campo obbligatorio, il server restituisce un errore.
Notazione alternativa quando il verbo HTTP PATCH non è supportato
Se il firewall non consente le richieste HTTP PATCH, effettua una richiesta HTTP POST e imposta l'intestazione di override su PATCH, come mostrato di seguito:
POST https://www.googleapis.com/... X-HTTP-Method-Override: PATCH ...
Differenza tra patch e aggiornamento
In pratica, quando invii i dati per una richiesta di aggiornamento che utilizza il verbo HTTP PUT, devi inviare solo i campi obbligatori o facoltativi. Se invii valori per i campi impostati dal server, questi vengono ignorati. Anche se potrebbe sembrare un altro modo per eseguire un aggiornamento parziale, questo approccio presenta alcune limitazioni. Con gli aggiornamenti che utilizzano il verbo HTTP PUT, la richiesta non va a buon fine se non fornisci i parametri obbligatori e vengono cancellati i dati impostati in precedenza se non fornisci i parametri facoltativi.
Per questo motivo, è molto più sicuro utilizzare la patch. Fornisci i dati solo per i campi che vuoi modificare; i campi omessi non vengono cancellati. L'unica eccezione a questa regola si verifica con elementi o array ripetuti: se li ometti tutti, rimangono invariati; se ne fornisci uno, l'intero insieme viene sostituito con quello che fornisci.
Richieste batch
Questo documento mostra come raggruppare le chiamate API per ridurre il numero di connessioni HTTP che il tuo client deve effettuare.
Questo documento riguarda nello specifico l'invio di una richiesta batch inviando una richiesta HTTP. Se invece utilizzi una libreria client Google per inviare una richiesta batch, consulta la documentazione della libreria client.
Panoramica
Ogni connessione HTTP stabilita dal client comporta un determinato carico. L'API Google Drive supporta il raggruppamento, per consentire al client di inserire più chiamate API in un'unica richiesta HTTP.
Esempi di situazioni in cui potresti voler utilizzare il raggruppamento:
- Recupero dei metadati per un numero elevato di file.
- Aggiornamento collettivo di metadati o proprietà.
- Modificare le autorizzazioni per un numero elevato di file, ad esempio l'aggiunta di un nuovo utente o gruppo.
- Sincronizzazione dei dati del client locale per la prima volta o dopo essere stato offline per un periodo di tempo prolungato.
In ogni caso, anziché inviare ogni chiamata separatamente, puoi raggrupparle in un'unica richiesta HTTP. Tutte le richieste interne devono essere indirizzate alla stessa API Google.
Puoi effettuare fino a 100 chiamate in una singola richiesta batch. Se devi effettuare più chiamate, utilizza più richieste collettive.
Nota: il sistema batch per l'API Google Drive utilizza la stessa sintassi del sistema di elaborazione batch OData, ma la semantica è diversa.
Ulteriori vincoli includono:
- Le richieste collettive con più di 100 chiamate potrebbero causare un errore.
- Esiste un limite di 8000 caratteri per la lunghezza dell'URL di ogni richiesta interna.
- Google Drive non supporta le operazioni collettive per i contenuti multimediali, né per il caricamento o il download né per l'esportazione dei file.
Dettagli del batch
Una richiesta batch è composta da più chiamate API combinate in un'unica richiesta HTTP, che può essere inviata all'batchPath specificato nel documento di rilevamento API. Il percorso predefinito è /batch/api_name/api_version. Questa sezione descrive la sintassi batch in dettaglio; di seguito è riportato un esempio.
Nota: un insieme di n richieste raggruppate viene conteggiato ai fini del limite di utilizzo come n richieste, non come una singola richiesta. La richiesta batch viene suddivisa in un insieme di richieste prima dell'elaborazione.
Formato di una richiesta batch
Una richiesta batch è una singola richiesta HTTP standard contenente più chiamate all'API Google Drive, che utilizza il tipo di contenuto multipart/mixed. All'interno di questa richiesta HTTP principale, ciascuna delle parti contiene una richiesta HTTP nidificata.
Ogni parte inizia con la propria intestazione HTTP Content-Type: application/http. Può anche avere un'intestazione Content-ID facoltativa. Tuttavia, le intestazioni della parte servono solo a contrassegnare l'inizio della parte e sono separate dalla richiesta nidificata. Dopo che il server ha scompattato la richiesta batch in richieste separate, le intestazioni delle parti vengono ignorate.
Il corpo di ogni parte è una richiesta HTTP completa, con verbo, URL, intestazioni e corpo. La richiesta HTTP deve contenere solo la parte di percorso dell'URL; gli URL completi non sono consentiti nelle richieste collettive.
Le intestazioni HTTP per la richiesta batch esterna, ad eccezione delle intestazioni Content- come Content-Type, si applicano a ogni richiesta del batch. Se specifichi una determinata intestazione HTTP sia nella richiesta esterna che in una singola chiamata, il valore dell'intestazione della singola chiamata sostituisce il valore dell'intestazione della richiesta batch esterna. Le intestazioni di una singola chiamata si applicano solo a quella chiamata.
Ad esempio, se fornisci un'intestazione Authorization per una chiamata specifica, questa intestazione si applica solo a quella chiamata. Se fornisci un'intestazione Authorization per la richiesta esterna, questa intestazione si applica a tutte le singole chiamate, a meno che non vengano sostituite con intestazioni Authorization proprie.
Quando il server riceve la richiesta raggruppata, applica i parametri di query e le intestazioni della richiesta esterna (se appropriato) a ogni parte e poi tratta ogni parte come se fosse una richiesta HTTP separata.
Risposta a una richiesta batch
La risposta del server è una singola risposta HTTP standard con un tipo di contenuto multipart/mixed; ogni parte è la risposta a una delle richieste nella richiesta raggruppata, nello stesso ordine delle richieste.
Come le parti della richiesta, ogni parte della risposta contiene una risposta HTTP completa, inclusi un codice di stato, le intestazioni e il corpo. Come le parti nella richiesta, ogni parte della risposta è preceduta da un'intestazione Content-Type che ne indica l'inizio.
Se una determinata parte della richiesta aveva un'intestazione Content-ID, la parte corrispondente della risposta ha un'intestazione Content-ID corrispondente, con il valore originale preceduto dalla stringa response-, come mostrato nell'esempio seguente.
Nota: il server potrebbe eseguire le chiamate in qualsiasi ordine. Non aspettarti che vengano eseguiti nell'ordine in cui li hai specificati. Se vuoi assicurarti che due chiamate vengano eseguite in un determinato ordine, non puoi inviarle in una singola richiesta; invia invece la prima da sola, quindi attendi la risposta alla prima prima di inviare la seconda.
Esempio
L'esempio seguente mostra l'utilizzo del raggruppamento con l'API Google Drive.
Esempio di richiesta batch
POST https://www.googleapis.com/batch/drive/v3 Accept-Encoding: gzip User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip) Content-Type: multipart/mixed; boundary=END_OF_PART Content-Length: 963--END_OF_PART Content-Length: 337 Content-Type: application/http content-id: 1 content-transfer-encoding: binary
POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id Authorization: Bearer authorization_token Content-Length: 70 Content-Type: application/json; charset=UTF-8
{ "emailAddress":"example@appsrocks.com", "role":"writer", "type":"user" } --END_OF_PART Content-Length: 353 Content-Type: application/http content-id: 2 content-transfer-encoding: binary
POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false Authorization: Bearer authorization_token Content-Length: 58 Content-Type: application/json; charset=UTF-8
{ "domain":"appsrocks.com", "role":"reader", "type":"domain" } --END_OF_PART--
Esempio di risposta batch
Questa è la risposta alla richiesta di esempio nella sezione precedente.
HTTP/1.1 200 OK Alt-Svc: quic=":443"; p="1"; ma=604800 Server: GSE Alternate-Protocol: 443:quic,p=1 X-Frame-Options: SAMEORIGIN Content-Encoding: gzip X-XSS-Protection: 1; mode=block Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk Transfer-Encoding: chunked X-Content-Type-Options: nosniff Date: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Vary: X-Origin Vary: Origin Expires: Fri, 13 Nov 2015 19:28:59 GMT--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-1
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35
{ "id": "12218244892818058021i" }
--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-2
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35
{ "id": "04109509152946699072k" }
--batch_6VIxXCQbJoQ_AATxy_GgFUk--
Restituire campi specifici dalla richiesta
Se non specifichi il parametro fields, il server restituisce un insieme predefinito di campi specifici per il metodo. Ad esempio, il metodo files.list restituisce solo i campi kind, id, name e
mimeType.
I campi predefiniti restituiti potrebbero non essere quelli di cui hai bisogno. Se vuoi specificare i campi da restituire nella risposta, utilizza il parametro
sistema fields.
Per ulteriori informazioni, consulta Restituire campi specifici.
Per tutti i metodi delle risorse about, comments (escluso delete) e replies (escluso delete), devi impostare il parametro fields. Questi metodi non restituiscono un insieme predefinito di campi.