Caricamenti ripristinabili

Configurazione

Questa pagina descrive i caricamenti ripristinabili in Cloud Storage. I caricamenti ripristinabili sono il metodo consigliato per caricare file di grandi dimensioni, perché non devi riavviarli dall'inizio in caso di errore di rete durante il caricamento.

Introduzione

Un caricamento ripristinabile ti consente di riprendere le operazioni di trasferimento dei dati a Cloud Storage dopo che un errore di comunicazione ha interrotto il flusso di dati. I caricamenti ripristinabili funzionano inviando più richieste, ognuna delle quali contiene una parte dell'oggetto che stai caricando. Questo è diverso da un caricamento con una sola richiesta, che contiene tutti i dati dell'oggetto in un'unica richiesta e deve riavviarsi dall'inizio se non va a buon fine.

  • Utilizza un caricamento ripristinabile se carichi file di grandi dimensioni o se carichi tramite una connessione lenta. Ad esempio, per i limiti di dimensione dei file per l'utilizzo dei caricamenti ripristinabili, consulta Considerazioni sulle dimensioni di caricamento.

  • Un caricamento ripristinabile deve essere completato entro una settimana dall'inizio, ma può essere annullato in qualsiasi momento.

  • Nel bucket viene visualizzato solo un caricamento ripristinabile completato e, se applicabile, sostituisce un oggetto esistente con lo stesso nome.

    • L'ora di creazione dell'oggetto si basa sul completamento del caricamento.

    • I metadati dell'oggetto impostati dall'utente sono specificati nella richiesta iniziale. Questi metadati vengono applicati all'oggetto al termine del caricamento.

    • L'API JSON supporta anche l'impostazione di metadati personalizzati nella richiesta finale se includi intestazioni con il prefisso X-Goog-Meta- in quella richiesta.

Come gli strumenti e le API utilizzano i caricamenti ripristinabili

A seconda di come interagisci con Cloud Storage, i caricamenti ripristinabili potrebbero essere gestiti automaticamente per tuo conto. Questa sezione descrive il comportamento di caricamento ripristinabile per diversi strumenti e fornisce indicazioni sulla configurazione delle dimensioni del buffer appropriate per la tua applicazione.

Console

La Google Cloud console gestisce automaticamente i caricamenti ripristinabili per tuo conto. Tuttavia, se aggiorni la pagina o esci dalla consoleGoogle Cloud durante il caricamento, quest'ultimo viene annullato.

Riga di comando

gcloud CLI utilizza i caricamenti ripristinabili nei comandi gcloud storage cp e gcloud storage rsync durante il caricamento dei dati in Cloud Storage. Se il caricamento viene interrotto, puoi riprenderlo eseguendo lo stesso comando che hai utilizzato per avviare il caricamento. Quando riprendi un caricamento di questo tipo che include più file, utilizza il flag --no-clobber per evitare di ricaricare i file che sono già stati completati correttamente.

Librerie client

Quando esegui caricamenti ripristinabili, le librerie client fungono da wrapper per l'API JSON di Cloud Storage.

C++

Le funzioni in storage::Client si comportano in modo diverso:

Per impostazione predefinita, UploadFile() esegue un caricamento ripristinabile quando l'oggetto supera i 20 MiB. In caso contrario, esegue un caricamento semplice o in più parti. Puoi configurare questa soglia impostando MaximumSimpleUploadsSizeOption durante la creazione di un storage::Client.

8 MiB è la dimensione predefinita del buffer, che puoi modificare con l'opzione UploadBufferSizeOption.

La libreria client C++ utilizza una dimensione del buffer uguale alla dimensione del chunk. La dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte). Quando utilizzi WriteObject() e UploadFile(), ti consigliamo di valutare i compromessi tra velocità di caricamento e utilizzo della memoria. L'utilizzo di buffer di piccole dimensioni per caricare oggetti di grandi dimensioni può rallentare il caricamento. Per maggiori informazioni sulla relazione tra velocità di caricamento e dimensione del buffer per C++, consulta l'analisi dettagliata su GitHub.

C#

Durante il caricamento, la libreria client C# esegue sempre caricamenti ripristinabili. Puoi avviare un caricamento ripristinabile con CreateObjectUploader.

