Questa pagina descrive come effettuare una richiesta di caricamento ripristinabile nell'API Google Foto Library tramite il protocollo REST. Questo protocollo consente di riprendere un'operazione di caricamento dopo che un errore di comunicazione ha interrotto il flusso di dati.
Se sei uno sviluppatore che utilizza librerie client, tieni presente che alcune offrono il supporto nativo per i caricamenti ripristinabili.
Utilizza l'opzione di caricamento ripristinabile se:
- Stai caricando file di grandi dimensioni.
- La probabilità che si verifichino interruzioni di rete o altri errori di trasmissione è elevata (ad esempio se stai caricando un file da un'app mobile).
I caricamenti ripristinabili possono inoltre ridurre l'utilizzo della larghezza di banda in caso di guasto della rete, perché non è necessario riavviare il caricamento di file di grandi dimensioni dall'inizio.
Passaggio 1: avvio di una sessione di caricamento
Avvia una sessione di caricamento ripristinabile inviando una richiesta POST a https://photoslibrary.googleapis.com/v1/uploads. Utilizzando l'URL di caricamento ripristinabile restituito in questa richiesta, carica il file.
La richiesta POST deve includere le seguenti intestazioni:
| Campi intestazione | |
|---|---|
Content-Length |
Impostalo su 0 perché il corpo della richiesta è vuoto. |
X-Goog-Upload-Command |
Da impostare su start. |
X-Goog-Upload-Content-Type |
Impostato sul tipo MIME del file, ad esempio image/jpeg. |
X-Goog-Upload-Protocol |
Da impostare su resumable. |
X-Goog-Upload-Raw-Size |
Imposta il numero totale di byte dei dati del file da trasferire. |
Ecco l'intestazione di una richiesta POST:
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: bytes-of-file
Passaggio 2: salva l'URL della sessione
Se l'esito è positivo, la richiesta POST restituisce un codice di stato HTTP 200 OK, che include la seguente intestazione.
X-Goog-Upload-URL: url-to-make-uploads-to X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes
Il campo di intestazione x-goog-upload-chunk-granularity contiene l'allineamento in byte e la granularità delle dimensioni di tutti i blocchi di dati inviati dal client. Se il caricamento avviene in più blocchi, tutti i caricamenti, tranne l'ultimo, devono essere eseguiti in multipli di questo valore. In altre parole, i byte di caricamento
del file devono essere allineati. Nell'ultimo blocco, puoi caricare i byte rimanenti.
Il campo dell'intestazione X-Goog-Upload-URL contiene un URL univoco che deve essere utilizzato per completare il caricamento tramite tutte le richieste rimanenti. Copia e salva questo URL della sessione ripristinabile, in modo da poterlo utilizzare per le richieste successive.
Passaggio 3: carica il file
Esistono due modi per caricare un file con una sessione ripristinabile:
- In una singola richiesta. Questo approccio è in genere il migliore, perché richiede meno richieste e, di conseguenza, offre prestazioni migliori.
-
In più blocchi. Con questo approccio, i caricamenti vengono effettuati nell'ambito di più richieste, suddividendo i dati. I dati vengono suddivisi in multipli di
x-goog-upload-chunk-granularity. Se necessario, le richieste suddivise possono essere ritentate.Utilizza questo approccio se:
- Devi ridurre la quantità di dati trasferiti in ogni singola richiesta. Questa operazione potrebbe essere necessaria quando esiste un limite di tempo fisso per le singole richieste.
- Devi fornire un indicatore personalizzato che mostri l'avanzamento del caricamento.
- Devi sapere quando è sicuro eliminare i dati.
Richiesta singola
Per caricare il file in una singola richiesta:
- Crea una richiesta
POSTall'URL della sessione ripristinabile. - Aggiungi i dati del file al corpo della richiesta.
Aggiungi le seguenti intestazioni HTTP:
Content-Length: impostato sul numero di byte nel file.X-Goog-Upload-Command: imposta suupload, finalize.
Invia la richiesta.
Se la richiesta di caricamento si interrompe o se ricevi una risposta 5xx, segui la procedura descritta in Riprendere un caricamento interrotto.
Se la richiesta ha esito positivo, riceverai un codice di stato HTTP 200 OK e un token di caricamento nel corpo della risposta.
Crea l'elemento multimediale utilizzando questo token di caricamento.
Più blocchi
Per caricare il file in più blocchi:
- Crea una richiesta
POSTall'URL della sessione ripristinabile. -
Aggiungi i dati del blocco al corpo della richiesta.
Fatta eccezione per il blocco finale che completa il caricamento, crea gli altri blocchi in multipli delle dimensioni accettate dei blocchi. Mantieni le dimensioni del blocco il più possibile in modo che il caricamento sia efficace.
-
Aggiungi le seguenti intestazioni HTTP:
Content-Length: impostato sul numero di byte nel blocco.X-Goog-Upload-Command: imposta suupload. Per l'ultimo blocco, impostalo suupload, finalize.X-Goog-Upload-Offset: impostato sull'offset in cui devono essere scritti i byte. Tieni presente che i byte devono essere caricati in modo seriale. Il primo offset è0.
- Invia la richiesta.
Se la richiesta di caricamento si interrompe o se ricevi una risposta
5xx, segui la procedura descritta in Riprendere un caricamento interrotto. - Ripeti i passaggi precedenti per ogni blocco rimanente del file.
Se la richiesta ha esito positivo, riceverai un codice di stato HTTP 200 OK e un token di caricamento nel corpo della risposta.
Crea l'elemento multimediale utilizzando questo token di caricamento.
Esempio
Richiesta singola
L'esempio seguente mostra una richiesta ripristinabile di caricamento di un file JPEG da 3.039.417 byte in una singola richiesta.
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
La risposta contiene l'URL di caricamento e le dimensioni previste del blocco:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
La richiesta di caricamento finale:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 3039417 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 0 [BYTES 0-4199999]
Più blocchi
L'esempio seguente mostra una richiesta ripristinabile di caricamento di un file JPEG da 3.039.417 byte in più blocchi, utilizzando l'URL di sessione ripristinabile e la granularità delle dimensioni del blocco accettata ottenuta nel passaggio precedente.
Questo esempio utilizza una dimensione del blocco di 262.144 byte restituita nel campo di intestazione x-goog-upload-chunk-granularity al momento dell'inizializzazione della sessione di caricamento. Tieni presente che ogni caricamento contiene byte
in multipli di 262.144.
Inizializza la sessione di caricamento per ricevere l'URL di caricamento e le dimensioni del blocco come descritto nel passaggio precedente:
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
La risposta contiene l'URL di caricamento e le dimensioni previste del blocco:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
Primo blocco:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 0 [BYTES 0-1048575]
Secondo blocco:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 1048576 [BYTES 1048576-2097151]
Ultimo blocco:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 942265 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 2097152 [BYTES 2097152-4200000]
Riprendere un caricamento interrotto
Se la richiesta di caricamento viene interrotta o se ricevi un codice di stato HTTP non 200, invia una query al server per scoprire il completamento del caricamento.
Ecco una richiesta POST all'URL della sessione ripristinabile. X-Goog-Upload-Command
deve essere impostato su query.
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: query
La risposta del server include un codice di stato HTTP 200 OK e le dimensioni attuali del caricamento.
HTTP/1.1 200 OK X-Goog-Upload-Status: active X-Goog-Upload-Size-Received: 100
A quel punto, potrai riprendere il caricamento. Devi riprendere l'offset fornito dal server, a meno che non invii un comando combinato di caricamento e finalizzazione. In tal caso, potrai riprendere anche con un offset pari a 0.
Se nella risposta HTTP del comando di query è presente l'intestazione X-Goog-Upload-Status e il valore non è active, significa che il caricamento è già stato terminato.