Questa pagina illustra i caricamenti riavviabili in Cloud Storage. I caricamenti riavviabili sono il metodo consigliato per caricare file di grandi dimensioni, perché non devi riavviarli dall'inizio se si verifica un errore di rete durante il caricamento.
Introduzione
Un caricamento riavviabile ti consente di riprendere le operazioni di trasferimento dei dati in Cloud Storage dopo che un errore di comunicazione ha interrotto il flusso di dati. I caricamenti riavviabili funzionano inviando più richieste, ciascuna delle quali contiene una parte dell'oggetto che stai caricando. È diverso da un caricamento con una singola richiesta, che contiene tutti i dati dell'oggetto in una singola richiesta e deve essere riavviato dall'inizio se non va a buon fine a metà.
Utilizza un caricamento ripristinabile se carichi file di grandi dimensioni o se esegui il caricamento tramite una connessione lenta. Ad esempio, per i limiti di dimensioni dei file per l'utilizzo dei caricamenti ripristinabili, consulta le considerazioni sulle dimensioni dei caricamenti.
Un caricamento ripristinabile di ripresa 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 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 prefisso
X-Goog-Meta-
.
- Un caricamento ripristinabile completato è considerato una singola operazione di classe A.
Come gli strumenti e le API utilizzano i caricamenti riavviabili
A seconda di come interagisci con Cloud Storage, i caricamenti riavviabili potrebbero essere gestiti automaticamente per tuo conto. Questa sezione descrive il comportamento di caricamento ripristinabile per diversi strumenti e fornisce indicazioni per configurare la dimensione del buffer appropriata per la tua applicazione.
Console
La console Google Cloud gestisce automaticamente i caricamenti riavviabili per tuo conto. Tuttavia, se aggiorni la pagina o esci dalla console Google Cloud mentre è in corso un caricamento, il caricamento viene annullato.
Riga di comando
La gcloud CLI utilizza i caricamenti riavviabili nei comandi gcloud storage cp
e gcloud storage rsync
quando carica i dati su Cloud Storage. Se il caricamento viene interrotto, puoi riprenderlo eseguendo lo stesso comando utilizzato per avviarlo. 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 riavviabili, le librerie client fungono da wrapper per l'API JSON di Cloud Storage.
C++
Le funzioni in storage::Client
hanno un comportamento diverso:
Client::WriteObject()
esegue sempre un caricamento ripristinabile.Client::InsertObject()
esegue sempre un caricamento semplice o suddiviso.Client::UploadFile()
può eseguire un caricamento ripristinabile, un caricamento semplice o un caricamento multiparte.
Per impostazione predefinita, UploadFile()
esegue un caricamento ripristinabile quando l'oggetto è più grande di 20 MiB. In caso contrario, esegue un semplice caricamento o un caricamento suddiviso. Puoi configurare questa soglia impostando
MaximumSimpleUploadsSizeOption
quando crei 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 uguale alla dimensione del frammento. 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 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 riavviabili.
Puoi avviare un caricamento ripristinabile con
CreateObjectUploader
.
La libreria client C# utilizza una dimensione del buffer uguale alla dimensione del chunk.
La dimensione del buffer predefinita è 10 MB e puoi modificarla impostando ChunkSize
su UploadObjectOptions
. La dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte). In genere, dimensioni dei buffer più grandi rendono più rapidi i caricamenti, ma tieni presente che esiste un compromesso tra velocità e utilizzo della memoria.
Vai
Per impostazione predefinita, i caricamenti riavviabili vengono eseguiti automaticamente quando il file è più grande di 16 MiB. Modifica il limite per l'esecuzione dei caricamenti
ripristinabili con Writer.ChunkSize
. I caricamenti riavviabili sono sempre suddivisi in blocchi quando si utilizza la libreria client Go.
I caricamenti suddivisi in più parti si verificano quando l'oggetto è più piccolo di Writer.ChunkSize
o quando Writer.ChunkSize
è impostato su 0, nel qual caso il chunking viene disattivato. Writer
non è in grado di 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). In genere, dimensioni dei buffer più grandi rendono più rapidi i caricamenti, ma tieni presente che esiste un compromesso tra velocità e utilizzo della memoria. Se esegui più caricamenti riavviabili contemporaneamente, devi impostare Writer.ChunkSize
su un valore inferiore a 16 MiB per evitare un aumento eccessivo 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 suddivisi in più parti e quelli riavviabili. I seguenti metodi eseguono sempre un caricamento ripristinabile:
Storage#createFrom(BlobInfo, java.io.InputStream, Storage.BlobWriteOption...)
Storage#createFrom(BlobInfo, java.io.InputStream, int, Storage.BlobWriteOption...)
Storage#createFrom(BlobInfo, java.nio.file.Path, Storage.BlobWriteOption...)
Storage#createFrom(BlobInfo, java.nio.file.Path, int, Storage.BlobWriteOption...)
Storage#writer(BlobInfo, Storage.BlobWriteOption...)
Storage#writer(java.net.URL)
La dimensione del buffer predefinita è 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 valore minimo obbligatorio 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 riavviabili funziona come una soglia minima di svuotamento, dove le scritture inferiori alla dimensione del buffer vengono messe in buffer fino a quando una scrittura non spinge il numero di byte in buffer al di sopra della dimensione del buffer.
Se carichi quantità di dati inferiori, 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 riprendebili impostando resumable
su UploadOptions
su
false
. I caricamenti ripetibili vengono gestiti automaticamente quando utilizzi il
metodo createWriteStream
.
Non è prevista una dimensione predefinita del buffer e i caricamenti suddivisi in blocchi devono essere invocati manualmente impostando l'opzione chunkSize
su CreateResumableUploadOptions. Se viene specificato chunkSize
, i dati vengono inviati in richieste HTTP separate, ciascuna con un payload di dimensioni chunkSize
. Se non viene specificato chunkSize
e la biblioteca sta eseguendo 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 alle dimensioni del frammento. La dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte). In genere, dimensioni del buffer più grandi rendono più rapidi i caricamenti, ma tieni presente che esiste un compromesso tra velocità e utilizzo della memoria.
PHP
Per impostazione predefinita, i caricamenti ripetibili vengono eseguiti automaticamente quando le dimensioni dell'oggetto sono superiori a 5 MB. In caso contrario, si verificano caricamenti suddivisi 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 frammento. 256 KiB è la dimensione del buffer predefinita per un caricamento ripristinabile e puoi modificarla impostando la proprietà chunkSize
.
La dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte). In genere, dimensioni dei buffer più grandi rendono più rapidi i caricamenti, ma tieni presente che esiste un compromesso tra velocità e utilizzo della memoria.
Python
I caricamenti ripetibili 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 MB è la dimensione predefinita del buffer utilizzata per un caricamento ripristinabile e puoi modificarla 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). In genere, dimensioni dei chunk più grandi consentono di velocizzare i caricamenti, ma tieni presente che esiste un compromesso tra velocità e utilizzo della memoria.
Ruby
La libreria client Ruby tratta tutti i caricamenti come caricamenti riavviabili non suddivisi in 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 sessione, che poi utilizzerai 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 Eseguire 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 sessione, che poi utilizzerai 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 Eseguire caricamenti ripristinabili.
Caricamenti ripristinabili di dimensioni sconosciute
Il meccanismo di caricamento ripristinabile supporta i trasferimenti in cui le dimensioni del file non sono conosciute in anticipo. Questo può essere utile, ad esempio, per comprimere 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 o se la codifica del trasferimento suddiviso in blocchi non funziona per la tua applicazione.
Per ulteriori informazioni, consulta la sezione Caricamenti in streaming.
Rendimento del caricamento
Scegliere le 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 sessione a un cliente in Asia, il caricamento avviene 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 deve trovarsi nella stessa posizione del bucket Cloud Storage in cui esegui il caricamento. Puoi quindi utilizzare un servizio IP geografico per scegliere la regione Compute Engine a cui instradare 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 invece tutti i contenuti in un unico blocco. Evitare il chunking rimuove i costi e gli addebiti per le operazioni relativi alla latenza aggiuntiva derivanti dalla query sull'offset persistente di ogni chunk, nonché migliora il throughput. Tuttavia, ti consigliamo di caricare i video in blocchi quando:
I dati di origine vengono generati in modo dinamico e vuoi limitare la quantità da mettere in buffer lato client nel caso in cui il caricamento non vada a buon fine.
I tuoi clienti hanno limitazioni relative alle dimensioni delle richieste, come accade per molti browser.
Se utilizzi l'API JSON o XML e il client riceve un errore, può eseguire una query sul server per l'offset mantenuto 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 In che modo gli strumenti e le API utilizzano i caricamenti riavviabili per ulteriori indicazioni sul suddivisione in blocchi per librerie client specifiche.
Considerazioni
Questa sezione è utile se stai creando il tuo client che invia richieste di caricamento ripristinabile direttamente all'API JSON o XML.
URI sessione
Quando avvii un caricamento riavviabile, Cloud Storage restituisce un URI sessione, che utilizzi nelle richieste successive per caricare i dati effettivi. Un esempio di URI 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 sessione nell'API XML è:
https://storage.googleapis.com/my-bucket/my-file.jpg?upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA
Questo URI 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 ulteriore autenticazione. Per questo motivo, condividi l'URI sessione con cautela e solo tramite HTTPS.
Un URI sessione scade dopo una settimana, ma può essere annullato prima della scadenza. Se effettui una richiesta utilizzando un URI sessione non più valido, ricevi uno dei seguenti errori:
- Un codice di stato
410 Gone
se sono trascorsi meno di una settimana dall'inizio del caricamento. - Un codice di stato
404 Not Found
se sono trascorse più di una settimana dall'inizio del caricamento.
In entrambi i casi, devi avviare un nuovo caricamento ripristinabile, ottenere un nuovo URI sessione e avviare il caricamento dall'inizio utilizzando il nuovo URI sessione.
Controlli di integrità
Ti consigliamo di richiedere un controllo dell'integrità dell'oggetto caricato finale per assicurarti che corrisponda al file di origine. A tale scopo, calcola il digest MD5 del file di origine e aggiungilo 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é è più probabile che il file di origine venga modificato durante l'operazione di caricamento.
Nuovi tentativi e invio di nuovo dei dati
Una volta che Cloud Storage ha eseguito la persistenza dei byte in un caricamento ripristinabile, questi byte non possono essere sovrascritti e Cloud Storage ignora i tentativi di farlo. Per questo motivo, non dovresti inviare dati diversi quando riavvolgi fino a un offset che hai inviato in precedenza.
Ad esempio, supponiamo che tu stia caricando un oggetto di 100.000 byte e la connessione venga interrotta. Quando controlli lo stato, scopri che 50.000 byte sono stati caricati e mantenuti correttamente. Se provi a riavviare il caricamento al 40.000esimo byte, Cloud Storage ignora i byte inviati dal 40.000esimo al 50.000esimo. Cloud Storage inizia a mantenere i dati inviati dal byte 50.001.
Passaggi successivi
- Esegui un caricamento ripristinabile.
- Scopri di più su come riprovare le richieste a Cloud Storage.
- Scopri di più su altri tipi di caricamenti in Cloud Storage.