Esecuzione di un caricamento ripristinabile

In questa pagina viene descritto come effettuare una richiesta di caricamento ripristinabile nell'API Street View Publish. Questo protocollo consente di riprendere un'operazione di caricamento dopo che un errore di comunicazione interrompe il flusso dei dati. Utilizza questa opzione se:

  • Stai caricando file di grandi dimensioni.
  • La probabilità che si verifichi un'interruzione della rete o un altro errore di trasmissione è elevata (ad esempio se carichi un file da un'app mobile).

I caricamenti ripristinabili possono inoltre ridurre l'utilizzo della larghezza di banda in caso di errore di rete, perché non è necessario riavviare i caricamenti di file di grandi dimensioni fin 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: imposta 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: imposta 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 per avviare la sessione di caricamento ripristinabile.

È in corso il 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 con tutte le richieste rimanenti.

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

Esempio: salvataggio dell'URL della sessione ripristinabile

L'esempio seguente mostra una risposta che include un URL della 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 una singola richiesta. Questo è l'approccio migliore perché richiede meno richieste e quindi ha prestazioni migliori.
  2. In più porzioni. Utilizza questo approccio se:
    • Devi ridurre la quantità di dati trasferiti in ogni singola richiesta. Potresti dover eseguire questa operazione 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 puoi eliminare i dati in sicurezza.

Richiesta singola

Per caricare il file in una singola 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: imposta 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ù blocchi:

  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. Fai in modo che le dimensioni del blocco siano il più 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: imposta su upload. Per l'ultimo blocco, impostalo su upload, finalize.
    • X-Goog-Upload-Offset: impostato sull'offset con cui 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 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 ha esito positivo, riceverai un codice di stato HTTP 200 OK.

Più blocchi

L'esempio seguente mostra una richiesta ripristinabile per caricare un file JPEG da 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 non 200, invia una query al server per scoprire per quanto tempo il caricamento è riuscito:

  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, potrai riprendere il caricamento. Devi ripristinare l'offset fornito dal server a meno che non invii un comando combinato di caricamento e finalizzazione. In tal caso, potrai riprendere anche l'operazione con l'offset 0.

Se è presente l'intestazione X-Goog-Upload-Status nella risposta HTTP del comando di query e il valore non è active, significa che il caricamento è già stato terminato.