La libreria client C# utilizza una dimensione del buffer uguale alla dimensione del blocco. La dimensione predefinita del buffer è 10 MB e puoi modificare questo valore impostando ChunkSize su UploadObjectOptions. La dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte). Dimensioni del buffer più grandi in genere velocizzano i caricamenti, ma tieni presente che esiste un compromesso tra velocità e utilizzo della memoria.

Vai

Per impostazione predefinita, i caricamenti ripristinabili vengono eseguiti automaticamente quando il file è più grande di 16 MiB. Modifica il limite per l'esecuzione di caricamenti ripristinabili con Writer.ChunkSize. I caricamenti ripristinabili vengono sempre suddivisi in blocchi quando si utilizza la libreria client Go.

I caricamenti in più parti si verificano quando l'oggetto è più piccolo di Writer.ChunkSize o quando Writer.ChunkSize è impostato su 0, il che disattiva la suddivisione in blocchi. Writer non può riprovare le richieste se ChunkSize è impostato su 0.

La libreria client Go utilizza una dimensione del buffer uguale alla dimensione del chunk. La dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte). Dimensioni del buffer più grandi in genere velocizzano i caricamenti, ma tieni presente che esiste un compromesso tra velocità e utilizzo della memoria. Se esegui contemporaneamente diversi caricamenti ripristinabili, devi impostare Writer.ChunkSize su un valore inferiore a 16 MiB per evitare un eccessivo utilizzo della memoria.

Tieni presente che l'oggetto non viene finalizzato in Cloud Storage finché non chiami Writer.Close() e ricevi una risposta di operazione riuscita. Writer.Close restituisce un errore se la richiesta non va a buon fine.

Java

La libreria client Java dispone di metodi separati per i caricamenti in più parti e ripristinabili. I seguenti metodi eseguono sempre un caricamento ripristinabile:

La dimensione predefinita del buffer è 15 MiB. Puoi impostare la dimensione del buffer utilizzando il metodo WriteChannel#setChunkSize(int) o trasmettendo un parametro bufferSize al metodo Storage#createFrom. La dimensione del buffer ha un minimo rigido di 256 KiB. Quando chiami WriteChannel#setChunkSize(int) internamente, la dimensione del buffer viene spostata su un multiplo di 256 KiB.

Il buffering per i caricamenti ripristinabili funziona come una soglia di scaricamento minima, in cui le scritture più piccole della dimensione del buffer vengono memorizzate nel buffer finché una scrittura non spinge il numero di byte memorizzati nel buffer al di sopra della dimensione del buffer.

Se carichi quantità di dati più piccole, valuta la possibilità di utilizzare Storage#create(BlobInfo, byte[], Storage.BlobTargetOption...) o Storage#create(BlobInfo, byte[], int, int, Storage.BlobTargetOption...).

Node.js

I caricamenti ripristinabili vengono eseguiti automaticamente. Puoi disattivare i caricamenti ripresi impostando resumable su UploadOptions su false. I caricamenti ripristinabili vengono gestiti automaticamente quando utilizzi il metodo createWriteStream.

Non esiste una dimensione del buffer predefinita e i caricamenti suddivisi in blocchi devono essere richiamati manualmente impostando l'opzione chunkSize su CreateResumableUploadOptions. Se viene specificato chunkSize, i dati vengono inviati in richieste HTTP separate, ognuna con un payload di dimensioni chunkSize. Se non viene specificato alcun chunkSize e la libreria esegue un caricamento ripristinabile, tutti i dati vengono trasmessi in streaming in una singola richiesta HTTP.

La libreria client Node.js utilizza una dimensione del buffer pari alla dimensione del chunk. La dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte). Dimensioni del buffer maggiori in genere velocizzano i caricamenti, ma tieni presente che esiste un compromesso tra velocità e utilizzo della memoria.

PHP

Per impostazione predefinita, i caricamenti ripristinabili vengono eseguiti automaticamente quando le dimensioni dell'oggetto sono superiori a 5 MB. In caso contrario, vengono eseguiti caricamenti in più parti. Questa soglia non può essere modificata. Puoi forzare un caricamento ripristinabile impostando l'opzione resumable nella funzione upload.

