Caricamenti ripristinabili

Configurazione

In questa pagina vengono descritti i caricamenti ripristinabili in Cloud Storage. I caricamenti ripristinabili sono il metodo consigliato per caricare file di grandi dimensioni, in quanto 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. Questo è diverso da un caricamento di richiesta singola, che contiene tutti i dati dell'oggetto in un'unica richiesta e deve ricominciare dall'inizio se l'operazione non viene completata correttamente.

  • Utilizza un caricamento ripristinabile se stai caricando file di grandi dimensioni o con una connessione lenta. Ad esempio, limiti sulle dimensioni dei file per l'utilizzo di 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 momento in cui viene completato il caricamento.

    • I metadati dell'oggetto impostati dall'utente vengono specificati nella richiesta iniziale. Questi metadati vengono applicati all'oggetto una volta completato il caricamento.

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

In che modo strumenti e 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 i diversi strumenti e fornisce indicazioni sulla configurazione della dimensione del buffer appropriata per l'applicazione.

Console

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

Riga di comando

gcloud CLI utilizza caricamenti ripristinabili nei comandi gcloud storage cp e gcloud storage rsync durante il caricamento di dati in Cloud Storage. Se il caricamento viene interrotto, puoi riprenderlo eseguendo lo stesso comando 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 già completati correttamente.

Librerie client

C++

Le funzioni in storage::Client hanno comportamenti diversi:

Per impostazione predefinita, UploadFile() esegue un caricamento ripristinabile quando l'oggetto è superiore a 20 MiB. In caso contrario, esegue un caricamento semplice o multiparte. Puoi configurare questa soglia impostando MaximumSimpleUploadsSizeOption quando crei 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 blocco. La dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte). Quando utilizzi WriteObject() e UploadFile(), è consigliabile 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 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 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). Le dimensioni del buffer più grandi in genere velocizzano i caricamenti, ma tieni presente che c'è un compromesso tra velocità e memoria.

Go

Per impostazione predefinita, i caricamenti ripristinabili avvengono automaticamente quando il file supera i 16 MiB. Puoi modificare 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 è più piccolo di Writer.ChunkSize o quando Writer.ChunkSize è impostato su 0 e il chunking viene disabilitato. Writer non può riprovare le richieste se ChunkSize è impostato su 0.

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

Tieni presente che l'oggetto non è 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 viene soddisfatta.

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 fisso di 256 KiB. Quando si chiama internamente WriteChannel#setChunkSize(int), la dimensione del buffer viene spostata in un multiplo di 256 KiB.

Il buffering per i caricamenti ripristinabili funziona come una soglia di svuotamento minima, in cui le scritture di dimensioni inferiori a quelle del buffer vengono inserite nel buffer finché una scrittura non esegue il push del numero di byte presenti nel buffer oltre la dimensione del buffer.

Se carichi quantità di dati minori, 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. I caricamenti ripristinabili vengono gestiti automaticamente quando si utilizza il metodo createWriteStream.

Non è prevista una dimensione del buffer predefinita e i caricamenti a blocchi devono essere richiamati manualmente impostando l'opzione chunkSize su CreateResumableUploadOptions. Se viene specificato chunkSize, i dati vengono inviati in richieste HTTP separate, ciascuna con un payload di dimensione chunkSize. Se non viene specificato alcun valore 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 uguale alla dimensione del blocco. La dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte). Buffer di dimensioni maggiori in genere velocizzano i caricamenti, ma c'è un compromesso tra velocità e memoria utilizzata.

PHP

Per impostazione predefinita, i caricamenti ripristinabili avvengono automaticamente quando la dimensione dell'oggetto supera i 5 MB. In caso contrario, vengono eseguiti caricamenti multiparte. Questa soglia non può essere modificata. Puoi forzare il ripristino di un caricamento impostando l'opzione resumable nella funzione upload.

La libreria client PHP utilizza una dimensione del buffer uguale alla dimensione del blocco. 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). Le dimensioni del buffer più grandi in genere velocizzano i caricamenti, ma tieni presente che c'è un compromesso tra velocità e memoria.

Python

