Migliora le prestazioni

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 ciò richieda ulteriore tempo della CPU per decomprimere i risultati, il compromesso con i costi di rete di solito lo rende molto utile.

Per ricevere una risposta codificata con gzip, devi fare due cose: impostare un'intestazione Accept-Encoding e modificare lo user agent in modo che contenga la stringa gzip. Ecco un esempio di intestazioni HTTP formate correttamente per attivare la compressione gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)

Utilizzare risorse parziali

Un altro modo per migliorare il rendimento delle chiamate API consiste nell'inviare e ricevere solo la parte dei dati che ti interessa. In questo modo, l'applicazione evita di trasferire, analizzare e archiviare 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).

Nelle sezioni seguenti vengono forniti ulteriori dettagli sulla creazione di richieste parziali.

Risposta parziale

Per impostazione predefinita, il server restituisce la rappresentazione completa di una risorsa dopo l'elaborazione delle richieste. Per prestazioni migliori, puoi chiedere al server di inviare solo i campi di cui hai realmente bisogno e ricevere invece 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, 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 durante la modifica delle risorse. Per inviare 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 GData precedente dell'aggiornamento parziale.

Il breve esempio 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 una patch

Dopo aver elaborato una richiesta patch valida, l'API restituisce un codice di risposta HTTP 200 OK insieme alla rappresentazione completa della risorsa modificata. Se le ETag vengono utilizzate dall'API, il server aggiorna i valori ETag quando elabora correttamente una richiesta patch, proprio come fa con PUT.

La richiesta di patch restituisce l'intera rappresentazione della risorsa, a meno che tu non utilizzi il parametro fields per ridurre la quantità di dati restituiti.

Se una richiesta di patch genera un nuovo stato della risorsa sintatticamente o semanticamente non valido, 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 tenti di 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, esegui 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 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 questo 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 cancella 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 che ometti non vengono cancellati. L'unica eccezione a questa regola si verifica con gli elementi ripetuti o gli array: se li ometti tutti, rimangono invariati; se ne fornisci uno qualsiasi, l'intero insieme viene sostituito con l'insieme che fornisci.

Richieste batch

Questo documento mostra come effettuare chiamate API in batch 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 overhead. L'API Google Drive supporta il raggruppamento in batch per consentire al client di inserire più chiamate API in una singola richiesta HTTP.

Esempi di situazioni in cui potresti voler utilizzare il raggruppamento in batch:

  • 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 aggiungendo un nuovo utente o gruppo.
  • Sincronizzazione dei dati del client locale per la prima volta o dopo un periodo di inattività 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 di Google.

Hai un limite di 100 chiamate in una singola richiesta batch. Se devi effettuare più chiamate, utilizza più richieste batch.

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 batch con più di 100 chiamate potrebbero causare un errore.
  • Esiste un limite di 8000 caratteri per la lunghezza dell'URL per ogni richiesta interna.
  • Google Drive non supporta le operazioni batch per i contenuti multimediali, né per il caricamento o il download, né per l'esportazione dei file.

Dettagli batch

Una richiesta batch è composta da più chiamate API combinate in un'unica richiesta HTTP, che può essere inviata al 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 in batch 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 scomposto 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 batch.

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 esegue l'override del 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 Autorizzazione per una chiamata specifica, questa intestazione si applica solo a quella chiamata. Se fornisci un'intestazione Autorizzazione per la richiesta esterna, questa intestazione si applica a tutte le singole chiamate, a meno che non eseguano l'override con intestazioni Autorizzazione proprie.

Quando il server riceve la richiesta raggruppata in batch, applica i parametri di query e le intestazioni della richiesta esterna (se opportuno) 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 in batch, 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 della 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 eseguite nell'ordine in cui le hai specificate. 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 prima di inviare la seconda.

Esempio

L'esempio seguente mostra l'utilizzo del raggruppamento in batch 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--

Restituisce 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 fields parametro di sistema. Per maggiori informazioni, vedi 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.