Fazer upload de objetos - Amazon Simple Storage Service

Fazer upload de objetos

Quando você faz upload de um arquivo no Amazon S3, ele é armazenado como um objeto do S3. Os objetos consistem em dados e metadados de arquivo que descrevem o objeto. Você pode ter um número ilimitado de objetos em um bucket. Antes de fazer upload de arquivos em um bucket do Amazon S3, você precisa escrever permissões para o bucket. Para obter mais informações sobre permissões de acesso, consulte Gerenciamento de identidade e acesso para o Amazon S3.

Você pode fazer upload de qualquer tipo de arquivo (imagens, backups, dados, filmes etc.) para um bucket do S3. O tamanho máximo de arquivo que você pode carregar usando o console do Amazon S3 é de 160 GB. Para fazer upload de um arquivo com mais de 160 GB, use a AWS Command Line Interface (AWS CLI), AWS SDKs ou a API REST do Amazon S3.

Se você fizer upload de um objeto com um nome de chave que já existe em um bucket com versionamento habilitado, o Amazon S3 criará outra versão de objeto em vez de substituir o objeto existente. Para obter mais informações sobre versionamento, consulte Uso do console do S3.

Dependendo do tamanho de dados enviados por upload, o Amazon S3 oferece as seguintes opções:

  • Fazer upload de um objeto em uma única operação usando AWS SDKs, a API REST ou a AWS CLI: com uma única operação PUT, você pode fazer upload de um único objeto com até 5 GB.

  • Fazer upload de um único objeto usando o console do Amazon S3: com o console do Amazon S3, é possível fazer upload de um único objeto com até 160 GB de tamanho.

  • Fazer upload de um objeto em partes usando AWS SDKs, a API REST ou a AWS CLI: com a operação de API de upload de várias partes, é possível fazer upload de um único objeto grande, com até 5 TB.

    A operação de API de upload de várias partes foi projetada para melhorar a experiência de upload de objetos maiores. É possível fazer upload de um objeto em partes. O upload dessas partes de objetos pode ser feito independentemente, em qualquer ordem, e em paralelo. Você pode usar um multipart upload de objetos de 5 MB a 5 TB. Para ter mais informações, consulte Carregar e copiar objetos usando multipart upload.

Quando você faz upload de um objeto, ele é automaticamente criptografado usando criptografia do lado do servidor com chaves gerenciadas pelo Amazon S3 (SSE-S3) por padrão. Quando você faz download, o objeto é descriptografado. Para obter mais informações, consulte Definir o comportamento padrão da criptografia para os buckets do Amazon S3 e Proteger dados com criptografia.

Ao fazer upload de um objeto, se quiser usar um tipo diferente de criptografia padrão, você também pode especificar a criptografia do lado do servidor com chaves do AWS Key Management Service (AWS KMS) (SSE-KMS) nas solicitações PUT do S3 ou definir a configuração de criptografia padrão no bucket de destino para usar o SSE-KMS para criptografar os dados. Para obter mais informações sobre SSE-KMS, consulte Especificando criptografia no lado do servidor com o AWS KMS (SSE-KMS). Se quiser usar uma chave do KMS que seja de propriedade de outra conta, você deverá ter permissão para usar a chave. Para obter mais informações sobre permissões entre contas para chaves do KMS, consulte Criar chaves do KMS que outras contas podem usar no Guia do desenvolvedor do AWS Key Management Service.

Se você encontrar um erro de Acesso negado (403 Proibido) no Amazon S3, consulte Solucionar erros de acesso negado (403 proibido) no Amazon S3 para saber mais sobre as causas comuns.

Este procedimento explica como fazer upload de objetos e pastas para um bucket do Amazon S3 usando o console.

Quando você faz upload de um objeto, o nome da chave de objeto é o nome do arquivo e quaisquer prefixos opcionais. No console do Amazon S3, você pode criar pastas para organizar seus objetos. No Amazon S3, as pastas são representadas como prefixos que aparecem no nome da chave de objeto. Se você fizer upload um objeto individual para uma pasta no console do Amazon S3, o nome da pasta será incluído no nome da chave do objeto.

