Vai al contenuto principale

Multipart Upload

Intro

Multipart Upload è un modo per caricare file di grandi dimensioni su un Object Storage S3 compatibile come Cubbit dividendoli in parti più piccole e caricando ogni parte in parallelo.

Il caricamento simultaneo di più parti migliora la velocità di caricamento e offre una maggiore affidabilità e possibilità di ripresa in caso di errori o interruzioni della rete. Infatti, se il caricamento di una singola parte si interrompe le altre parti rimangono inalterate e il processo può riprendere in qualsiasi momento. Le parti vengono poi combinate in un unico oggetto sul server.

Questo ha diversi vantaggi:

  • Velocità di caricamento: il caricamento di più parti in parallelo rende il processo di caricamento più veloce.
  • Recupero post guasto: se la connessione cade durante il caricamento, l'oggetto è ancora al sicuro. Le parti caricate in precedenza vengono conservate e il caricamento può riprendere con le parti mancanti.
  • Pausa del caricamento: Il caricamento dell'oggetto può essere interrotto e ripreso senza che sia necessario riavviare l'intero caricamento.

Questa funzione è ideale per il caricamento di oggetti di grandi dimensioni, per massimizzare il throughput della rete o per il caricamento di file in una rete instabile dove i guasti sono frequenti.

Multipart Upload passo dopo passo

Il processo di multipart upload prevede le seguenti fasi:

  1. Avvio del caricamento: Avvia il processo di caricamento inviando una richiesta API CreateMultipartUpload. Questa richiesta restituisce un ID di caricamento, che viene utilizzato per identificare il caricamento nelle richieste API successive.
  2. Caricamento delle parti: Carica parti del file in parallelo inviando richieste API UploadPart con l'ID di caricamento e un numero di parte. Il numero di parte deve iniziare con 1 e aumentare per ogni parte.
  3. Completamento del caricamento: Una volta caricate tutte le parti, invia una richiesta API CompleteMultipartUpload con l'ID di caricamento e un elenco di numeri di parte e dei corrispondenti ETag (un hash dei dati).
  4. Verifica del caricamento: Conferma il completamento del caricamento scaricando l'intero file con GetObject e confrontandolo con il file originale.
Come fermare un caricamento

In caso di fallimento, è possibile interrompere un multipart upload con una richiesta API AbortMultipartUpload che scarterà le parti caricate e libererà spazio di archiviazione.

Uso

Vediamo come lavorare con questa funzione utilizzando i comandi della CLI di AWS s3api.

Creare un caricamento multipart

Iniziamo inizializzando un upload multipart:

aws s3api create-multipart-upload --endpoint https://s3.cubbit.eu --bucket my-cubbit-bucket --key sergio.jpg

Questo stamperà un UploadId nell'output, prendiamone nota.

Avete dimenticato di scrivere l'UploadId?

Non c'è da preoccuparsi, se si è dimenticato di scrivere l'UploadId si può eseguire un ListMultipartUploads, che mostra un elenco di upload multipart in corso con il loro ID.

Mostra i caricamenti multipart in corso

Se in qualsiasi momento è necessario controllare quali caricamenti multipart sono ancora in corso:

aws s3api list-multipart-uploads --endpoint https://s3.cubbit.eu --bucket my-cubbit-bucket --key sergio.jpg

Caricare alcune parti

Poi possiamo caricare alcune parti, ad esempio due:

aws s3api upload-part --endpoint https://s3.cubbit.eu --bucket my-cubbit-bucket --key sergio.log --upload-id <UploadId> --part-number 1 --body ~/sergio-part1.log

aws s3api upload-part --endpoint https://s3.cubbit.eu --bucket my-cubbit-bucket --key sergio.log --upload-id <UploadId> --part-number 2 --body ~/sergio-part2.log

Questi stampano i valori di ETag nell'output, prendiamone nota.

Avete dimenticato di scrivere gli ETag?

Non c'è da preoccuparsi, se si dimentica di scrivere gli ETag si può eseguire un ListParts, che mostra un elenco di parti con il loro numero di parte e l'ETag.

Caricare una parte copiando da un altro oggetto

Quando carichiamo una parte, possiamo anche omettere il body indicando invece un oggetto esistente come sorgente da copiare:

aws s3api upload-part-copy --endpoint https://s3.cubbit.eu --bucket my-cubbit-bucket --key sergio.log --upload-id <UploadId> --part-number 1 --copy-source "my-cubbit-bucket/my-source-object"

Oppure, possiamo copiare solo una porzione dell'oggetto sorgente. Ad esempio i primi 1024 bytes:

aws s3api upload-part-copy --endpoint https://s3.cubbit.eu --bucket my-cubbit-bucket --key sergio.log --upload-id <UploadId> --part-number 1 --copy-source "my-cubbit-bucket/my-source-object" --copy-source-range bytes=0-1023

Così come per il caricamento di parti ordinario, bisognerà prendere nota del valore diETag stampato.

Possibili errori durante la copia

Acluni oggetti molto datati potrebbero essere consdierati non idonei ad essere copiati mostrando l'errore "Invalid source object". Se doveste incorrere in questo caso potete rivolgervi al nostro supporto tecnico.

Mostra le parti caricate

Se in qualsiasi momento è necessario controllare quali parti sono già state caricate:

aws s3api list-parts --endpoint https://s3.cubbit.eu --bucket my-cubbit-bucket --key sergio.jpg --upload-id <UploadId>

Completare un caricamento multiparte

Infine, una volta che tutte le parti sono state caricate, possiamo creare l'oggetto finale da esse, completando il caricamento:

aws s3api complete-multipart-upload --endpoint https://s3.cubbit.eu --bucket my-cubbit-bucket --key sergio.jpg --upload-id <UploadId> --multipart-upload "Parts=[{ETag=<ETag prima parte>,PartNumber=1},{ETag=<ETag seconda parte>,PartNumber=2}]"

Limiti

Il multipart upload ha alcune limitazioni descritte nella seguente tabella:

ElementoLimite
Massima dimensione oggetto5 TiB
Numero massimo di parti per caricamento10,000
Numero identificativo parte1 to 10,000 (inclusive)
Minima dimensione parte5 MiB
Massima dimensione parte5 GiB
Massimo numero di parti ritornate da una richiesta lista parti1000
Massimo numero di multipart uploads ritornate da una richiesta lista multipart uploads1000