La libreria client PHP utilizza una dimensione del buffer uguale alla dimensione del chunk. 256 KiB è la dimensione predefinita del buffer per un caricamento ripristinabile e puoi modificare la dimensione del buffer impostando la proprietà chunkSize. La dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte). Dimensioni del buffer più grandi in genere velocizzano i caricamenti, ma tieni presente che esiste un compromesso tra velocità e utilizzo della memoria.

Python

I caricamenti ripristinabili si verificano quando l'oggetto è più grande di 8 MiB, mentre i caricamenti multiparte si verificano quando l'oggetto è più piccolo di 8 MiB. Questa soglia non può essere modificata. La libreria client Python utilizza una dimensione del buffer uguale alla dimensione del chunk. 100 MiB è la dimensione predefinita del buffer utilizzata per un caricamento ripristinabile e puoi modificare la dimensione del buffer impostando la proprietà blob.chunk_size.

Per eseguire sempre un caricamento ripristinabile indipendentemente dalle dimensioni dell'oggetto, utilizza la classe storage.BlobWriter o il metodo storage.Blob.open(mode='w'). Per questi metodi, la dimensione predefinita del buffer è 40 MiB. Puoi anche utilizzare Resumable Media per gestire i caricamenti ripristinabili.

La dimensione del chunk deve essere un multiplo di 256 KiB (256 x 1024 byte). Dimensioni dei chunk più grandi in genere velocizzano i caricamenti, ma tieni presente che esiste un compromesso tra velocità e utilizzo della memoria.

Ruby

La libreria client Ruby considera tutti i caricamenti come caricamenti ripristinabili non suddivisi in blocchi.

API REST

API JSON

L'API Cloud Storage JSON utilizza una richiesta POST Object che include il parametro di query uploadType=resumable per avviare il caricamento ripristinabile. Questa richiesta restituisce un URI di sessione che utilizzi in una o più richieste PUT Object per caricare i dati dell'oggetto. Per una guida passo passo alla creazione della tua logica per il caricamento ripristinabile, consulta Esecuzione di caricamenti ripristinabili.

API XML

L'API Cloud Storage XML utilizza una richiesta POST Object che include l'intestazione x-goog-resumable: start per avviare il caricamento ripristinabile. Questa richiesta restituisce un URI di sessione che utilizzi in una o più richieste PUT Object per caricare i dati dell'oggetto. Per una guida passo passo alla creazione della tua logica per il caricamento ripristinabile, consulta Esecuzione di caricamenti ripristinabili.

Caricamenti ripristinabili di dimensioni sconosciute

Il meccanismo di caricamento ripristinabile supporta i trasferimenti in cui le dimensioni del file non sono note in anticipo. Ciò può essere utile in casi come la compressione di un oggetto al volo durante il caricamento, poiché è difficile prevedere le dimensioni esatte del file compresso all'inizio di un trasferimento. Il meccanismo è utile se vuoi trasmettere in streaming un trasferimento che può essere ripreso dopo essere stato interrotto oppure se la codifica del trasferimento chunked non funziona per la tua applicazione.

Per ulteriori informazioni, consulta Caricamenti in streaming.

Rendimento del caricamento

Scelta delle regioni delle sessioni

I caricamenti ripristinabili vengono bloccati nella regione in cui li avvii. Ad esempio, se avvii un caricamento ripristinabile negli Stati Uniti e fornisci l'URI di sessione a un client in Asia, il caricamento viene comunque eseguito negli Stati Uniti. Per ridurre il traffico tra regioni e migliorare le prestazioni, devi mantenere una sessione di caricamento ripristinabile nella regione in cui è stata creata.

Se utilizzi un'istanza Compute Engine per avviare un caricamento ripristinabile, l'istanza deve trovarsi nella stessa località del bucket Cloud Storage in cui esegui il caricamento. Puoi quindi utilizzare un servizio IP geografico per scegliere la regione di Compute Engine a cui indirizzare le richieste dei clienti, il che contribuisce a mantenere il traffico localizzato in una regione geografica.

Caricamento in blocchi

