Caricamenti ripristinabili

Configurazione

Questa pagina illustra i caricamenti ripristinabili in Cloud Storage. I caricamenti ripristinabili sono il metodo consigliato per caricare file di grandi dimensioni, poiché non è necessario riavviarli dall'inizio se si verifica un errore di rete durante il caricamento.

introduzione

Un caricamento ripristinabile consente di riprendere le operazioni di trasferimento di dati in Cloud Storage dopo che un errore di comunicazione ha interrotto il flusso di dati. I caricamenti ripristinabili funzionano mediante l'invio di più richieste, ciascuna delle quali contiene una parte dell'oggetto che stai caricando. È diverso dal caricamento di richiesta singola, che contiene tutti i dati dell'oggetto in un'unica richiesta e deve ricominciare dall'inizio se l'operazione ha esito negativo.

  • Utilizza un caricamento ripristinabile se stai caricando file di grandi dimensioni o utilizzando una connessione lenta. Ad esempio, le limitazioni relative alle dimensioni dei file per l'utilizzo di caricamenti ripristinabili, consulta le considerazioni sulle dimensioni di caricamento.

  • Un caricamento ripristinabile deve essere completato entro una settimana dall'avvio, 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 degli oggetti impostati dall'utente vengono specificati nella richiesta iniziale. Questi metadati vengono applicati all'oggetto al termine del caricamento.

    • L'API JSON supporta anche l'impostazione dei metadati personalizzati nella richiesta finale se nella richiesta sono incluse intestazioni precedute da X-Goog-Meta-.

In che modo strumenti e API utilizzano 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 su come configurare la dimensione del buffer appropriata per la tua applicazione.

Console

La console Google Cloud gestisce i caricamenti ripristinabili automaticamente per tuo conto. Tuttavia, se aggiorni o esci dalla console Google Cloud mentre è in corso un caricamento, quest'ultimo viene annullato.

Riga di comando

Gcloud CLI utilizza caricamenti ripristinabili nei comandi gcloud storage cp e gcloud storage rsync quando carichi i dati in Cloud Storage. Se il caricamento viene interrotto, puoi riprenderlo eseguendo lo stesso comando utilizzato per avviare il caricamento. Quando ripristini un caricamento di questo tipo che include più file, usa il flag --no-clobber per impedire il ricaricamento dei file già completati correttamente.

Librerie client

C++

Le funzioni in storage::Client si comportano con comportamenti diversi:

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

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

La libreria client C++ utilizza una dimensione del buffer pari alla dimensione del blocco. 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 piccoli per caricare oggetti di grandi dimensioni può rallentare il caricamento. Per ulteriori informazioni sulla relazione tra velocità di caricamento e dimensione del buffer per C++, consulta l'analisi dettagliata in 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 pari 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.

Go

Per impostazione predefinita, i caricamenti ripristinabili vengono eseguiti automaticamente quando il file supera i 16 MiB. Cambi 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 multiparte si verificano quando l'oggetto è inferiore a Writer.ChunkSize o quando Writer.ChunkSize è impostato su 0, dove la suddivisione in blocchi diventa disabilitata. Writer non può ritentare richieste se ChunkSize è impostato su 0.

La libreria client Go utilizza una dimensione del buffer pari alla dimensione del blocco. 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 più caricamenti ripristinabili contemporaneamente, devi impostare Writer.ChunkSize su un valore inferiore a 16 MiB per evitare un sovraccarico della memoria.

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

Java

La libreria client Java prevede metodi separati per caricamenti multiparte 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 passando un parametro bufferSize al metodo Storage#createFrom. La dimensione del buffer ha un minimo di 256 KiB. Quando chiami WriteChannel#setChunkSize(int) internamente, la dimensione del buffer viene spostata a un multiplo di 256 KiB.

Il buffer per i caricamenti ripristinabili funziona come soglia di svuotamento minimo, in cui le scritture inferiori alla dimensione del buffer vengono sottoposte a buffering finché una scrittura non spinge il numero di byte nel buffer sopra la dimensione del buffer.

Se carichi quantità minori di dati, 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 ripristinabili impostando resumable su UploadOptions su false. Quando utilizzi il metodo createWriteStream, i caricamenti ripristinabili vengono gestiti automaticamente.

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

La libreria client Node.js utilizza una dimensione del buffer pari alla dimensione del blocco. 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 superano i 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 pari alla dimensione del blocco. 256 KiB è la dimensione predefinita del buffer per un caricamento ripristinabile; puoi modificarla 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 supera gli 8 MiB, mentre i caricamenti con più parti si verificano quando l'oggetto è inferiore a 8 MiB. Questa soglia non può essere modificata. La libreria client Python usa una dimensione del buffer uguale alla dimensione del blocco. 100 MiB è la dimensione predefinita del buffer utilizzata per un caricamento ripristinabile; 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 Contenuti multimediali ripristinabili per gestire caricamenti ripristinabili.

