In questa pagina vengono descritti i caricamenti ripristinabili in Cloud Storage. I caricamenti ripristinabili sono consigliato per caricare file di grandi dimensioni, in quanto non è necessario riavviale dall'inizio se si verifica un errore di rete durante il caricamento è in corso.
Introduzione
Un caricamento ripristinabile ti consente di riprendere le operazioni di trasferimento di dati su 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 caricamento di richiesta singola, che contiene tutti i dati dell'oggetto in un unico e deve ricominciare dall'inizio se non riesce a metà.
Utilizza un caricamento ripristinabile se stai caricando file di grandi dimensioni o su un connessione lenta. Ad esempio limiti 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'inizio, ma puoi potrà 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 versione finale richiesta se includi intestazioni con prefisso
X-Goog-Meta-
in richiesta.
- Un caricamento ripristinabile completato è considerato un'operazione di classe A.
In che modo strumenti e API utilizzano i caricamenti ripristinabili
A seconda di come interagisci con Cloud Storage, caricamenti ripristinabili potrebbero essere gestite automaticamente per tuo conto. Questa sezione descrive le il comportamento di caricamento ripristinabile per i vari strumenti e fornisce indicazioni su e configurare la dimensione del buffer appropriata per l'applicazione.
Console
La console Google Cloud gestisce automaticamente i caricamenti ripristinabili per conto tuo. Tuttavia, se aggiorni o esci dalla scheda Console Google Cloud mentre è in corso un caricamento, quest'ultimo viene annullato.
Riga di comando
gcloud CLI utilizza caricamenti ripristinabili
I comandi gcloud storage cp
e gcloud storage rsync
quando
e il caricamento di dati in Cloud Storage. Se il caricamento viene interrotto:
puoi riprenderla eseguendo lo stesso comando che hai usato per avviare
per il caricamento. Quando riprendi un caricamento di questo tipo che include più file, utilizza
il flag --no-clobber
per impedire il ricaricamento dei file
completato correttamente.
Librerie client
C++
Le funzioni in storage::Client
hanno comportamenti diversi:
Client::WriteObject()
esegue sempre un'operazione ripristinabile per il caricamento.Client::InsertObject()
esegue sempre una semplice caricamento multiparte.Client::UploadFile()
può eseguire una caricamento semplice, caricamento multiparte.
Per impostazione predefinita, UploadFile()
esegue un caricamento ripristinabile quando l'oggetto
sia superiore a 20 MiB. In caso contrario, esegue un semplice caricamento
caricamento 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 a quella del blocco
dimensioni. La dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte).
Quando usi WriteObject()
e UploadFile()
, potrebbe essere utile
considerare i compromessi tra velocità di caricamento e utilizzo della memoria. Utilizzo
buffer di piccole dimensioni per caricare oggetti di grandi dimensioni possono rallentare il caricamento. Per maggiori informazioni
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
impostazione ChunkSize
su UploadObjectOptions
. La
la dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte). Più grande
Le dimensioni del buffer di solito velocizzano i caricamenti, ma tieni presente che
un compromesso tra velocità
e utilizzo della memoria.
Vai
Per impostazione predefinita, i caricamenti ripristinabili avvengono automaticamente quando il file viene
superiore a 16 MiB. Modifica il limite per eseguire il ripristino
caricamenti con Writer.ChunkSize
. I caricamenti ripristinabili sono
vengono sempre suddivisi in blocchi quando si usa la libreria client Go.
I caricamenti multiparte si verificano quando l'oggetto è più piccolo di
Writer.ChunkSize
o quando Writer.ChunkSize
è impostato su 0, dove
il chunking viene disabilitato. Il valore Writer
è
impossibile ritentare 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). Più grande
Le dimensioni del buffer di solito velocizzano i caricamenti, ma tieni presente che
un compromesso tra velocità
e utilizzo della memoria. Se esegui più volte
di caricamenti ripristinabili contemporaneamente, devi impostare Writer.ChunkSize
su un
inferiore a 16 MiB per evitare un eccesso di memoria.
Tieni presente che l'oggetto non viene finalizzato in Cloud Storage fino a quando
chiami Writer.Close()
e ricevi un successo
la risposta corretta. Writer.Close
restituisce un errore se la richiesta non è
riuscito.
Java
La libreria client Java prevede metodi separati per caricamenti multiparte e ripristinabili. La 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 predefinita del buffer è 15 MiB. Puoi impostare la dimensione del buffer
utilizzando il metodo WriteChannel#setChunkSize(int)
oppure
passando un parametro bufferSize
alla
Storage#createFrom
. La dimensione del buffer ha un
massimo di 256 KiB. Durante la chiamata
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 svuotamento minima. in cui le scritture più piccole di quelle del buffer vengono memorizzate nel buffer fino a quando esegue il push del numero di byte presenti nel buffer sopra la dimensione del buffer.
Se carichi quantità di dati minori, valuta la possibilità di
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 il ripristino
caricamenti impostando resumable
su UploadOptions
su
false
. I caricamenti ripristinabili vengono gestiti automaticamente quando si utilizza
Metodo createWriteStream
.
Non è prevista una dimensione del buffer predefinita e i caricamenti a blocchi devono essere
richiamato manualmente impostando l'opzione chunkSize
CreateResumableUploadOptions. Se chunkSize
è
specificato, i dati vengono inviati in richieste HTTP separate, ciascuna con un
payload di dimensione chunkSize
. Se non viene specificato alcun valore chunkSize
e viene
di una libreria sta eseguendo un caricamento ripristinabile, tutti i dati vengono trasmessi in un
a una singola richiesta HTTP.
La libreria client Node.js utilizza una dimensione del buffer uguale a quella del blocco dimensioni. La dimensione del buffer deve essere un multiplo di 256 KiB (256 x 1024 byte). Buffer di grandi dimensioni in genere velocizzano i caricamenti, ma tieni presente che un compromesso tra velocità e memoria utilizzata.
PHP
Per impostazione predefinita, i caricamenti ripristinabili avvengono automaticamente quando la dimensione dell'oggetto
sia superiore a 5 MB. In caso contrario, vengono eseguiti caricamenti multiparte. Questa soglia
non possono essere modificate. Puoi forzare il caricamento ripristinabile impostando il parametro
resumable
nella funzione upload
.
La libreria client PHP utilizza una dimensione del buffer uguale alla dimensione del blocco
dimensioni. 256 KiB è la dimensione del buffer predefinita 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). Più grande
Le dimensioni del buffer di solito velocizzano i caricamenti, ma tieni presente che
un compromesso tra velocità
e utilizzo della memoria.
Python
I caricamenti ripristinabili si verificano quando l'oggetto è superiore a 8 MiB,
e caricamenti multiparte si verificano quando l'oggetto è inferiore a 8 MiB
Questa soglia non può essere modificata. La libreria client Python utilizza un
una dimensione del buffer uguale alla dimensione del blocco. 100 MiB è
la dimensione predefinita del buffer usata per un caricamento ripristinabile
modificare la dimensione del buffer impostando
Proprietà blob.chunk_size
.
Per eseguire sempre un caricamento ripristinabile.
a prescindere 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
per gestire i caricamenti ripristinabili.
La dimensione del blocco deve essere un multiplo di 256 KiB (256 x 1024 byte). Più grande le dimensioni dei chunk in genere velocizzano i caricamenti, ma tieni presente che c'è un compromesso tra velocità e utilizzo della memoria.
Ruby
La libreria client Ruby tratta tutti i caricamenti come ripristinabili non in blocchi caricamenti.
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 la
caricamento ripristinabile. Questa richiesta restituisce come URI di sessione che
poi utilizzalo 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 ripristino
per il caricamento, 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 la
caricamento ripristinabile. Questa richiesta restituisce come URI di sessione che
poi utilizzalo 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 ripristino
per il caricamento, 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 noto in anticipo. Questo può essere utile per casi come la compressione di un oggetto al momento del caricamento, perché è difficile prevedere la dimensione esatta del file. per il file compresso all'inizio del trasferimento. Il meccanismo è utile se vuoi trasmettere in streaming un trasferimento che può essere ripreso dopo essere stato o se la codifica del trasferimento a 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. Per Ad esempio, se avvii un caricamento ripristinabile negli Stati Uniti e fornisci l'URI della sessione per un cliente in Asia, il caricamento avviene ancora negli Stati Uniti. Per ridurre il traffico tra regioni e migliorare le prestazioni, devi mantenere un caricamento ripristinabile nella regione in cui è stato creato.
Se utilizzi un'istanza Compute Engine per avviare un caricamento ripristinabile, deve trovarsi nella stessa località del bucket Cloud Storage in cui carichi contenuti. Potrai quindi utilizzare un servizio IP geografico per scegliere Compute Engine regione a cui instrada le richieste dei clienti, in modo da mantenere il traffico localizzato in una regione geografica.
Caricamento a blocchi
Se possibile, evita di suddividere un trasferimento in blocchi più piccoli e caricalo l'intero contenuto in un unico blocco. Evitare il chunking rimuove la latenza aggiuntiva e i costi delle operazioni derivanti dall'esecuzione di query sull'offset persistente di ciascun blocco e migliora la velocità effettiva. Tuttavia, valuta la possibilità di caricare in blocchi quando:
I dati di origine vengono generati in modo dinamico e vuoi limitare il modo in cui ne devi eseguire il buffering sul lato client nel caso in cui il caricamento non vada a buon fine.
I tuoi clienti hanno limitazioni per le dimensioni delle richieste, come nel caso di molti browser.
Se utilizzi l'API JSON o XML e il tuo client riceve un errore, può esegui una query sul server per trovare l'offset persistente e riprendi il caricamento rimanente byte da quell'offset. Console Google Cloud, Google Cloud CLI e client le librerie gestiscono questo aspetto automaticamente per tuo conto. Consulta In che modo strumenti e API utilizzano i caricamenti ripristinabili per ulteriori indicazioni sul chunking per librerie client specifiche.
Considerazioni
Questa sezione è utile se stai creando un tuo client che invia le richieste di caricamento ripristinabile direttamente nell'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 sessione funge da token di autenticazione, pertanto le richieste che lo utilizzano non devono essere firmati e possono essere utilizzati da chiunque per caricare i dati nella destinazione senza ulteriori autenticazioni. Per questo motivo, sii prudente nel condividendo l'URI della sessione solo tramite HTTPS.
Un URI sessione scade dopo una settimana, ma può essere annullato prima del giorno in scadenza. Se effettui una richiesta utilizzando un URI sessione non più valido, ricevi uno dei seguenti errori:
- Un codice di stato
410 Gone
se è passata meno di una settimana dall'ultima caricamento avviato. - Un codice di stato
404 Not Found
se è passata più di una settimana da il caricamento è stato avviato.
In entrambi i casi, devi avviare un nuovo caricamento ripristinabile e ottenere una nuova sessione. e avvia 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
Digest MD5 del file di origine e aggiunta alla richiesta Content-MD5
intestazione.
Il controllo dell'integrità del file caricato è particolarmente importante se stai caricare un file di grandi dimensioni per un lungo periodo di tempo, con l'aumento probabilità che il file di origine venga modificato durante il caricamento operativa.
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
Quando 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 che hai inviato in precedenza.
Ad esempio, supponiamo che tu stia caricando un oggetto da 100.000 byte e che la tua connessione interrotto. Quando controlli lo stato, scopri che 50.000 byte sono stati è stato caricato e mantenuto correttamente. Se tenti di riavviare il caricamento all'indirizzo byte 40.000, Cloud Storage ignora i byte inviati da 40.000 a 50.000. Cloud Storage inizia a rendere persistenti i dati inviati a byte 50.001.
Passaggi successivi
- Esegui un caricamento ripristinabile.
- Scopri di più su come ritentare le richieste a Cloud Storage.
- Scopri altri tipi di caricamenti in Cloud Storage.