I caricamenti ripristinabili si verificano quando l'oggetto ha dimensioni superiori a 8 MiB, mentre i caricamenti multiparte si verificano quando l'oggetto è inferiore a 8 MiB. Questa soglia non può essere modificata. La libreria client Python utilizza una dimensione del buffer uguale alla dimensione del blocco. 100 MiB è la dimensione del buffer predefinita 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 Contenuti multimediali ripristinabili per gestire i caricamenti ripristinabili.

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

Ruby

La libreria client Ruby tratta tutti i caricamenti come caricamenti ripristinabili non 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 restituisce come URI sessione, che utilizzerai in una o più richieste PUT Object per caricare i dati dell'oggetto. Per una guida passo passo sulla creazione della tua logica 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 restituisce come URI sessione, che utilizzerai in una o più richieste PUT Object per caricare i dati dell'oggetto. Per una guida passo passo sulla creazione della tua logica per il caricamento ripristinabile, consulta Esecuzione di caricamenti ripristinabili.

Caricamenti ripristinabili di dimensioni sconosciute

Il meccanismo di caricamento ripristinabile supporta trasferimenti in cui le dimensioni del file non sono note in anticipo. Questo può essere utile per casi come la compressione immediata di un oggetto durante il caricamento, dato che è difficile prevedere la dimensione esatta del file compresso all'inizio di un trasferimento. Il meccanismo è utile se vuoi trasmettere in flusso un trasferimento che può essere ripreso dopo essere stato interrotto o se la codifica del trasferimento in blocchi non funziona per la tua applicazione.

Per ulteriori informazioni, vedi Caricamenti in streaming.

Rendimento dei caricamenti

Scelta delle regioni per le sessioni

I caricamenti ripristinabili vengono bloccati nell'area geografica in cui li avvii. Ad esempio, se avvii un caricamento ripristinabile negli Stati Uniti e fornisci l'URI della sessione a un cliente in Asia, il caricamento continua attraverso gli 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 instradare le richieste dei clienti, in modo da mantenere il traffico localizzato in un'area geografica.

Caricamento a blocchi

Se possibile, evita di suddividere un trasferimento in blocchi più piccoli e carica invece l'intero contenuto in un unico blocco. Evitare il chunking rimuove i costi aggiuntivi di latenza e i costi delle operazioni dall'esecuzione di query sull'offset persistente di ogni blocco, nonché migliora la velocità effettiva. Tuttavia, dovresti valutare il caricamento in blocchi se:

  • I dati di origine vengono generati in modo dinamico e vuoi limitarne la quantità necessari per il buffering sul lato client in caso di caricamento non riuscito.

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

Se utilizzi l'API JSON o XML e il client riceve un errore, può eseguire una query sul server per individuare 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 questo aspetto automaticamente per tuo conto. Per ulteriori indicazioni sul chunking per librerie client specifiche, consulta In che modo strumenti e API utilizzano caricamenti ripristinabili.

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 di sessione, che utilizzerai nelle richieste successive per caricare i dati effettivi. Ecco 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

Ecco 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 di sessione funge da token di autenticazione, perciò le richieste che lo utilizzano non devono essere firmate e possono essere utilizzati da chiunque per caricare dati nel bucket di destinazione senza ulteriore autenticazione. Per questo motivo, sii prudente nel condividere l'URI della sessione e lo condividi solo tramite HTTPS.

Un URI sessione scade dopo una settimana, ma può essere annullato prima della scadenza. Se effettui una richiesta utilizzando un URI di sessione non più valido, viene visualizzato 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, 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 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.

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

Quando avvii un caricamento ripristinabile, il valore x-goog-content-sha256 verrà ignorato. Ti consigliamo quindi di impostare x-goog-content-sha256 su UNSIGNED-PAYLOAD.

Nuovi tentativi e reinvio dei dati

Una volta che Cloud Storage rende persistenti i byte in un caricamento ripristinabile, questi byte non possono essere sovrascritti e Cloud Storage ignora i tentativi in tal senso. Per questo motivo, non devi inviare dati diversi quando torni indietro a un offset inviato in precedenza.

Ad esempio, supponiamo che tu stia caricando un oggetto da 100.000 byte e che la connessione si interrompa. Quando controlli lo stato, noti che 50.000 byte sono stati caricati e resi persistenti correttamente. 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 rendere persistenti i dati inviati nel byte 50.001.

Passaggi successivi