Esecuzione di un caricamento ripristinabile

Questa pagina descrive come effettuare una richiesta di caricamento ripristinabile nell'API Street View Publish. Questo protocollo ti consente di riprendere un'operazione di caricamento dopo che un errore di comunicazione interrompe 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 ripristinabili possono anche ridurre l'utilizzo della larghezza di banda in caso di errore di 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 a 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 dei 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: avvio 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

Salvataggio dell'URL della sessione ripristinabile descrive come gestire la risposta alla richiesta di avvio della sessione di caricamento ripristinabile.

Salvataggio dell'URL della sessione ripristinabile

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 in tutte le richieste rimanenti.

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

Esempio: salvataggio dell'URL della sessione ripristinabile

Il seguente esempio mostra una risposta che include un URL di sessione ripristinabile 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 un'unica richiesta. Questo approccio è in genere il migliore, perché richiede meno richieste e quindi offre prestazioni migliori.
  2. In più parti. Utilizza questo approccio se:
    • Devi ridurre la quantità di dati trasferiti in una singola richiesta. Potresti doverlo fare 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 un'unica richiesta:

  1. Crea una richiesta POST all'URL della sessione ripristinabile.
  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ù blocchi

Per caricare il file in più parti:

  1. Crea una richiesta POST all'URL della sessione ripristinabile.
  2. Aggiungi i dati del blocco al corpo della richiesta. Crea blocchi in multipli di 2 MiB (mebibyte), ad eccezione del blocco finale che completa il caricamento. Mantieni le dimensioni del blocco il più grandi possibile in modo che il caricamento sia efficiente.

  3. Aggiungi le seguenti intestazioni HTTP:

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

  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 blocco rimanente nel file.

Esempio: caricamento del file

Richiesta singola

L'esempio seguente mostra una richiesta ripristinabile per caricare un intero file JPEG di 4.200.000 byte in un'unica richiesta, utilizzando l'URL della 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ù blocchi

L'esempio seguente mostra una richiesta ripristinabile per caricare un file JPEG di 4.200.000 byte in più blocchi, utilizzando l'URL della sessione ripristinabile e la granularità delle dimensioni ottenuta nel passaggio precedente. Questo esempio utilizza una dimensione del blocco 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 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: 2097000



[BYTES 2097000-4193999]

Ultimo blocco: 

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, interroga il server per scoprire la quantità di dati caricati correttamente:

  1. Crea una richiesta POST all'URL della sessione ripristinabile.
  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 tu non invii un comando di caricamento e finalizzazione combinato, nel qual caso puoi riprendere anche 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 terminato.