Caricamento degli oggetti

Quando un file viene caricato in Amazon S3, viene archiviato come oggetto 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 per 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 di Amazon S3 è 160 GB. Per caricare un file di dimensioni superiori a 160 GB, usa AWS Command Line Interface (AWS CLI), gli AWS SDK o l'API REST 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 con un'unica operazione utilizzando gli AWS SDK, l'API REST oppure AWS CLI — Con una singola PUT operazione, puoi caricare un singolo oggetto di dimensioni fino a 5 GB.

• Carica 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 più parti utilizzando gli AWS SDK, l'API REST oppure AWS CLI: utilizzando l'operazione API di caricamento multiparte, puoi caricare un singolo oggetto di grandi dimensioni, di dimensioni fino a 5 TB.

  L'operazione 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.

Al momento del caricamento, l'oggetto viene crittografato automaticamente per impostazione predefinita utilizzando la crittografia lato server con chiavi gestite da Amazon S3 (SSE-S3). Quando lo scarichi, l'oggetto viene decrittato. Per ulteriori informazioni, consulta Impostazione del comportamento predefinito della crittografia lato server per i bucket Amazon S3 e Protezione dei dati con la crittografia.

Quando carichi un oggetto, se desideri utilizzare un diverso tipo di crittografia predefinita, puoi anche specificare la crittografia lato server con le chiavi AWS Key Management Service (AWS KMS) (SSE-KMS) nelle tue richieste PUT S3 o impostare la configurazione di crittografia predefinita nel bucket di destinazione per utilizzare SSE-KMS per crittografare i dati. Per ulteriori informazioni su SSE-KMS, consulta Specifica della crittografia lato server con AWS KMS (SSE-KMS). Se desideri utilizzare una chiave KMS di proprietà di un account diverso, devi avere l'autorizzazione necessaria per l'uso della chiave. Per ulteriori informazioni sulle autorizzazioni tra account per le chiavi KMS, vedi Creazione di chiavi KMS utilizzabili da altri account nella Guida per gli sviluppatori di AWS Key Management Service .

Se riscontri un errore di accesso negato (403 proibito) in Amazon S3, Risoluzione dei problemi relativi agli errori di accesso negato (403 Accesso negato) in Amazon S3 consulta la pagina per saperne di più sulle cause più comuni.

Utilizzo della console S3

Questa procedura spiega come caricare oggetti e cartelle in un bucket Amazon 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 di 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 di 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 di Amazon S3, ad esempio Classe di storage, Crittografia o Metadati, viene creato un nuovo oggetto per sostituire quello precedente. Se è abilitata la funzione Controllo delle 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 di Amazon S3 visualizza solo la parte del nome della chiave che segue l'ultimo simbolo /. Ad esempio, in una cartella di images, 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 AWS Management Console e apri la console Amazon S3 all'indirizzo https://console.aws.amazon.com/s3/.

2. Nel pannello di navigazione a sinistra, scegli Buckets (Bucket).

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

4. Scegli Carica.

5. Nella finestra Carica completa una delle seguenti operazioni:

   • Trascina e rilascia file e cartelle nella finestra Carica .

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

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

7. 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 viene visualizzato un messaggio di esito positivo 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. In Impostazioni di crittografia, scegli Utilizza le impostazioni del bucket per la crittografia predefinita o Ignora le impostazioni del bucket per la crittografia predefinita.

   3. Se scegli Ignora le impostazioni del bucket per la crittografia predefinita, dovrai configurare le seguenti impostazioni di crittografia.

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

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

      • Per crittografare i file caricati utilizzando le chiavi memorizzate in AWS Key Management Service (AWS KMS), scegli AWS Key Management Service key (SSE-KMS). Quindi scegli una delle seguenti opzioni per Chiave AWS KMS :

        • Per scegliere da un elenco di chiavi KMS disponibili, seleziona Scegli tra le chiavi AWS KMS keys, quindi scegli la chiave KMS dall'elenco delle chiavi disponibili.

          In questo elenco vengono visualizzate sia la chiave Chiave gestita da AWS (aws/s3) che quella gestita dal cliente. Per ulteriori informazioni sulle chiavi gestite dal cliente, consulta Chiavi gestite dal cliente e chiavi AWS nella Guida per gli sviluppatori di AWS Key Management Service .

        • Per inserire l'ARN della chiave KMS, scegli Inserisci AWS KMS key ARN, quindi inserisci l'ARN della chiave KMS nel campo visualizzato.

        • Per creare una nuova chiave gestita dal cliente nella AWS KMS console, scegli Crea una chiave KMS.

          Per ulteriori informazioni sulla creazione di una AWS KMS key, consulta Creating keys nella AWS Key Management Service Developer Guide.

        Importante

        Puoi utilizzare solo le chiavi KMS disponibili nello Regione AWS stesso bucket. La console Amazon S3 elenca solo le prime 100 chiavi KMS nella stessa regione del bucket. Per utilizzare una chiave KMS non elencata, devi inserire l'ARN della chiave KMS. Se desideri utilizzare una chiave KMS di proprietà di un account diverso, è necessario innanzitutto disporre dell'autorizzazione necessaria per l'uso della chiave e quindi inserire l'ARN della chiave KMS.

        Amazon S3 supporta solo chiavi KMS di crittografia simmetriche e non chiavi KMS asimmetriche. Per ulteriori informazioni, consulta Identificazione delle chiavi KMS simmetriche e asimmetriche nella Guida per gli sviluppatori di AWS Key Management Service .

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). Immetti un nome di tag nel campo Chiave. Immetti 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).

Utilizzo degli SDK AWS

Puoi utilizzare gli AWS SDK per caricare oggetti in Amazon S3. Gli SDK offrono le 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 { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";

const client = new S3Client({});

export const main = async () => {
  const command = new PutObjectCommand({
    Bucket: "test-bucket",
    Key: "hello-s3.txt",
    Body: "Hello S3!",
  });

  try {
    const response = await client.send(command);
    console.log(response);
  } catch (err) {
    console.error(err);
  }
};

PHP

Questo esempio ti guida nell'utilizzo delle classi di AWS SDK for PHP per caricare un oggetto di dimensioni fino a 5 GB. Per i file di dimensioni maggiori è necessario utilizzare l'operazione API per il caricamento in più parti. Per ulteriori informazioni, consulta Caricamento e copia di oggetti utilizzando il caricamento in più parti.

In questo esempio si presuppone che le istruzioni per Utilizzo AWS SDK for PHP ed esecuzione degli esempi PHP siano già in fase di esecuzione e che la AWS SDK for PHP sia stata correttamente installata.

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\Exception\S3Exception;
use Aws\S3\S3Client;

$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

La AWS SDK for Ruby - Versione 3 offre due modi per caricare un oggetto su 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

# Example usage:
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__

Il secondo modo in cui AWS SDK for Ruby - Version 3 può caricare un oggetto utilizza il #put metodo 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

# Example usage:
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__

Utilizzo di REST API

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.

Utilizzando il AWS CLI

È 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 .