Por exemplo, se você carregar um objeto chamado sample1.jpg para uma pasta chamada backup, o nome da chave será backup/sample1.jpg. Contudo, o objeto é exibido no console como sample1.jpg na pasta backup. Para obter mais informações sobre nomes de chave, consulte Trabalhar com metadados de objeto.

nota

Se você renomear um objeto ou alterar qualquer uma das propriedades no console do Amazon S3, por exemplo Classe de armazenamento, Criptografia ou Metadados, será criado outro objeto para substituir o antigo. Se o versionamento do S3 estiver habilitado, uma nova versão do objeto será criada e o objeto existente se tornará uma versão mais antiga. O perfil que altera a propriedade também se torna o proprietário do novo objeto (ou versão do objeto).

Quando você faz upload de uma pasta, o Amazon S3 faz upload de todos os arquivos e subpastas da pasta especificada em seu bucket. Ele então atribui um nome de chave de objeto que é uma combinação do nome de arquivo carregado com o nome da pasta. Por exemplo, se você fizer upload de uma pasta chamada /images que contém dois arquivos, sample1.jpg e sample2.jpg, o Amazon S3 fará upload dos arquivos e atribuirá a eles os nomes de chave correspondentes, images/sample1.jpg e images/sample2.jpg. Os nomes de chave incluem o nome da pasta como um prefixo. O console do Amazon S3 exibe somente a parte do nome de chave que vem depois da última /. Por exemplo, em uma pasta images, os objetos images/sample1.jpg e images/sample2.jpg são exibidos como sample1.jpg e sample2.jpg.

Para fazer upload de pastas e arquivos para um bucket do S3

  1. Faça login no AWS Management Console e abra o console do Amazon S3 em https://console.aws.amazon.com/s3/.

  2. No painel de navegação à esquerda, escolha Buckets.

  3. Na lista Buckets, escolha o nome do bucket no qual você deseja carregar suas pastas ou arquivos.

  4. Escolha Upload (Fazer upload).

  5. Na janela Upload (Fazer upload), siga um destes procedimentos:

    • Arraste e solte arquivos e pastas para a janela Upload (Fazer upload) .

    • Escolha Adicionar arquivo ou Adicionar pasta, escolha arquivos ou pastas para fazer upload e depois escolha Abrir.

  6. Para habilitar o versionamento, em Destination (Destino), escolha Enable Bucket Versioning (Ativar versionamento de bucket).

  7. Para fazer upload dos arquivos e pastas listados sem configurar opções de upload adicionais, na parte inferior da página, escolha Upload (Fazer upload).

    O Amazon S3 faz o upload de seus objetos e pastas. Quando o upload for concluído, você verá uma mensagem de sucesso na página Upload: status.

