Carga de objetos

Al cargar un archivo en Amazon S3, se guarda como un objeto de S3. Los objetos constan de los datos y metadatos del archivo que describen el objeto. Puede haber un número ilimitado de objetos en un bucket. Para poder cargar archivos en un bucket de Amazon S3, debe escribir permisos para el bucket. Para obtener más información acerca de los permisos de acceso, consulte Identity and Access Management en Amazon S3.

Puede cargar cualquier tipo de archivo, como imágenes, copias de seguridad, datos, películas, etc., en un bucket de S3. El tamaño máximo de un archivo que puede cargar con la consola de Amazon S3 es de 160 GB. Para cargar un archivo que sobrepase los 160 GB de tamaño, utilice la AWS Command Line Interface (AWS CLI), el SDK de AWS o la API de REST de Amazon S3.

Si carga un objeto con un nombre de clave que ya existe en un bucket con el control de versiones activado, Amazon S3 crea otra versión del objeto en vez de reemplazar el objeto existente. Para obtener más información sobre el control de versiones, consulte Uso de la consola de S3.

En función del tamaño de los datos que cargue, Amazon S3 ofrece las siguientes opciones:

• Cargar un objeto en una única operación mediante los SDK de AWS, la API de REST o la AWS CLI: con una única operación PUT, se puede cargar un único objeto de hasta 5 GB.

• Cargar un solo objeto mediante la consola de Amazon S3: con la consola de Amazon S3, se puede cargar un único objeto de hasta 160 GB.

• Cargar un objeto en partes mediante los SDK de AWS, la API de REST o la AWS CLI: con la API de carga multiparte, se puede cargar un solo objeto grande, de hasta 5 TB.

  La operación de la API de carga multiparte está diseñada para mejorar la experiencia de carga para objetos más grandes. Puede cargar un objeto en partes. Estas partes de objetos se pueden cargar independientemente, en cualquier orden y en paralelo. Puede usar la carga multiparte para objetos que ocupen de 5 MB a 5 TB. Para obtener más información, consulte Carga y copia de objetos con la carga multiparte.

Cuando se carga un objeto, el objeto se cifra automáticamente mediante cifrado del lado del servidor con claves administradas de Amazon S3 (SSE-S3) de forma predeterminada. Al descargarlo, el objeto se descifra. Para obtener más información, consulte Establecer el comportamiento del cifrado predeterminado del lado del servidor para los buckets de Amazon S3 y Protección de los datos mediante el cifrado.

Al cargar un objeto, si quiere utilizar un tipo de cifrado predeterminado diferente, también puede especificar el cifrado del lado del servidor con claves de AWS Key Management Service (AWS KMS) (SSE-KMS) en sus solicitudes PUT de S3 o definir la configuración de cifrado predeterminada en el bucket de destino para usar SSE-KMS para cifrar los datos. Para obtener más información sobre SSE-KMS, consulte Especificación del cifrado del lado del servidor con AWS KMS (SSE-KMS). Si desea utilizar una clave de KMS propiedad de una cuenta diferente, primero debe tener permiso para utilizar la clave. Para obtener más información sobre los permisos entre cuentas para las claves de KMS, consulte Crear claves de KMS que otras cuentas puedan utilizar en la Guía para desarrolladores de AWS Key Management Service.

Si aparece un error Access Denied (403 Forbidden) en Amazon S3, consulte Solucionar errores de acceso denegado (403 Prohibido) en Amazon S3 para obtener más información sobre las causas comunes de dicho error.

Uso de la consola de S3

Este procedimiento explica cómo cargar objetos y carpetas a un bucket de Amazon S3 mediante la consola.

Cuando carga un objeto, el nombre de la clave de objeto es el nombre del archivo y los prefijos opcionales. En la consola de Amazon S3, puede crear carpetas para organizar sus objetos. En Amazon S3, las carpetas se representan como prefijos que aparecen en el nombre de la clave de objeto. Si carga un objeto individual en una carpeta de la consola de Amazon S3, el nombre de la carpeta se incluirá en el nombre de la clave de objeto.

Por ejemplo, si carga un objeto denominado sample1.jpg en una carpeta denominada backup, el nombre de la clave es backup/sample1.jpg. Sin embargo, el objeto se mostrará en la consola como sample1.jpg la carpeta backup. Para obtener más información sobre nombres de clave, consulte Trabajar con metadatos de objeto.

