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 singola richiesta, che contiene tutti i dati dell'oggetto in una singola richiesta e deve riavviarsi dall'inizio se si verifica un errore a metà del caricamento.

Un caricamento ripristinabile viene eseguito tramite una sessione di caricamento ripristinabile. Quando avvii un caricamento, Cloud Storage crea una sessione e restituisce un URI di sessione univoco. Tu o un client delegato (ad esempio un browser web) inviate quindi i dati dell'oggetto a questo URI di sessione in una o più richieste. Ogni sessione rimane attiva per un massimo di una settimana, consentendo di riprendere i caricamenti se vengono interrotti da interruzioni di rete o riavvii del client.

  • Utilizza un caricamento ripristinabile se stai caricando file di grandi dimensioni o se stai caricando tramite una connessione lenta. Per i limiti delle dimensioni dei file per l'utilizzo dei caricamenti ripristinabili, consulta Considerazioni sulle dimensioni di caricamento.

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

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

    • L'ora di creazione dell'oggetto si basa sul momento in cui il caricamento viene completato.

    • I metadati dell'oggetto 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 di metadati personalizzati nella richiesta finale se includi le 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 caricamento ripristinabile per i diversi strumenti e fornisce indicazioni sulla configurazione della dimensione del buffer appropriata per la tua applicazione.

Console

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

Riga di comando

Gcloud CLI utilizza i caricamenti ripristinabili nei 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 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 i caricamenti ripristinabili, le librerie client fungono da wrapper intorno all'API JSON Cloud Storage.

C++

Le funzioni in storage::Client vengono eseguite con un comportamento diverso:

Per impostazione predefinita, UploadFile() esegue un caricamento ripristinabile quando l'oggetto è più grande di 20 MiB. In caso contrario, esegue un caricamento semplice o un caricamento multiparte. Puoi configurare questa soglia impostando MaximumSimpleUploadsSizeOption quando crei un storage::Client.

La dimensione predefinita del buffer è 8 MiB, 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(), potresti prendere in considerazione i compromessi tra velocità di caricamento e memoria utilizzata. 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 chunk. 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 esiste un compromesso tra velocità e memoria utilizzata.

Go

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

I caricamenti multiparte vengono eseguiti quando l'oggetto è più piccolo di Writer.ChunkSize o quando Writer.ChunkSize è impostato su 0, nel qual caso la suddivisione in chunk viene disattivata. Il 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). Le dimensioni del buffer più grandi in genere velocizzano i caricamenti, ma tieni presente che esiste un compromesso tra velocità e memoria utilizzata. Se esegui più caricamenti ripristinabili 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 ha metodi separati per i 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 Storage#createFrom metodo. La dimensione del buffer ha un minimo fisso 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 ripristinabili impostando resumable su UploadOptions su false. I caricamenti ripristinabili vengono gestiti automaticamente quando utilizzi il createWriteStream metodo.

Non esiste una dimensione predefinita del buffer e i caricamenti suddivisi in chunk 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 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 uguale alla dimensione del chunk. 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 esiste un compromesso tra velocità e memoria utilizzata.

PHP

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

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). Le dimensioni del buffer più grandi in genere velocizzano i caricamenti, ma tieni presente che esiste un compromesso tra velocità e memoria utilizzata.

Python

I caricamenti ripristinabili vengono eseguiti quando l'oggetto è più grande di 8 MiB, mentre i caricamenti multiparte vengono eseguiti 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. La dimensione predefinita del buffer utilizzata per un caricamento ripristinabile è 100 MiB e puoi modificarla impostando la blob.chunk_size proprietà.

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). Le dimensioni dei chunk più grandi in genere velocizzano i caricamenti, ma tieni presente che esiste un compromesso tra velocità e memoria utilizzata.

Ruby

La libreria client Ruby tratta tutti i caricamenti come caricamenti ripristinabili non suddivisi in chunk.

API REST

API JSON

L'API JSON Cloud Storage 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 XML Cloud Storage 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.

Se un client multiorigine (ad esempio un browser web) caricherà i dati, includi l'intestazione Origin del client nella richiesta iniziale che crea la sessione. Cloud Storage determina le intestazioni CORS in base alla richiesta iniziale; se Origin viene omesso durante l'avvio della sessione, Cloud Storage non includerà le intestazioni CORS nelle risposte alle richieste di caricamento successive, causando il fallimento delle richieste multiorigine del browser.

Caricamenti ripristinabili di dimensioni sconosciute

Il meccanismo di caricamento ripristinabile supporta i trasferimenti in cui le dimensioni del file non sono note in anticipo. Questo può essere utile in casi come la compressione di un oggetto on-the-fly 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 chunk non funziona per la tua applicazione.

Per ulteriori informazioni, consulta Caricamenti di streaming.

Prestazioni di caricamento

Scelta delle regioni di sessione

I caricamenti ripristinabili sono ancorati alla 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 carichi i dati. Puoi quindi utilizzare un servizio IP geografico per scegliere la regione Compute Engine a cui indirizzare le richieste dei clienti, il che aiuta a mantenere il traffico localizzato in una regione geografica.

Caricamento in chunk

Se possibile, evita di suddividere un trasferimento in chunk più piccoli e carica invece l'intero contenuto in un singolo chunk. Evitare la suddivisione in chunk elimina i costi di latenza e le spese operative aggiuntive per l'esecuzione di query sull'offset persistente di ogni chunk, oltre a migliorare la velocità effettiva. Tuttavia, devi prendere in considerazione il caricamento in chunk quando:

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

  • I tuoi client hanno limitazioni relative alle dimensioni delle 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 l'offset persistente e riprendere il caricamento dei byte rimanenti da quell'offset. La Google Cloud console, Google Cloud CLI e le librerie client gestiscono automaticamente questa operazione per tuo conto. Per ulteriori indicazioni sulla suddivisione in chunk per librerie client specifiche, consulta Come gli strumenti e le 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 API XML.

URI di sessione

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

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

Ecco un esempio di URI di sessione nell'API XML:

 https://storage./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 i dati nel bucket di destinazione senza ulteriori autenticazioni. Per questo motivo, condividi l'URI di sessione con cautela e solo tramite HTTPS.

Un URI di 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'avvio del caricamento.
  • Un codice di stato 404 Not Found se è trascorsa più di una settimana dall'avvio del caricamento.

In entrambi i casi, o se perdi l'URI di sessione prima del completamento del caricamento, 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 caricato finale per assicurarti che corrisponda al file di origine. Puoi farlo calcolando il digest MD5 del file di origine e aggiungendolo all'Content-MD5intestazione della richiesta.

Il controllo dell'integrità del file caricato è particolarmente importante se carichi 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.

Tuttavia, non puoi eseguire controlli di integrità su parti o chunk intermedi di un caricamento ripristinabile, perché i caricamenti ripristinabili sono progettati per consentirti di riprendere un caricamento in caso di interruzione imprevista.

Nuovi tentativi e invio di 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 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 connessione venga interrotta. Quando controlli lo stato, scopri che 50.000 byte sono stati caricati e resi persistenti 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 al byte 50.001.

Passaggi successivi