Para configurar propriedades de objeto adicionais

  1. Para alterar as permissões da lista de controle de acesso, escolha Permissions (Permissões).

  2. Em Access control list (ACL) (Lista de controle de acesso (ACL)), edite as permissões.

    Para informações sobre permissões de acesso a objeto, consulte Usar o console do S3 para definir permissões de ACL para um objeto. Você pode conceder acesso de leitura aos seus objetos ao público (todos no mundo), para todos os arquivos que você está carregando. No entanto, recomendamos não alterar a configuração padrão para acesso de leitura público. Conceder acesso público de leitura é aplicável a um pequeno subconjunto de casos de uso, como quando buckets são usados para sites. Você sempre pode alterar as permissões de objeto depois de carregar o objeto.

  3. Para configurar outras propriedades, escolha Properties (Propriedades).

  4. Na seção Classe de armazenamento escolha a classe de armazenamento para os arquivos que você está carregando.

    Para obter mais informações sobre classes de armazenamento, consulte Uso de classes de armazenamento do Amazon S3.

  5. Para atualizar as configurações de criptografia para seus objetos, em Server-side encryption settings (Configurações de criptografia do lado do servidor), faça o seguinte.

    1. Escolha Specify an encryption key (Especificar uma chave de criptografia).

    2. Em Configurações de criptografia, escolha Usar configurações de bucket para criptografia padrão ou Substituir configurações de bucket para criptografia padrão.

    3. Se você escolher Substituir configurações do bucket para criptografia padrão, deverá definir as configurações de criptografia a seguir.

      • Para criptografar os arquivos carregados usando chaves gerenciadas pelo Amazon S3, escolha Chave gerenciada pelo Amazon S3 (SSE-S3).

        Para ter mais informações, consulte Usar a criptografia do lado do servidor com chaves gerenciadas pelo Amazon S3 (SSE-S3).

      • Para criptografar os arquivos carregados usando chaves armazenadas no AWS Key Management Service (AWS KMS), selecione Chave do AWS Key Management Service (SSE-KMS). Depois, escolha uma das seguintes opções para a chave do AWS KMS:

        • Para escolher entre uma lista de chaves do KMS disponíveis, selecione Escolher de sua AWS KMS keys e escolha a chave do KMS na lista de chaves disponíveis.

          As chaves Chave gerenciada pela AWS (aws/s3) e as chaves gerenciadas pelo cliente são exibidas nessa lista. Para ter mais informações sobre chaves gerenciadas pelo cliente, consulte Chaves de clientes e chaves da AWS no Guia do desenvolvedor do AWS Key Management Service.

        • Para inserir o ARN da chave do KMS, selecione Inserir ARN da AWS KMS key e insira o ARN da chave do KMS no campo exibido.

        • Para criar uma chave gerenciada pelo cliente no console do AWS KMS, selecione Criar uma chave do KMS.

          Para ter mais informações sobre como criar uma AWS KMS key, consulte Criação de chaves no Guia do desenvolvedor do AWS Key Management Service.

        Importante

        Você só pode usar chaves do KMS disponíveis na mesma Região da AWS que o bucket. O console do Amazon S3 lista somente as primeiras 100 chaves do KMS na mesma região que o bucket. Para usar uma chave do KMS que não esteja listada, você deve inserir o ARN da chave do KMS. Se quiser usar uma chave do KMS que seja de propriedade de outra conta, primeiro você deverá ter permissão para usar a chave e, depois, inserir o ARN da chave do KMS.

        O Amazon S3 só é compatível com chaves do KMS de criptografia simétrica, e não com chaves assimétricas do KMS. Para ter mais informações, consulte Identificar chaves do KMS simétricas e assimétricas no Guia do desenvolvedor do AWS Key Management Service.

  6. Para usar somas de verificação adicionais, escolha On (Ativar). Em seguida, em Checksum function (Função de soma de verificação), escolha a função que você gostaria de usar. O Amazon S3 calcula e armazena o valor da soma de verificação depois de receber o objeto inteiro. Você pode usar a caixa Precalculated value (Valor pré-calculado) para fornecer esse valor. Se fizer isso, o Amazon S3 vai comparar o valor que você forneceu com o valor calculado. Se os dois valores não corresponderem, o Amazon S3 gerará um erro.

    As somas de verificação adicionais permitem que você especifique o algoritmo de soma de verificação que gostaria de usar para verificar seus dados. Para obter mais informações sobre somas de verificação adicionais, consulte Verificar a integridade do objeto.

  7. Para adicionar tags a todos os objetos que você está carregando, escolha Add tag (Adicionar tag). Insira um nome de tag no campo Chave. Insira um valor para a tag.

    A marcação de objetos é uma forma de categorizar o armazenamento. Cada tag é um par de chave-valor. Os valores de chave e tag diferenciam maiúsculas de minúsculas. É possível ter até dez tags por objeto. Uma chave de tag pode ter até 128 caracteres Unicode e os valores de tag podem ter até 255 caracteres Unicode. Para obter mais informações sobre tags de objeto, consulte Categorizando seu armazenamento usando tags.

  8. Para adicionar metadados, escolha Add metadata (Adicionar metadados).

    1. Em Type (Tipo), escolha System defined (Definido pelo sistema) ou User defined (Definido pelo usuário).

      Para metadados definidos pelo sistema, você pode selecionar cabeçalhos HTTP comuns, como Content-Type e Content-Disposition. Para obter uma lista de metadados definidos pelo sistema e informações sobre a possibilidade de adicionar o valor, consulte Metadados do objeto definidos pelo sistema. Todos os metadados que começam com o prefixo x-amz-meta- são tratados como metadados definidos pelo usuário. Os metadados definidos pelo usuário são armazenados com o objeto e retornados quando você baixa o objeto. As chaves e seus valores devem estar em conformidade com os padrões US-ASCII. Metadados definidos pelo usuário podem ter até 2 KB. Para obter mais informações sobre metadados definidos pelo sistema e pelo usuário, consulte Trabalhar com metadados de objeto.

    2. Para Key (Chave), escolha uma chave.

    3. Digite um valor para a chave.

  9. Para carregar seus objetos, escolha Upload (Fazer upload).

    O Amazon S3 faz o upload do objeto. Quando o upload for concluído, você pode ver uma mensagem de sucesso na página de Upload: status.

  10. Selecione Exit (Sair).

