Caricamento degli oggetti - Amazon Simple Storage Service

Caricamento degli oggetti

Quando un file viene caricato in Amazon S3, viene archiviato come oggetto di S3. Gli oggetti sono composti dai dati e dai metadata dei file che descrivono l'oggetto. Un bucket può avere un numero illimitato di oggetti. Per caricare file e cartelle in un bucket Amazon S3, è necessario disporre delle autorizzazioni in scrittura per il bucket. Per ulteriori informazioni sulle autorizzazioni di accesso, consultare Identity and Access Management in Amazon S3.

In un bucket S3 è possibile caricare qualsiasi tipo di file: immagini, backup, dati, film e così via. La dimensione massima di un file che è possibile caricare utilizzando la console Amazon S3 è 160 GB. Per caricare un file di dimensioni maggiori di 160 GB, utilizza la AWS CLI, l'SDK AWS o REST API di Amazon S3.

Se si carica un oggetto con un nome della chiave già esistente in un bucket che supporta la funzione Controllo delle versioni, Amazon S3 crea un'altra versione dell'oggetto anziché sostituire l'oggetto esistente. Per ulteriori informazioni sulla funzione Controllo delle versioni, consulta Utilizzo della console S3.

A seconda della dimensione dei dati da caricare, in Amazon S3 sono disponibili le seguenti opzioni:

  • Carica un oggetto in una singola operazione utilizzando gli SDK AWS, REST API o la AWS CLI: con una singola operazione PUT è possibile caricare oggetti di dimensioni fino a 5 GB.

  • Caricare un singolo oggetto tramite la console di Amazon S3 - Con la console di Amazon S3, è possibile caricare un singolo oggetto fino a 160 GB di dimensioni.

  • Carica un oggetto in parti utilizzando gli SDK AWS, REST API o la CLI AWS CLI: utilizzando l'API di caricamento in più parti, è possibile caricare un singolo oggetto di grandi dimensioni (fino a 5 TB).

    L'API per il caricamento in più parti è concepita per migliorare l'esperienza di caricamento per gli oggetti di dimensioni maggiori. È possibile caricare un oggetto in parti. Queste parti possono essere caricate in modo indipendente, in qualsiasi ordine e in parallelo. È possibile utilizzare un caricamento in più parti per gli oggetti con una dimensione compresa tra 5 MB e 5 TB. Per ulteriori informazioni, consulta Caricamento e copia di oggetti utilizzando il caricamento in più parti.

Quando si carica un oggetto, è possibile richiedere che venga crittografato da Amazon S3 prima del salvataggio su disco e quindi decrittato quando viene eseguito il download. Per ulteriori informazioni, consulta Protezione dei dati tramite crittografia.

Questa procedura spiega come caricare oggetti e cartelle in un bucket S3 utilizzando la console.

Quando carichi un oggetto, il nome della chiave oggetto è costituito dal nome del file e da qualsiasi prefisso facoltativo. Nella console Amazon S3, puoi creare cartelle per organizzare i tuoi oggetti. In Amazon S3, le cartelle sono rappresentate come prefissi visualizzati nel nome della chiave oggetto. Se carichi un singolo oggetto in una cartella nella console Amazon S3, il nome della cartella viene incluso nel nome della chiave oggetto.

Ad esempio, se carichi un oggetto denominato sample1.jpg in una cartella denominata backup, il nome della chiave è backup/sample1.jpg. Tuttavia, l'oggetto viene visualizzato nella console come sample1.jpg nella cartella backup. Per ulteriori informazioni sui nomi delle chiavi, consultare Utilizzo dei metadati degli oggetti.

Nota

Se rinomini un oggetto o modifichi una delle proprietà nella console Amazon S3, ad esempio Storage Class (Classe di storage), Encryption (Crittografia) o Metadata (Metadati), viene creato un nuovo oggetto per sostituire quello precedente. Se è abilitata la funzione Controllo versioni S3, viene creata una nuova versione dell'oggetto e l'oggetto esistente diventa una versione precedente. Il ruolo che modifica la proprietà diventa anche il proprietario del nuovo oggetto o della versione dell'oggetto.

Quando si carica una cartella, Amazon S3 carica nel bucket tutti i file e le sottocartelle inclusi nella cartella specificata, quindi assegna un nome della chiave dell'oggetto, ossia una combinazione del nome del file caricato e del nome della cartella. Ad esempio, se si carica una cartella denominata /images contenente due file, sample1.jpg e sample2.jpg, Amazon S3 carica i file, quindi assegna i nomi delle chiavi corrispondenti, images/sample1.jpg e images/sample2.jpg. I nomi delle chiavi includono il nome della cartella come prefisso. La console Amazon S3 visualizza solo la parte del nome della chiave che segue l'ultimo simbolo /. Ad esempio, in una cartella di immagini gli oggetti images/sample1.jpg e images/sample2.jpg sono visualizzati come sample1.jpg e sample2.jpg.