nota

Si cambia el nombre de un objeto o cambia cualquiera de las propiedades de la consola de Amazon S3 (por ejemplo, la clase de almacenamiento, el cifrado o los metadatos), se crea un nuevo objeto para reemplazar el anterior. Si el control de versiones de S3 está activado, se crea una nueva versión del objeto y el objeto existente se convierte en una versión anterior. El rol que cambia la propiedad también se convierte en el propietario del nuevo objeto o (versión del objeto).

Cuando carga una carpeta, Amazon S3 carga todos los archivos y subcarpetas de la carpeta especificada en su bucket. Luego asigna un nombre de clave de objeto, que es una combinación del nombre del archivo cargado y el nombre de la carpeta. Por ejemplo, si carga una carpeta denominada /images que contiene dos archivos, sample1.jpg y sample2.jpg, Amazon S3 carga los archivos y les asigna los nombres de clave correspondientes, images/sample1.jpg e images/sample2.jpg. Los nombres de clave incluyen el nombre de la carpeta como un prefijo. La consola de Amazon S3 muestra solo la parte del nombre de clave siguiente a la última /. Por ejemplo, dentro de una carpeta images, los objetos images/sample1.jpg y images/sample2.jpg se muestran como sample1.jpg y sample2.jpg.

Para cargar carpetas y archivos a un bucket de S3

1. Inicie sesión AWS Management Console Management Console y abra la consola de Amazon S3 en https://console.aws.amazon.com/s3/.

2. En el panel de navegación izquierdo, elija Instancias.

3. En la lista Buckets (Buckets), elija el nombre del bucket en el que desea cargar sus carpetas o archivos.

4. Seleccione Upload.

5. En la ventana Upload (Cargar), realice una de las siguientes acciones:

   • Arrastre y suelte archivos y carpetas en la ventana Upload (Cargar).

   • Elija Agregar archivo o Agregar carpeta, elija los archivos o carpetas que desee cargar y Abrir.

6. Para habilitar el control de versiones, en Destination (Destino), seleccione Enable Bucket Versioning (Activar control de versiones de bucket).

7. Para cargar los archivos y carpetas enumerados sin configurar opciones de carga adicionales, en la parte inferior de la página, seleccione Upload (Cargar).

   Amazon S3 carga sus objetos y carpetas. Cuando finalice la carga, puede ver un mensaje de éxito en la página Cargar: estado.

Para configurar propiedades de objeto adicionales

1. Para cambiar los permisos de la lista de control de acceso, elija Permissions (Permisos).

2. En Access control list (ACL) (Lista de control de acceso [ACL]), edite los permisos.

   Para obtener información acerca de los permisos de acceso a objetos, consulte Uso de la consola S3 para establecer permisos de ACL para un objeto. Puede conceder acceso de lectura a los objetos al público (a todo el mundo) para todos los archivos que esté cargando. Sin embargo, recomendamos no cambiar la configuración predeterminada para el acceso de lectura pública. Otorgar acceso de lectura público es aplicable a un pequeño conjunto de casos de uso, por ejemplo cuando los buckets se utilizan para sitios web. Siempre puede cambiar los permisos del objeto después de cargarlo.

3. Para configurar otras propiedades, elija Properties (Propiedades).

4. En la sección Clase de almacenamiento, elija la clase de almacenamiento para los archivos que esté cargando.

   Para obtener más información acerca de las clases de almacenamiento, consulte Uso de las clases de almacenamiento de Amazon S3.