Se possibile, evita di suddividere un trasferimento in blocchi più piccoli e carica l'intero contenuto in un unico blocco. L'evitare la suddivisione in blocchi elimina i costi di latenza aggiuntivi e le spese per le operazioni di query sull'offset persistente di ogni blocco, oltre a migliorare la velocità effettiva. Tuttavia, ti consigliamo di caricare i video in blocchi quando:

  • I dati di origine vengono generati in modo dinamico e vuoi limitare la quantità di dati da memorizzare nel buffer lato client in caso di errore di caricamento.

  • I tuoi clienti hanno limitazioni alle dimensioni delle richieste, come avviene per molti browser.

Se utilizzi l'API JSON o XML e il tuo client riceve un errore, può eseguire una query sul server per l'offset persistente e riprendere il caricamento dei byte rimanenti da quell'offset. La console Google Cloud , Google Cloud CLI e le librerie client gestiscono automaticamente questa operazione per tuo conto. Consulta Come gli strumenti e le API utilizzano i caricamenti ripristinabili per ulteriori indicazioni sulla suddivisione in blocchi per librerie client specifiche.

Considerazioni

Questa sezione è utile se stai creando un tuo client che invia richieste di caricamento ripristinabile direttamente all'API JSON o XML.

URI sessione

Quando avvii un caricamento ripristinabile, Cloud Storage restituisce un URI sessione, che utilizzi nelle richieste successive per caricare i dati effettivi. Un esempio di URI di sessione nell'API JSON è:

https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=my-file.jpg&upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

Un esempio di URI di sessione nell'API XML è:

 https://storage.googleapis.com/my-bucket/my-file.jpg?upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

Questo URI di sessione funge da token di autenticazione, quindi le richieste che lo utilizzano non devono essere firmate e possono essere utilizzate da chiunque per caricare dati nel bucket di destinazione senza ulteriore autenticazione. Per questo motivo, fai attenzione a condividere l'URI della sessione e condividilo solo tramite HTTPS.

L'URI di una sessione scade dopo una settimana, ma può essere annullato prima della scadenza. Se effettui una richiesta utilizzando un URI di sessione non più valido, ricevi uno dei seguenti errori:

  • Un codice di stato 410 Gone se è trascorsa meno di una settimana dall'inizio del caricamento.
  • Un codice di stato 404 Not Found se è trascorsa più di una settimana dall'inizio del caricamento.

In entrambi i casi, o se perdi l'URI della sessione prima del completamento del caricamento, devi avviare un nuovo caricamento ripristinabile, ottenere un nuovo URI della sessione e iniziare il caricamento dall'inizio utilizzando il nuovo URI della sessione.

Controlli di integrità

Ti consigliamo di richiedere un controllo dell'integrità dell'oggetto caricato finale per assicurarti che corrisponda al file di origine. Puoi farlo calcolando il digest MD5 del file di origine e aggiungendolo all'intestazione della richiesta Content-MD5.

Il controllo dell'integrità del file caricato è particolarmente importante se stai caricando un file di grandi dimensioni per un lungo periodo di tempo, perché aumenta la probabilità che il file di origine venga modificato nel corso dell'operazione di caricamento.

Tuttavia, non puoi eseguire controlli di integrità su porzioni o blocchi intermedi di un caricamento ripristinabile, perché questi caricamenti sono pensati per consentirti di riprendere un caricamento in caso di interruzione imprevista.

Tentativi e invio di nuovo dei dati

Una volta che Cloud Storage ha reso persistenti i byte in un caricamento ripristinabile, questi byte non possono essere sovrascritti e Cloud Storage ignora i tentativi di farlo. Per questo motivo, non devi inviare dati diversi quando torni a un offset che hai inviato in precedenza.

Ad esempio, supponiamo che tu stia caricando un oggetto di 100.000 byte e che la tua connessione venga interrotta. Quando controlli lo stato, scopri che 50.000 byte sono stati caricati e salvati correttamente. Se provi a riavviare il caricamento al byte 40.000, Cloud Storage ignora i byte che invii da 40.000 a 50.000. Cloud Storage inizia a rendere persistenti i dati che invii a partire dal byte 50.001.

Passaggi successivi