Per caricare cartelle e file in un bucket S3
  1. Accedi alla AWS Management Console e apri la console Amazon S3 all'indirizzo https://console.aws.amazon.com/s3/.

  2. Nell'elenco Buckets (Bucket) scegliere il nome del bucket in cui si desidera caricare le cartelle o i file.

  3. Scegli Carica.

  4. Nella finestra Carica completa una delle seguenti operazioni:

    • Trascina e rilascia file e cartelle nella finestra Carica .

    • Scegli Aggiungi file o Aggiungi cartella, scegli i file o le cartelle da caricare e seleziona Apri.

  5. Per abilitare il controllo delle versioni, in Destinazione, seleziona Abilita controllo delle versioni del bucket.

  6. Per caricare i file e le cartelle elencati senza configurare ulteriori opzioni di caricamento, nella parte inferiore della pagina scegli Carica.

    Amazon S3 caricherà i tuoi oggetti e le tue cartelle. Al termine del caricamento, sarà visualizzato un messaggio di successo nella pagina Carica: stato .

Per configurare proprietà aggiuntive dell'oggetto
  1. Per modificare le autorizzazioni della lista di controllo degli accessi, scegli Permissions (Autorizzazioni).

  2. In Access control list (ACL) Lista di controllo degli accessi (ACL), modifica le autorizzazioni.

    Per informazioni sulle autorizzazioni di accesso agli oggetti, consulta Utilizzo della console S3 per impostare le autorizzazioni ACL per un oggetto. Puoi concedere l'accesso in lettura ai tuoi oggetti al pubblico (chiunque) per tutti i file che stai caricando. Ti consigliamo di non modificare l'impostazione di default per l'accesso pubblico in lettura. La concessione dell'accesso pubblico in lettura si applica a un piccolo sottoinsieme di casi d'uso, ad esempio quando i bucket vengono usati per i siti Web. È sempre possibile apportare modifiche alle autorizzazioni dell'oggetto dopo averlo caricato.

  3. Per configurare altre proprietà scegli Properties (Proprietà).

  4. Nella sezione Classe di storage seleziona la classe di storage per i file che si stanno caricando.

    Per ulteriori informazioni sulle classi di storage, consulta Utilizzo delle classi di storage di Amazon S3.

  5. Per aggiornare le impostazioni di crittografia per gli oggetti, in Impostazioni di crittografia lato server completa le operazioni riportate di seguito.

    1. Scegli Specify an encryption key (Specifica una chiave di crittografia).

    2. Per crittografare i file caricati utilizzando chiavi gestite da Amazon S3, seleziona Chiave Amazon S3 (SSE-S3).

      Per ulteriori informazioni, consulta Utilizzo della crittografia lato server con chiavi di crittografia gestite da Amazon S3 (SSE-S3).

    3. Per crittografare i file caricati utilizzando AWS Key Management Service (AWS KMS), scegli Chiave AWS Key Management Service (SSE-KMS). Quindi scegli un'opzione per la chiave AWS KMS.

      • AWS managed key (Chiave gestita da AWS): scegli una chiave gestita da AWS.

      • Choose from your KMS root keys (Scegli tra le chiavi root KMS): scegli una chiave gestita dal cliente da un elenco di chiavi KMS nella stessa regione del bucket.

        Per ulteriori informazioni sulla creazione delle chiavi gestite dal cliente, consulta Creazione di chiavi nella Guida per Developer di AWS Key Management Service. Per ulteriori informazioni sulla protezione dei dati con AWS KMS, consulta la sezione Utilizzo della crittografia lato server con AWS Key Management Service (SSE-KMS).

      • Enter KMS root key ARN (Inserisci l'ARN della chiave root KMS): specifica l'ARN della chiave AWS KMS per una chiave gestita dal cliente e inserisci l'Amazon Resource Name (ARN).

        Puoi utilizzare l'ARN della chiave root KMS per dare a un account esterno la possibilità di utilizzare un oggetto protetto da una AWS KMS key. A tale scopo, seleziona Enter KMS root key ARN (Specifica ARN della chiave root KMS)e inserisci l'Amazon Resource Name (ARN) per l'account esterno. Gli amministratori di un account esterno dotati delle autorizzazioni d'uso per un oggetto protetto dalla chiave KMS possono limitare ulteriormente l'accesso creando una policy IAM a livello di risorsa.

      Nota

      Per crittografare gli oggetti in un bucket, puoi utilizzare solo le AWS KMS keys disponibili nella stessa Regione AWS del bucket.

  6. Per utilizzare checksum aggiuntivi, scegli On (Attivato). Per Checksum function (Funzione checksum), scegli la funzione che desideri utilizzare. Amazon S3 calcola e archivia il valore del checksum dopo aver ricevuto l'intero oggetto. Puoi utilizzare la casella Precalculated value (Valore precalcolato) per fornire un valore precalcolato. In tal caso, Amazon S3 confronta il valore specificato con il valore calcolato. Se i due valori non corrispondono, Amazon S3 genera un errore.

    I checksum aggiuntivi ti consentono di specificare l'algoritmo di checksum che desideri utilizzare per verificare i dati. Per ulteriori informazioni sui checksum aggiuntivi, consulta Verifica dell'integrità degli oggetti.

  7. Per aggiungere tag a tutti gli oggetti che si stanno caricando, scegliere Add tag (Aggiungi tag). Digitare un nome di tag nel campo Key (Chiave). Digitare un valore per il tag.

    Il tagging ti consente di catalogare lo storage. Ogni tag è una coppia chiave-valore. I valori delle chiavi e dei tag fanno distinzione tra maiuscole e minuscole. Puoi avere un massimo di 10 tag per oggetto. Una chiave di tag può essere composta da un massimo di 128 caratteri Unicode e i valori di tag possono essere composti da un massimo di 255 caratteri Unicode. Per ulteriori informazioni sui tag degli oggetti, consulta Suddivisione in categorie dello storage utilizzando i tag.

  8. Per aggiungere metadati, seleziona Aggiungi metadati.

    1. In Tipo seleziona Definito dal sistema o Definito dall'utente.

      Per i metadati definiti dal sistema, puoi selezionare le intestazioni HTTP comuni, ad esempio Content-Type e Content-Disposition. Per un elenco di metadati definiti dal sistema e informazioni sulla possibilità di aggiungere il valore, consulta Metadata di oggetti definiti dal sistema. Eventuali metadata che iniziano con il prefisso x-amz-meta- sono considerati come metadata definiti dall'utente. I metadata definiti dall'utente vengono archiviati con l'oggetto e vengono restituiti quando si scarica l'oggetto. Sia le chiavi che i relativi valori devono essere conformi agli standard US-ASCII. I metadata definiti dall'utente possono avere una dimensione massima di 2 KB. Per ulteriori informazioni sui metadati definiti dal sistema e definiti dall'utente, consulta Utilizzo dei metadati degli oggetti.

    2. Per Chiave, seleziona una chiave.

    3. Digitare un valore per la chiave.

  9. Per caricare i tuoi oggetti, scegli Carica.

    Amazon S3 caricherà l'oggetto. Al termine del caricamento, sarà visualizzato un messaggio di successo nella pagina Carica: stato .

  10. Scegliere Exit (Esci).

È possibile utilizzare l'SDK AWS per caricare oggetti in Amazon S3. L'SDK offre librerie wrapper per facilitare il caricamento dei dati. Per informazioni, consulta l'elenco degli SDK supportati.

Di seguito sono riportati degli esempi con alcuni SDK selezionati:

.NET

Il seguente esempio di codice #C crea due oggetti con due richieste PutObjectRequest:

  • La prima richiesta PutObjectRequest salva una stringa di testo come dati dell'oggetto di esempio. Specifica inoltre il nome del bucket e il nome della chiave dell'oggetto.

  • La seconda richiesta PutObjectRequest carica un file specificando il nome file. Questa richiesta specifica anche l'intestazione ContentType e i metadati opzionali dell'oggetto (un titolo).

Per istruzioni su come creare e testare un esempio di utilizzo, consulta Esecuzione degli esempi di codice .NET di Amazon S3.

using Amazon; using Amazon.S3; using Amazon.S3.Model; using System; using System.Threading.Tasks; namespace Amazon.DocSamples.S3 { class UploadObjectTest { private const string bucketName = "*** bucket name ***"; // For simplicity the example creates two objects from the same file. // You specify key names for these objects. private const string keyName1 = "*** key name for first object created ***"; private const string keyName2 = "*** key name for second object created ***"; private const string filePath = @"*** file path ***"; private static readonly RegionEndpoint bucketRegion = RegionEndpoint.EUWest1; private static IAmazonS3 client; public static void Main() { client = new AmazonS3Client(bucketRegion); WritingAnObjectAsync().Wait(); } static async Task WritingAnObjectAsync() { try { // 1. Put object-specify only key name for the new object. var putRequest1 = new PutObjectRequest { BucketName = bucketName, Key = keyName1, ContentBody = "sample text" }; PutObjectResponse response1 = await client.PutObjectAsync(putRequest1); // 2. Put the object-set ContentType and add metadata. var putRequest2 = new PutObjectRequest { BucketName = bucketName, Key = keyName2, FilePath = filePath, ContentType = "text/plain" }; putRequest2.Metadata.Add("x-amz-meta-title", "someTitle"); PutObjectResponse response2 = await client.PutObjectAsync(putRequest2); } catch (AmazonS3Exception e) { Console.WriteLine( "Error encountered ***. Message:'{0}' when writing an object" , e.Message); } catch (Exception e) { Console.WriteLine( "Unknown encountered on server. Message:'{0}' when writing an object" , e.Message); } } } }
Java

L'esempio seguente crea due oggetti. Il primo ha una stringa di testo come dati e il secondo è un file. L'esempio crea il primo oggetto specificando il nome del bucket, la chiave dell'oggetto e i dati di testo direttamente in una chiamata a AmazonS3Client.putObject(). L'esempio crea il secondo oggetto utilizzando una richiesta PutObjectRequest che specifica il nome del bucket, la chiave dell'oggetto e il percorso del file. La richiesta PutObjectRequest specifica anche l'intestazione ContentType e i metadati del titolo.

Per istruzioni su come creare e testare un esempio di utilizzo, consulta Test degli esempi di codice Java di Amazon S3.

import com.amazonaws.AmazonServiceException; import com.amazonaws.SdkClientException; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; import com.amazonaws.services.s3.model.ObjectMetadata; import com.amazonaws.services.s3.model.PutObjectRequest; import java.io.File; import java.io.IOException; public class UploadObject { public static void main(String[] args) throws IOException { Regions clientRegion = Regions.DEFAULT_REGION; String bucketName = "*** Bucket name ***"; String stringObjKeyName = "*** String object key name ***"; String fileObjKeyName = "*** File object key name ***"; String fileName = "*** Path to file to upload ***"; try { //This code expects that you have AWS credentials set up per: // https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-credentials.html AmazonS3 s3Client = AmazonS3ClientBuilder.standard() .withRegion(clientRegion) .build(); // Upload a text string as a new object. s3Client.putObject(bucketName, stringObjKeyName, "Uploaded String Object"); // Upload a file as a new object with ContentType and title specified. PutObjectRequest request = new PutObjectRequest(bucketName, fileObjKeyName, new File(fileName)); ObjectMetadata metadata = new ObjectMetadata(); metadata.setContentType("plain/text"); metadata.addUserMetadata("title", "someTitle"); request.setMetadata(metadata); s3Client.putObject(request); } catch (AmazonServiceException e) { // The call was transmitted successfully, but Amazon S3 couldn't process // it, so it returned an error response. e.printStackTrace(); } catch (SdkClientException e) { // Amazon S3 couldn't be contacted for a response, or the client // couldn't parse the response from Amazon S3. e.printStackTrace(); } } }
JavaScript

Nell'esempio di seguito viene caricato un file esistente in un bucket Amazon S3 in una regione specifica.

// Import required AWS SDK clients and commands for Node.js. import { PutObjectCommand } from "@aws-sdk/client-s3"; import { s3Client } from "./libs/s3Client.js"; // Helper function that creates an Amazon S3 service client module. import {path} from "path"; import {fs} from "fs"; const file = "OBJECT_PATH_AND_NAME"; // Path to and name of object. For example '../myFiles/index.js'. const fileStream = fs.createReadStream(file); // Set the parameters export const uploadParams = { Bucket: "BUCKET_NAME", // Add the required 'Key' parameter using the 'path' module. Key: path.basename(file), // Add the required 'Body' parameter Body: fileStream, }; // Upload file to specified bucket. export const run = async () => { try { const data = await s3Client.send(new PutObjectCommand(uploadParams)); console.log("Success", data); return data; // For unit tests. } catch (err) { console.log("Error", err); } }; run();
PHP

Questo argomento mostra in dettaglio come utilizzare le classi dell'AWS SDK for PHP per caricare un oggetto con una dimensione massima di 5 GB. Per i file di dimensioni maggiori è necessario utilizzare l'API per il caricamento in più parti. Per ulteriori informazioni, consulta Caricamento e copia di oggetti utilizzando il caricamento in più parti.

In questo argomento si presume che siano già state seguite le istruzioni riportate in Utilizzo dell'AWS SDK for PHP ed esecuzione degli esempi in PHP e che AWS SDK for PHP sia stato correttamente installato.

Esempio – Creazione di un oggetto in un bucket Amazon S3 tramite il caricamento dei dati

Nel seguente esempio di codice PHP viene creato un oggetto in un bucket specificato mediante il caricamento dei dati con il metodo putObject(). Per informazioni sull'esecuzione degli esempi di codice PHP in questa guida, consulta Esecuzione di esempi in PHP.

require 'vendor/autoload.php'; use Aws\S3\S3Client; use Aws\S3\Exception\S3Exception; $bucket = '*** Your Bucket Name ***'; $keyname = '*** Your Object Key ***'; $s3 = new S3Client([ 'version' => 'latest', 'region' => 'us-east-1' ]); try { // Upload data. $result = $s3->putObject([ 'Bucket' => $bucket, 'Key' => $keyname, 'Body' => 'Hello, world!', 'ACL' => 'public-read' ]); // Print the URL to the object. echo $result['ObjectURL'] . PHP_EOL; } catch (S3Exception $e) { echo $e->getMessage() . PHP_EOL; }
Ruby

L'AWS SDK for Ruby versione 3 supporta due metodi per il caricamento di un oggetto in Amazon S3. Il primo metodo consiste nell'utilizzare un uploader di file gestito che facilita il caricamento dei file di qualsiasi dimensione dal disco. Per utilizzare tale metodo:

  1. Crea un'istanza della classe Aws::S3::Resource.

  2. Fare riferimento all'oggetto di destinazione in base al nome del bucket e alla chiave. Gli oggetti sono in un bucket e dispongono di chiavi univoche con le quali vengono identificati.

  3. Eseguire la chiamata #upload_file sull'oggetto.

require "aws-sdk-s3" # Wraps Amazon S3 object actions. class ObjectUploadFileWrapper attr_reader :object # @param object [Aws::S3::Object] An existing Amazon S3 object. def initialize(object) @object = object end # Uploads a file to an Amazon S3 object by using a managed uploader. # # @param file_path [String] The path to the file to upload. # @return [Boolean] True when the file is uploaded; otherwise false. def upload_file(file_path) @object.upload_file(file_path) true rescue Aws::Errors::ServiceError => e puts "Couldn't upload file #{file_path} to #{@object.key}. Here's why: #{e.message}" false end end def run_demo bucket_name = "doc-example-bucket" object_key = "my-uploaded-file" file_path = "object_upload_file.rb" wrapper = ObjectUploadFileWrapper.new(Aws::S3::Object.new(bucket_name, object_key)) return unless wrapper.upload_file(file_path) puts "File #{file_path} successfully uploaded to #{bucket_name}:#{object_key}." end run_demo if $PROGRAM_NAME == __FILE__

La seconda soluzione per il caricamento di un oggetto supportata dalla versione 3 di AWS SDK for Ruby utilizza il metodo #put di Aws::S3::Object. Questo metodo è utile se l'oggetto è una stringa o un oggetto I/O che non è un file su disco. Per utilizzare tale metodo:

  1. Crea un'istanza della classe Aws::S3::Resource.

  2. Fare riferimento all'oggetto di destinazione in base al nome del bucket e alla chiave.

  3. Eseguire la chiamata #put passando la stringa o l'oggetto I/O.

require "aws-sdk-s3" # Wraps Amazon S3 object actions. class ObjectPutWrapper attr_reader :object # @param object [Aws::S3::Object] An existing Amazon S3 object. def initialize(object) @object = object end def put_object(source_file_path) File.open(source_file_path, "rb") do |file| @object.put(body: file) end true rescue Aws::Errors::ServiceError => e puts "Couldn't put #{source_file_path} to #{object.key}. Here's why: #{e.message}" false end end def run_demo bucket_name = "doc-example-bucket" object_key = "my-object-key" file_path = "my-local-file.txt" wrapper = ObjectPutWrapper.new(Aws::S3::Object.new(bucket_name, object_key)) success = wrapper.put_object(file_path) return unless success puts "Put file #{file_path} into #{object_key} in #{bucket_name}." end run_demo if $PROGRAM_NAME == __FILE__

Per caricare un oggetto puoi inviare richieste REST. È possibile inviare una richiesta PUT per caricare i dati in una singola operazione. Per ulteriori informazioni, consulta PUT Object.

È possibile inviare una richiesta PUT per caricare un oggetto di un massimo di 5 GB in una singola operazione. Per ulteriori informazioni ed esempi, consulta l'esempio PutObject in Riferimento ai comandi della AWS CLI.