Você pode usar os AWS SDKs para fazer upload de objetos no Amazon S3. Os SDKs fornecem bibliotecas wrapper para você para fazer upload de dados com facilidade. Para obter informações, consulte a Lista de SDKs compatíveis.

Aqui estão alguns exemplos com alguns SDKs selecionados:

.NET

O exemplo de código C# a seguir cria dois objetos com as duas solicitações PutObjectRequest:

  • A primeira solicitação PutObjectRequest salva uma sequência de texto como exemplo de dados do objeto. Ela também especifica os nomes do bucket e da chave de objeto.

  • A segunda solicitação PutObjectRequest faz upload de um arquivo especificando o nome do arquivo. Essa solicitação também especifica o cabeçalho ContentType e os metadados opcionais de objeto (título).

Para obter instruções sobre como criar e testar um exemplo funcional, consulte Executar os exemplos de código do Amazon S3 .NET.

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

O exemplo a seguir cria dois objetos. O primeiro objeto tem uma sequência de texto como dados, e o segundo objeto é um arquivo. O exemplo cria o primeiro objeto especificando o nome de bucket, a chave de objeto, e os dados de texto diretamente em uma chamada para AmazonS3Client.putObject(). O exemplo cria um segundo objeto usando um PutObjectRequest que especifica o nome de bucket, a chave de objeto, e o caminho do arquivo. O PutObjectRequest também especifica o cabeçalho de ContentType e os metadados do título.

Para obter instruções sobre criar e testar um exemplo funcional, consulte Testar exemplos de código Java no 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

O exemplo a seguir carrega um arquivo existente para um bucket do Amazon S3 em uma região 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

Este exemplo orienta você quanto ao uso de classes do AWS SDK for PHP para fazer upload de um objeto de até 5 GB. Para arquivos maiores, você deve usar a operação de API de upload de várias partes. Para ter mais informações, consulte Carregar e copiar objetos usando multipart upload.

Este exemplo considera que você já está seguindo as instruções para Usar o AWS SDK for PHP e executar exemplos do PHP e tem o AWS SDK for PHP devidamente instalado.

exemplo Criar um objeto em um bucket do Amazon S3 fazendo upload dos dados

O exemplo PHP a seguir cria um objeto em um bucket especificado pelo upload de dados usando o método putObject(). Para obter informações sobre a execução dos exemplos de PHP neste guia, consulte Executar exemplos do 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

O AWS SDK for Ruby versão 3 oferece duas maneiras de fazer upload de um objeto para o Amazon S3. O primeiro usa um upload gerenciado de arquivo, que facilita o upload de arquivos de qualquer tamanho para disco. Usar o método de upload gerenciado de arquivo:

  1. Crie uma instância da classe Aws::S3::Resource.

  2. Faça referência ao objeto de destino pelo nome e chave do bucket. Os objetos residem em um bucket e têm chaves exclusivas que identificam cada objeto.

  3. Chame #upload_file no 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__

A segunda forma que o AWS SDK for Ruby – Versão 3 pode fazer upload de um objeto usa o método #put do Aws::S3::Object. Isso é útil se o objeto for uma string ou um objeto de E/S que não seja um arquivo em disco. Para usar este método:

  1. Crie uma instância da classe Aws::S3::Resource.

  2. Faça referência ao objeto de destino pelo nome e chave do bucket.

  3. Chame#put, passando a sequência ou objeto de E/S.

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__

Você pode enviar solicitações REST para fazer upload de um objeto. Você pode enviar uma solicitação PUT para carregar dados em uma única operação. Para obter mais informações, consulte Objeto PUT.

Você pode enviar uma solicitação PUT para fazer upload de um objeto de até 5 GB em uma única operação. Para obter mais informações, consulte o exemplo de PutObject na Referência de comandos da AWS CLI.