La dimensione del blocco deve essere un multiplo di 256 KiB (256 x 1024 byte). Le dimensioni dei blocchi più grandi in genere velocizzano i caricamenti, ma tieni presente che c'è un compromesso tra velocità e utilizzo della memoria.

Ruby

La libreria client di Ruby tratta tutti i caricamenti come caricamenti ripristinabili senza blocchi.

API REST

API JSON

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

API XML

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

Caricamenti ripristinabili di dimensioni sconosciute

Il meccanismo di caricamento ripristinabile supporta trasferimenti in cui la dimensione del file non è nota in anticipo. Questo può essere utile per casi come la compressione all'istante di un oggetto durante il caricamento, poiché è difficile prevedere la dimensione esatta del file compresso all'inizio di un trasferimento. Il meccanismo è utile se vuoi trasmettere in streaming un trasferimento che può essere ripreso dopo l'interruzione o se la codifica del trasferimento in blocchi non funziona per la tua applicazione.

Per ulteriori informazioni, consulta la sezione Caricamenti in streaming.

Rendimento dei caricamenti

Scelta delle regioni delle sessioni

I caricamenti ripristinabili sono bloccati nella regione in cui li hai avviati. Ad esempio, se avvii un caricamento ripristinabile negli Stati Uniti e fornisci l'URI della sessione a un client in Asia, il caricamento continuerà comunque 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 dovrebbe trovarsi nella stessa località del bucket Cloud Storage in cui carichi. Puoi quindi utilizzare un servizio con IP geografico per scegliere la regione di Compute Engine verso la quale instrada le richieste dei clienti, in modo da mantenere il traffico localizzato in una regione.

Caricamento in blocchi

Se possibile, evita di suddividere un trasferimento in parti più piccole e carica invece l'intero contenuto in un unico blocco. L'eliminazione del chunking elimina i costi di latenza aggiuntivi e gli addebiti per le operazioni dalla query sull'offset persistente di ogni blocco e migliora la velocità effettiva. Tuttavia, ti consigliamo di caricare il file in blocchi quando:

  • I dati di origine vengono generati dinamicamente e vuoi limitare la quantità di dati di cui devi eseguire il buffering sul lato client in caso di caricamento non riuscito.

  • I tuoi client hanno limitazioni per le dimensioni delle richieste, come nel caso di molti browser.

Se utilizzi l'API JSON o XML e il client riceve un errore, può inviare una query al server per determinare l'offset permanente e riprendere il caricamento dei byte rimanenti da quell'offset. La console Google Cloud, Google Cloud CLI e le librerie client gestiscono questa operazione automaticamente per tuo conto. Per ulteriori indicazioni sulla suddivisione in blocchi per librerie client specifiche, consulta In che modo strumenti e API utilizzano i caricamenti ripristinabili.

Considerazioni

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

URI sessione

Quando avvii un caricamento ripristinabile, Cloud Storage restituisce un URI di sessione, che puoi utilizzare 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, pertanto le richieste che lo utilizzano non devono essere firmate e possono essere utilizzate da chiunque per caricare dati nel bucket di destinazione senza ulteriori autenticazioni. Per questo motivo, condividi l'URI della sessione con prudenza 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, riceverai 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'avvio del caricamento.

In entrambi i casi, devi avviare un nuovo caricamento ripristinabile, ottenere un nuovo URI di sessione e avviare il caricamento dall'inizio utilizzando il nuovo URI di sessione.

Controlli di integrità

Ti consigliamo di richiedere un controllo di integrità dell'oggetto finale caricato 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.

La verifica dell'integrità del file caricato è particolarmente importante se stai caricando un file di grandi dimensioni per un lungo periodo di tempo, perché esiste una maggiore probabilità che il file di origine venga modificato nel corso dell'operazione di caricamento.

Nuovi tentativi e nuovo invio dei dati

Quando Cloud Storage conserva i byte in un caricamento ripristinabile, questi byte non possono essere sovrascritti e Cloud Storage ignora i tentativi in tal senso. Per questo motivo, quando riavvolgi il caricamento non devi inviare dati diversi a un offset inviato in precedenza.

Ad esempio, supponiamo che tu stia caricando un oggetto di 100.000 byte e che la connessione sia interrotta. Quando controlli lo stato, scopri che 50.000 byte sono stati caricati e resi persistenti. Se tenti di riavviare il caricamento a 40.000 byte, Cloud Storage ignora i byte inviati da 40.000 a 50.000. Cloud Storage inizia a conservare i dati inviati a byte 50.001.

Passaggi successivi