Esecuzione di un caricamento ripristinabile

Questa pagina descrive come effettuare una richiesta di caricamento riassumibile nell'API Street View Publish. Questo protocollo ti consente di riprendere un'operazione di caricamento dopo che un errore di comunicazione ha interrotto il flusso di dati. Utilizza questa opzione 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 riavviabili possono anche ridurre l'utilizzo della larghezza di banda in caso di guasto della rete, perché non devi riavviare i caricamenti di file di grandi dimensioni dall'inizio.

Se invii file di piccole dimensioni tramite una connessione di rete affidabile, puoi utilizzare un semplice caricamento.

Avvio di una sessione di caricamento ripristinabile

Dopo aver ottenuto un uploadUrl, puoi avviare una sessione di caricamento ripristinabile:

  1. Crea una richiesta POST al uploadUrl.

  2. Aggiungi le seguenti intestazioni HTTP:

    • X-Goog-Upload-Protocol: impostato su resumable.
    • X-Goog-Upload-Header-Content-Length: impostato sul numero totale di byte degli dati del file, che verranno trasferiti nelle richieste successive.
    • X-Goog-Upload-Header-Content-Type: impostato sul tipo MIME dei dati del file.
    • X-Goog-Upload-Command: impostato su start.

  3. Invia la richiesta.

Esempio: lancio di una sessione di caricamento ripristinabile

L'esempio seguente mostra come avviare una sessione ripristinabile per caricare un nuovo file. In questo caso, il file è un'immagine e il numero totale di byte nel file è 4200000. Tieni presente che il corpo della richiesta è vuoto, pertanto l'intestazione Content-Length è impostata su 0.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

La sezione Salvare l'URL della sessione riavviabile descrive come gestire la risposta alla richiesta di avvio della sessione di caricamento riavviabile.

Salvataggio dell'URL della sessione riavvolgibile

Per la richiesta inviata per avviare una sessione di caricamento ripristinabile, il server risponderà con un codice di stato HTTP 200 OK, inclusa la seguente intestazione:

  • X-Goog-Upload-URL: un URL univoco che deve essere utilizzato per completare il caricamento tramite tutte le richieste rimanenti.

Copia e salva l'URL della sessione riassumibile in modo da poterlo utilizzare per le richieste successive.

Esempio: salvataggio dell'URL della sessione riavvolgibile

L'esempio seguente mostra una risposta che include un URL sessione riassumibile e un requisito di granularità delle dimensioni.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

Caricamento del file

Esistono due modi per caricare un file con una sessione ripristinabile:

  1. In una singola richiesta. In genere, questo approccio è il migliore, perché richiede meno richieste e, di conseguenza, ha un rendimento migliore.
  2. In più blocchi. Utilizza questo approccio se:
    • Devi ridurre la quantità di dati trasferiti in una 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 l'avanzamento del caricamento.
    • Devi sapere quando è sicuro eliminare i dati.

Richiesta singola

Per caricare il file in una singola richiesta:

  1. Crea una richiesta POST all'URL della sessione riassumibile.
  2. Aggiungi i dati del file al corpo della richiesta.

  3. Aggiungi le seguenti intestazioni HTTP:

    • Content-Length: impostato sul numero di byte nel file.
    • X-Goog-Upload-Command: impostato su upload, finalize.

  4. Invia la richiesta.

Se la richiesta di caricamento viene interrotta o ricevi una risposta 5xx, segui la procedura descritta in Riprendere un caricamento interrotto.

Più chunk

Per caricare il file in più parti:

  1. Crea una richiesta POST all'URL della sessione riassumibile.
  2. Aggiungi i dati del blocco al corpo della richiesta. Crea blocchi in multipli di 2 MiB (mebibyte), tranne il blocco finale che completa il caricamento. Mantieni le dimensioni dei chunk il più grandi possibile per garantire l'efficienza del caricamento.

  3. Aggiungi le seguenti intestazioni HTTP:

    • Content-Length: impostato sul numero di byte nel chunk.
    • X-Goog-Upload-Command: impostato su upload. Per l'ultimo chunk, imposta su upload, finalize.
    • X-Goog-Upload-Offset: viene impostato sull'offset in cui devono essere scritti i byte. Tieni presente che i byte devono essere caricati in sequenza.

  4. Invia la richiesta. Se la richiesta di caricamento viene interrotta o ricevi una risposta 5xx, segui la procedura descritta in Riprendere un caricamento interrotto.

  5. Ripeti i passaggi da 1 a 4 per ogni chunk rimanente del file.

Esempio: caricare il file

Richiesta singola

L'esempio seguente mostra una richiesta ripristinabile per caricare un intero file JPEG da 4.200.000 byte in una singola richiesta, utilizzando l'URL di sessione ripristinabile ottenuto nel passaggio precedente:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

Se la richiesta va a buon fine, ricevi un codice di stato HTTP 200 OK.

Più chunk

L'esempio seguente mostra una richiesta riprendente per il caricamento di un file JPEG di 4.200.000 byte in più chunk, utilizzando l'URL della sessione riprendente e la granularità delle dimensioni ottenuta nel passaggio precedente. Questo esempio utilizza una dimensione del chunk di 2097000 byte, che è un multiplo di 2 MiB (mebibyte).

Primo blocco: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

Secondo chunk: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

Ultimo chunk: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

Riprendere un caricamento interrotto

Se la richiesta di caricamento viene interrotta o se ricevi un codice di stato HTTP diverso da 200, esegui una query sul server per scoprire il tempo di caricamento:

  1. Crea una richiesta POST all'URL della sessione riassumibile.
  2. Imposta X-Goog-Upload-Command su query.
  3. Invia la richiesta.

Il server risponderà con 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 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, il caricamento è già stato interrotto.