5. Para actualizar la configuración de cifrado de los objetos, en Server-side encryption settings (Configuración de cifrado del lado del servidor), haga lo siguiente.

   1. Elija Specify an encryption key (Especificar una clave de cifrado).

   2. En Configuración del cifrado, elija Usar la configuración del bucket para el cifrado predeterminado o Anular la configuración del bucket para el cifrado predeterminado.

   3. Si elige Anular la configuración del bucket para el cifrado predeterminado, debe configurar los siguientes ajustes de cifrado.

      • Para cifrar los archivos cargados con claves que administra Amazon S3, seleccione Clave administrada de Amazon S3 (SSE-S3).

        Para obtener más información, consulte Uso del cifrado del servidor con claves administradas por Amazon S3 (SSE-S3).

      • Si desea cifrar los archivos cargados mediante claves almacenadas en AWS Key Management Service (AWS KMS), elija la Clave de AWS Key Management Service (SSE-KMS). A continuación, elija una de las siguientes opciones para la clave de AWS KMS:

        • Para seleccionar en una lista de claves de KMS disponibles, marque Elija entre sus claves de AWS KMS keys y seleccione su clave de KMS en la lista de claves disponibles.

          En esta lista aparecen tanto la Clave administrada de AWS (aws/s3) como las claves administradas por el cliente. Para obtener más información acerca de las claves administradas por el cliente, consulte Claves de cliente y claves de AWS en la Guía para desarrolladores de AWS Key Management Service.

        • Para introducir el ARN de la clave de KMS, elija Introducir el ARN de la clave de AWS KMS key e introduzca el ARN de la clave de KMS en el campo que aparece.

        • Para crear una nueva clave administrada por el cliente en la consola de AWS KMS, elija Crear una clave de KMS.

          Para obtener más información acerca de cómo crear una AWS KMS key, consulte Creación de claves en la AWS Key Management Service Guía para desarrolladores.

        importante

        Solo puede utilizar las claves de KMS que estén disponibles en la misma Región de AWS del bucket. La consola de Amazon S3 solo muestra las primeras 100 claves de KMS de la misma región del bucket. Para utilizar una clave de KMS que no aparezca en la lista, debe introducir el ARN de la clave de KMS. Si desea utilizar una clave de KMS propiedad de una cuenta de diferente, primero debe tener permiso para utilizar la clave y, después, debe introducir el ARN de la clave de KMS.

        Amazon S3 admite solo claves KMS de cifrado simétricas y no claves KMS asimétricas. Para obtener más información, consulte Identificación de claves de KMS simétricas y asimétricas en la Guía para desarrolladores de AWS Key Management Service.

6. Para utilizar sumas de comprobación adicionales, elija On (Activado). A continuación, en Checksum function (Función de suma de comprobación), elija la función que desearía utilizar. Amazon S3 calcula y almacena el valor de la suma de comprobación después de recibir todo el objeto. Puede utilizar el recuadro Precalculated value (Valor precalculado) para proporcionar un valor precalculado. Si lo hace, Amazon S3 compara el valor que proporcionó con el valor que calcula. Si los valores no coinciden, Amazon S3 genera un error.

   Las sumas de comprobación adicionales le permiten especificar el algoritmo de suma de comprobación que desea utilizar para verificar los datos. Para obtener más información sobre sumas de comprobación adicionales, consulte Comprobación de la integridad de objetos.

7. Para agregar etiquetas a todos los objetos que va a cargar, elija Add tag (Agregar etiqueta). Escriba un nombre de etiqueta en el campo Clave. Ingrese un valor para la etiqueta.

   El etiquetado de objetos le permite categorizar el almacenamiento. Cada etiqueta es un par clave-valor. Los valores de clave y de etiqueta distinguen entre mayúsculas y minúsculas. Puede tener hasta 10 etiquetas por cada objeto. Una clave de etiqueta puede tener una longitud de hasta 128 caracteres Unicode y los valores de etiqueta pueden tener una longitud de hasta 255 caracteres Unicode. Para obtener más información acerca de las etiquetas de objeto, consulte Categorización del almacenamiento mediante etiquetas.

8. Para agregar metadatos, elija Add metadata (Agregar metadatos).

   1. En Type (Tipo), elija System defined (Definido por sistema) o User defined (Definido por el usuario).

      Para los metadatos definidos por el sistema, puede seleccionar encabezados HTTP comunes, como Content-Type (Tipo de contenido) y Content-Disposition (Disposición de contenido). Para obtener una lista de metadatos definidos por el sistema e información sobre si puede agregar el valor, consulte Metadatos de objetos definidos por el sistema. Cualquier metadato que comience con el prefijo x-amz-meta- se trata como metadato definido por el usuario. Los metadatos definidos por el usuario se almacenan con el objeto y se devuelven cuando lo descarga. Tanto las claves como sus valores deben cumplir los estándares ASCII de EE. UU. Los metadatos definidos por el usuario pueden tener un tamaño de hasta 2 KB. Para obtener más información acerca de los metadatos definidos por el sistema y por el usuario, consulte Trabajar con metadatos de objeto.

   2. Para Key (Clave), elija una clave.

   3. Escriba un valor para la clave.

