In questa pagina viene descritto come effettuare una richiesta di caricamento ripristinabile all'API Raccolta di Google Foto. tramite il protocollo REST. Questo protocollo consente di riprendere un'operazione di caricamento dopo che un errore di comunicazione interrompe il flusso di dati.
Se sei uno sviluppatore che utilizza le librerie client, tieni presente che alcune librerie client offrono un 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 (ad esempio, se carichi un file da un'app mobile).
I caricamenti ripristinabili possono anche ridurre l'utilizzo della larghezza di banda in presenza di una rete in quanto non è necessario riavviare i caricamenti di file di grandi dimensioni partendo da zero.
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. Utilizzo del caricamento ripristinabile
URL restituito in questa richiesta, carica il file.
La richiesta POST deve includere le seguenti intestazioni:
| Campi intestazione | |
|---|---|
Content-Length |
Imposta su 0 perché il corpo della richiesta è vuoto. |
X-Goog-Upload-Command |
Da impostare su start. |
X-Goog-Upload-Content-Type |
Imposta il tipo MIME del file, ad esempio
image/jpeg. |
X-Goog-Upload-Protocol |
Da impostare su resumable. |
X-Goog-Upload-Raw-Size |
Impostato sul numero totale di byte dei dati del file da trasferito. |
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 dei byte
e granularità delle dimensioni per tutti i blocchi di dati inviati dal client. Se il caricamento è
eseguita in più blocchi, tutti i caricamenti, tranne l'ultimo,
deve essere eseguita in multipli di questo valore. ovvero i byte di caricamento del file
devono essere allineati a questo valore. Nell'ultimo blocco puoi caricare i dati rimanenti
byte.
Il campo di 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
ripristinabile, così potrai utilizzarlo 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 è di solito il migliore, perché richiede meno richieste e, di conseguenza, ha prestazioni migliori.
-
In più blocchi. Con questo approccio, i caricamenti vengono effettuati in più richieste, suddividendo i dati. I dati vengono suddivisi in multipli di
x-goog-upload-chunk-granularity. Se necessario, le richieste chunked possono essere ritentate.Utilizza questo approccio se:
- È necessario ridurre la quantità di dati trasferiti in ogni singola richiesta. Potrebbe essere necessario eseguire questa operazione se esiste un limite di tempo fisso richieste individuali.
- Devi fornire un indicatore personalizzato che mostri il caricamento progressi.
- Devi sapere quando puoi eliminare i dati in sicurezza.
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 nella .X-Goog-Upload-Command: impostata suupload, finalize.
Invia la richiesta.
Se la richiesta di caricamento viene interrotta o ricevi un 5xx
seguire la procedura descritta in Riprendere una
ha interrotto il caricamento.
Se la richiesta ha esito positivo, ricevi uno stato HTTP 200 OK
e un token di caricamento nel corpo della risposta.
Crea
l'elemento multimediale utilizzando questo token di caricamento.
Più chunk
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 di altri blocchi in multipli delle dimensioni accettate. Mantieni il valore il più grande possibile in modo che il caricamento sia efficiente.
-
Aggiungi le seguenti intestazioni HTTP:
Content-Length: impostato sul numero di byte nella un blocco note.X-Goog-Upload-Command: impostata suupload. Per l'ultimo blocco, imposta un valore suupload, finalize.X-Goog-Upload-Offset: viene impostato sull'offset in cui si trova devono essere scritti. Tieni presente che i byte devono essere caricati in modo seriale. Il primo offset è0.
- Invia la richiesta.
Se la richiesta di caricamento viene interrotta o ricevi un
5xxseguire la procedura descritta in Riprendere una ha interrotto il caricamento. - Ripeti i passaggi precedenti per ogni blocco rimanente del file.
Se la richiesta ha esito positivo, ricevi uno 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 caricare un file JPEG da 3.039.417 byte in un’unica 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 la dimensione del blocco prevista:
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
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ù chunk
L'esempio seguente mostra una richiesta ripristinabile di caricare un
File JPEG da 3.039.417 byte in più blocchi, utilizzando la sessione ripristinabile
e la granularità della dimensione del blocco accettata ottenuti nel passaggio precedente.
Questo esempio utilizza una dimensione del blocco di 262.144 byte restituita in
campo header, x-goog-upload-chunk-granularity, quando
sessione di caricamento è stata inizializzata. Tieni presente che ogni caricamento contiene byte
sono in multipli di 262.144.
Inizializza la sessione di caricamento per ricevere l'URL di caricamento e la dimensione 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 la dimensione del blocco prevista:
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 uno stato HTTP diverso da 200
esegui una query sul server per scoprire il numero di caricamenti riusciti.
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 dal server include un codice di stato HTTP 200 OK e il
dimensioni correnti del caricamento.
HTTP/1.1 200 OK X-Goog-Upload-Status: active X-Goog-Upload-Size-Received: 100
Potrai quindi riprendere il caricamento a questo offset. Devi riprendere dall'offset forniti dal server, a meno che tu non invii un comando combinato di caricamento e finalizzazione, In questo caso puoi anche riprendere da un offset pari a 0.
Se l'intestazione X-Goog-Upload-Status nella risposta HTTP del comando di query
è presente e il valore non è active, che indica che il caricamento è
è già stato chiuso.