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.
Utilizza l'opzione di caricamento ripristinabile se:
- Stai caricando file di grandi dimensioni.
- La probabilità di interruzione della rete o di un altro errore di trasmissione è elevata (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 |
Impostato 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 un'intestazione della 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 la richiesta va a buon fine, restituisce un codice di stato HTTP 200 OK, incluso
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. In altre parole, i byte di caricamento del file devono essere allineati a questo valore. Nell'ultimo chunk 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 sessione riassumibile, in modo da poterlo utilizzare per le richieste successive.
Passaggio 3: carica il file
Esistono due modi per caricare un file con una sessione riavviabile:
- 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 suddivise in blocchi possono essere riprovate.Utilizza questo approccio se:
- Devi ridurre la quantità di dati trasferiti in ogni singola richiesta. Potresti dover eseguire questa operazione quando è previsto un limite di tempo fisso per le singole richieste.
- Devi fornire un indicatore personalizzato che mostri lo stato di 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 riassumibile. - 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: impostata suupload, finalize.
Invia la richiesta.
Se la richiesta di caricamento viene interrotta o ricevi una risposta 5xx
, segui la procedura descritta in Riprendere un caricamento
interrotto.
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ù parti:
- Crea una richiesta
POSTall'URL della sessione riassumibile. -
Aggiungi i dati del chunk al corpo della richiesta.
Fatta eccezione per il blocco finale che completa il caricamento, crea di altri blocchi in multipli delle dimensioni accettate. Mantieni la dimensione del chunk il più grande possibile per un caricamento efficiente.
-
Aggiungi le seguenti intestazioni HTTP:
Content-Length: impostato sul numero di byte nella un blocco note.X-Goog-Upload-Command: impostato suupload. Per l'ultimo chunk, impostaupload, 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 sequenza. Il primo offset è0.
- Invia la richiesta.
Se la richiesta di caricamento viene interrotta o ricevi una risposta
5xx, segui la procedura descritta in Riprendere un caricamento interrotto. - Ripeti questi passaggi per ogni chunk rimanente nel file.
Se la richiesta riesce, ricevi 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 riprendente per il caricamento di un file JPEG di 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 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 riprendente per il caricamento di un
file JPEG di 3039417 byte in più chunk, utilizzando l'URL della sessione riprendente
e la granularità delle dimensioni dei chunk accettate ottenuta nel passaggio precedente.
Questo esempio utilizza una dimensione del chunk di 262.144 byte restituita nel
campo dell'intestazione x-goog-upload-chunk-granularity quando è stata inizializzata la
sessione di caricamento. 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 chunk:
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 chunk:
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 riassumibile. 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
A questo punto puoi riprendere il caricamento. Devi riprendere dall'offset fornito dal server, a meno che non invii un comando combinato di caricamento e finalizzazione, nel qual caso puoi anche riprendere dall'offset 0.
Se l'intestazione X-Goog-Upload-Status nella risposta HTTP del comando di query è presente e il valore non è active, significa che il caricamento è già stato terminato.