9. Para cargar los objetos, selecciona Upload (Cargar).

   Amazon S3 carga su objeto. Cuando finalice la carga, puede ver un mensaje de éxito en la página Upload: status (Cargar: estado).

10. Seleccione Exit (Salir).

Uso de los AWS SDK

Puede utilizar los SDK de AWS para cargar objetos en Amazon S3. Los SDK proporcionan bibliotecas de encapsulamiento para que pueda cargar datos fácilmente. Para obtener información, consulte la Lista de SDK admitidos.

Aquí se muestran algunos ejemplos con algunos SDK seleccionados:

.NET

El siguiente código de C# crea dos objetos con dos solicitudes de PutObjectRequest:

• La primera solicitud de PutObjectRequest guarda una cadena de texto como muestra de datos del objeto. También especifica los nombres del bucket y de la clave del objeto.

• La segunda solicitud de PutObjectRequest carga un archivo especificando el nombre del archivo. Esto requiere también especificar el encabezado de ContentType y los metadatos opcionales del objeto (un título).

Para obtener instrucciones acerca de cómo crear y probar una muestra funcional, consulte Ejecución de ejemplos de código .NET de 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

En el siguiente ejemplo se crean dos objetos. El primer objeto tiene una cadena de texto como datos y el segundo objeto es un archivo. El ejemplo crea el primer objeto especificando el nombre de bucket, la clave de objeto y los datos de texto directamente en una llamada a AmazonS3Client.putObject(). El ejemplo crea el segundo objeto utilizando un PutObjectRequest que especifica el nombre de bucket, la clave de objeto y la ruta del archivo. El PutObjectRequest también especifica el encabezado de ContentType y los metadatos del título.

Para obtener instrucciones sobre la creación y comprobación de una muestra funcional, consulte Prueba de los ejemplos de código de Java de 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

En el ejemplo siguiente se carga un archivo existente en un bucket de Amazon S3 en una región específica.

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

En este tema se detalla el proceso de uso de las clases de AWS SDK for PHP para cargar un objeto de hasta 5 GB de tamaño. Para archivos más grandes, debe utilizar la operación de la API de carga multiparte. Para obtener más información, consulte Carga y copia de objetos con la carga multiparte.

En este ejemplo, se da por sentado que está familiarizado con las instrucciones para Uso del AWS SDK for PHP y ejecución de ejemplos de PHP y ha instalado AWS SDK for PHP adecuadamente.

ejemplo — Creación de un objeto en un bucket de Amazon S3 mediante la carga de datos

En el siguiente ejemplo en PHP se crea un objeto en un bucket específico cargando datos con el método putObject(). Para obtener información acerca de la ejecución de ejemplos de PHP en esta guía, consulte Ejecución de ejemplos de 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

AWS SDK for Ruby, versión 3, tiene dos maneras de cargar un objeto en Amazon S3. La primera usa un cargador de archivos administrado, que facilita la carga de archivos de cualquier tamaño desde el disco. Para utilizar el método del cargador de archivos administrado:

1. Cree una instancia de la clase Aws::S3::Resource.

2. Haga referencia al objeto objetivo con el nombre del bucket y la clave. Los objetos residen en un bucket y tienen claves únicas que identifica cada objeto.

3. Llame a #upload_file en el objeto.

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__

La segunda manera en la que la versión 3 de AWS SDK for Ruby puede cargar un objeto es usar el método #put de Aws::S3::Object. Esto resulta útil si el objeto es una cadena o un objeto I/O que no sea un archivo en el disco. Para usar este método:

1. Cree una instancia de la clase Aws::S3::Resource.

2. Haga referencia al objeto objetivo con el nombre del bucket y la clave.

3. Llame a #put, pasando la cadena o el objeto 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__

Uso de la API de REST

Puede enviar solicitudes REST para cargar un objeto. Puede enviar una solicitud PUT para cargar datos en una única operación. Para obtener más información, consulte PUT Object.

Mediante AWS CLI

Envíe una solicitud PUT para cargar un objeto de hasta 5 GB en una única operación. Para obtener más información, consulte el ejemplo de PutObject en la referencia de comandos de AWS CLI.