객체 업로드 - Amazon Simple Storage Service

객체 업로드

Amazon S3에 파일을 업로드하면 이 파일은 S3 객체로 저장됩니다. 객체는 파일 데이터 및 그 객체를 설명하는 메타데이터로 구성됩니다. 또한 버킷에 저장할 수 있는 객체 수에는 제한이 없습니다. Amazon S3 버킷에 파일을 업로드하려면 해당 버킷에 대한 쓰기 권한이 있어야 합니다. 액세스 권한에 대한 자세한 내용은 Amazon S3의 Identity and Access Management을 참조하세요.

이미지, 백업, 데이터, 동영상 등 모든 유형의 파일을 S3 버킷에 업로드할 수 있습니다. Amazon S3 콘솔을 사용하여 업로드할 수 있는 파일의 최대 크기는 160GB입니다. 160GB가 넘는 파일을 업로드하려면 AWS CLI, AWS SDK 또는 Amazon S3 REST API를 사용하세요.

버전 관리를 사용하는 버킷에 이미 키 이름이 있는 객체를 업로드하면 Amazon S3는 기존 객체를 대체하는 대신 객체의 다른 버전을 만듭니다. 버전 관리에 대한 자세한 내용은 S3 콘솔 사용 섹션을 참조하세요.

Amazon S3는 업로드하는 데이터의 크기에 따라 다음과 같은 옵션을 제공합니다.

  • AWS SDK, REST API 또는 AWS CLI를 사용하여 단일 작업으로 객체 업로드 - 단일 PUT 작업으로 최대 5GB 크기의 단일 객체를 업로드할 수 있습니다.

  • Amazon S3 콘솔을 사용하여 단일 객체 업로드 —Amazon S3 콘솔을 사용하면 최대 160GB 크기의 단일 객체를 업로드할 수 있습니다.

  • AWS SDK, REST API 또는 AWS CLI를 사용하여 부분으로 나누어 객체 업로드 - 멀티파트 업로드 API를 사용하여 최대 5TB 크기의 단일 대형 객체를 업로드할 수 있습니다.

    멀티파트 업로드 API는 대용량 객체의 업로드 경험을 개선하기 위해 디자인되었습니다. 객체를 파트별로 업로드할 수 있습니다. 이러한 객체 파트는 임의의 순서로 독립적으로, 그리고 병렬적으로 업로드할 수 있습니다. 크기가 5MB에서 5TB까지인 객체에 대해 멀티파트 업로드를 사용할 수 있습니다. 자세한 내용은 멀티파트 업로드를 사용한 객체 업로드 및 복사 섹션을 참조하세요.

객체를 업로드할 때 필요하다면 Amazon S3가 객체를 암호화하여 디스크에 저장하고 객체를 다운로드할 때 복호화하도록 요청할 수 있습니다. 자세한 내용은 암호화를 사용하여 데이터 보호 섹션을 참조하세요.

이 절차는 콘솔을 사용하여 S3 버킷에 객체 및 폴더를 업로드하는 방법에 대해 설명합니다.

객체를 업로드할 때 객체 키 이름은 파일 이름과 선택적 접두사입니다. Amazon S3 콘솔에서 폴더를 생성하여 객체를 구성할 수 있습니다. Amazon S3에서 폴더는 객체 키 이름에 나타나는 접두사로 표시됩니다. Amazon S3 콘솔의 폴더에 개별 객체를 업로드하면 객체 키 이름에 폴더 이름이 포함됩니다.

예를 들어 이름이 sample1.jpg인 객체를 이름이 backup인 폴더에 업로드하는 경우 키 이름은 backup/sample1.jpg입니다. 그러나 콘솔에는 해당 객체가 sample1.jpg 폴더의 backup로 표시됩니다. 키 이름에 대한 자세한 내용은 객체 메타데이터 작업 단원을 참조하세요.

참고

S3 콘솔에서 객체 이름을 바꾸거나 스토리지 클래스, 암호화, 메타데이터 등의 속성을 변경하면 새 객체가 생성되어 이전 객체를 대체합니다. S3 버전 관리가 활성화된 경우 객체의 새 버전이 생성되고 기존 객체는 이전 버전이 됩니다. 또한 속성을 변경하는 역할도 새 객체(또는 객체 버전)의 소유자가 됩니다.

폴더를 업로드하면 Amazon S3는 지정된 폴더의 모든 파일과 하위 폴더를 버킷으로 업로드합니다. 그러면 업로드된 파일 이름과 폴더 이름을 조합하여 객체 키 이름이 지정됩니다. 예를 들어 /imagessample1.jpg라는 두 개의 파일을 포함하는 폴더 sample2.jpg를 업로드하는 경우 Amazon S3는 파일을 업로드한 후 해당 키 이름인 images/sample1.jpgimages/sample2.jpg를 할당합니다. 키 이름에는 폴더 이름이 접두사로 포함됩니다. Amazon S3 콘솔에는 마지막 "/" 이후의 키 이름 부분만 표시됩니다. 예를 들어, 이미지 폴더의 images/sample1.jpgimages/sample2.jpg 객체는 sample1.jpgsample2.jpg로 표시됩니다.

S3 버킷에 폴더 및 파일을 업로드하는 방법

  1. AWS Management Console에 로그인한 후 https://console.aws.amazon.com/s3/에서 Amazon S3 콘솔을 엽니다.

  2. 버킷 목록에서 폴더 또는 파일을 업로드할 버킷 이름을 선택합니다.

  3. 업로드를 선택합니다.

  4. 업로드 창에서 다음 중 하나를 수행합니다.

    • 파일 및 폴더를 업로드 창으로 끌어다 놓습니다.

    • 파일 추가 또는 폴더 추가를 선택하고 업로드할 파일 또는 폴더를 선택한 후 열기를 선택합니다.

  5. 버전 관리를 활성화하려면 대상에서 버킷 버전 관리 활성화를 선택합니다.

  6. 추가 업로드 옵션을 구성하지 않고 나열된 파일 및 폴더를 업로드하려면 페이지 하단에서 업로드를 선택합니다.

    Amazon S3가 객체와 폴더를 업로드합니다. 업로드가 완료되면 업로드: 상태 페이지에서 성공 메시지를 볼 수 있습니다.

  7. 업로드 전에 추가 객체 속성을 구성하려면 추가 객체 속성을 구성하려면 섹션을 참조하세요.

추가 객체 속성을 구성하려면

  1. 추가 객체 속성을 구성하려면 추가 업로드 옵션을 선택합니다.

  2. 스토리지 클래스에서 업로드하려는 파일의 스토리지 클래스를 선택합니다.

    스토리지 클래스에 대한 자세한 정보는 Amazon S3 스토리지 클래스 사용를 참조하세요.

  3. 객체에 대한 암호화 설정을 업데이트하려면 서버 측 암호화 설정에서 다음을 수행합니다.

    1. 기본 암호화 버킷 설정 재정의를 선택합니다.

    2. Amazon S3에서 관리하는 키를 사용하여 업로드된 파일을 암호화하려면 Amazon S3 키(SSE-S3)를 선택합니다.

      자세한 내용은 Amazon S3가 관리하는 암호화 키(SSE-S3)를 사용하는 서버 측 암호화로 데이터 보호 섹션을 참조하세요.

    3. AWS Key Management Service(AWS KMS)를 사용하여 업로드된 파일을 암호화하려면 [AWS Key Management Service 키(SSE-KIM)(AWS Key Management Service key(SSE-KMS))]를 선택합니다. 그런 다음 AWS KMS 키에 대한 옵션을 선택합니다.

      • AWS 관리형 키 - AWS 관리형 키를 선택합니다.

      • KMS 루트 키에서 선택 - 버킷과 동일한 리전의 KMS 키 목록에서 고객 관리형 키를 선택합니다.

        고객 관리형 키 생성에 대한 자세한 내용은 AWS Key Management Service 개발자 안내서키 생성을 참조하세요. AWS KMS로 데이터를 보호하는 방법에 대한 자세한 내용은 AWS Key Management Service에 저장된 KMS 키를 사용하는 서버 측 암호화(SSE-KMS)로 데이터 보호 섹션을 참조하세요.

      • KMS 루트 키 ARN 입력 - 고객 관리형 키에 대한 AWS KMS 키 ARN을 지정하고 Amazon 리소스 이름(ARN)을 입력합니다.

        KMS 루트 키 ARN을 사용하여 외부 계정에 AWS KMS key로 보호되는 객체를 사용할 수 있는 권한을 부여할 수 있습니다. 이렇게 하려면 KMS 루트 키 ARN 입력을 선택하고 외부 계정의 Amazon 리소스 이름(ARN)을 입력합니다. KMS 키로 보호되는 객체에 대한 사용 권한이 있는 외부 계정의 관리자는 리소스 수준의 IAM 정책을 만들어 액세스를 더 제한할 수 있습니다.

      참고

      버킷의 객체를 암호화할 때는 해당 버킷과 동일한 AWS 리전 에 있는 AWS KMS keys만 사용할 수 있습니다.

  4. 액세스 제어 목록 권한을 변경하려면 ACL(액세스 제어 목록)에서 권한을 편집합니다.

    객체 액세스 권한에 대한 자세한 내용은 S3 콘솔을 사용하여 객체에 대한 ACL 권한 설정를 참조하세요. 현재 업로드 중인 모든 파일에 대해 일반 대중(전 세계 모든 사람)에게 객체에 대한 읽기 액세스 권한을 부여할 수 있습니다. 퍼블릭 읽기 액세스의 기본 설정은 변경하지 않는 것이 좋습니다. 퍼블릭 읽기 액세스 권한 부여는 웹 사이트에 버킷을 사용하는 경우와 같은 사용 사례의 작은 하위 집합에 적용할 수 있습니다. 객체를 업로드한 후에도 언제든 객체 권한을 변경할 수 있습니다.

  5. 업로드 중인 모든 객체에 태그를 추가하려면 태그 추가를 선택합니다. 필드에 태그 이름을 입력합니다. 태그의 값을 입력합니다.

    객체 태그 지정을 통해 스토리지를 분류할 수 있습니다. 각 태그는 키-값 페어입니다. 키와 태그 값은 대/소문자를 구분합니다. 객체마다 태그를 10개까지 포함할 수 있습니다. 태그 키는 최대 128개 유니코드 문자이며, 태그 값은 최대 255개 유니코드 문자입니다. 객체 태그에 대한 자세한 내용은 태그를 사용하여 스토리지 분류 섹션을 참조하세요.

  6. 메타데이터를 추가하려면 메타데이터 추가를 선택합니다.

    1. 유형에서 시스템 정의 또는 사용자 정의를 선택합니다.

      시스템 정의 메타데이터의 경우, 콘텐츠 유형콘텐츠 처리 같은 일반적인 HTTP 헤더를 선택할 수 있습니다. 시스템 정의 메타데이터 목록과 값 추가 가능 여부를 확인하려면 시스템 정의 객체 메타데이터 단원을 참조하세요. 접두사 x-amz-meta-(으)로 시작하는 모든 메타데이터는 사용자 정의 메타데이터로 처리됩니다. 사용자 정의 메타데이터는 객체와 함께 저장되었다가 해당 객체를 다운로드할 때 반환됩니다. 키와 값 모두 US-ASCII 표준에 부합해야 합니다. 사용자 정의 메타데이터의 최대 크기는 2KB입니다. 시스템 정의 메타데이터와 사용자 정의 메타데이터에 대한 자세한 내용은 객체 메타데이터 작업 단원을 참조하세요.

    2. 에 대해 키를 선택합니다.

    3. 키 값을 입력합니다.

  7. 객체를 업로드하려면 업로드를 선택합니다.

    Amazon S3가 객체를 업로드합니다. 업로드가 완료되면 업로드: 상태 페이지에서 성공 메시지를 볼 수 있습니다.

  8. 종료를 선택합니다.

Amazon S3에서 AWS SDK를 사용하여 객체를 업로드할 수 있습니다. SDK는 데이터를 간편하게 업로드할 수 있는 래퍼 라이브러리를 제공합니다. 자세한 내용은 지원되는 SDK 목록을 참조하세요.

다음은 엄선된 SDK가 포함된 몇 가지 예입니다.

.NET

다음 C# 코드 예제에서는 PutObjectRequest 요청 두 개로 객체 두 개를 만듭니다.

  • 첫 번째 PutObjectRequest 요청은 텍스트 문자열을 샘플 객체 데이터로 저장합니다. 또한 버킷과 객체 키 이름도 지정합니다.

  • 두 번째 PutObjectRequest 요청은 파일 이름을 지정하여 파일을 업로드합니다. 이 요청은 ContentType 헤더와 객체 메타데이터(제목)도 지정합니다.

실제 예제를 작성하여 테스트하는 방법에 대한 자세한 내용은 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

다음 예제에서는 객체 두 개를 만듭니다. 첫 번째 객체는 텍스트 문자열을 데이터로 갖고 있고, 두 번째 객체는 파일입니다. 이 예제에서는 AmazonS3Client.putObject()에 대한 호출로 직접 버킷 이름, 객체 키 및 텍스트 데이터를 지정하여 첫 번째 객체를 만듭니다. 이 예제에서는 버킷 이름, 객체 키 및 파일 경로를 지정하는 PutObjectRequest를 사용하여 두 번째 객체를 만듭니다. PutObjectRequestContentType 헤더 및 제목 메타데이터도 지정합니다.

실제 예제를 작성 및 테스트하는 방법에 대한 자세한 내용은 Amazon S3 Java 코드 예제 테스트 섹션을 참조하세요.

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

다음 예제에서는 특정 리전의 Amazon S3 버킷에 기존 파일을 업로드합니다.

// 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 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

이 단원에서는 AWS SDK for PHP의 클래스를 사용하여 최대 5GB 크기의 객체를 업로드하는 방법을 설명합니다. 5GB보다 큰 파일은 멀티파트 업로드 API를 사용해야 합니다. 자세한 내용은 멀티파트 업로드를 사용한 객체 업로드 및 복사 섹션을 참조하세요.

이 주제에서는 이미 AWS SDK for PHP 사용 및 PHP 예제 실행의 지침에 따라 AWS SDK for PHP가 올바르게 설치되어 있다고 가정합니다.

예 - 데이터를 업로드하여 Amazon S3 버킷에 객체 생성

다음 PHP 예제는 putObject() 메서드를 사용한 데이터 업로드를 통해 지정된 버킷에 객체를 생성합니다. 이 가이드의 PHP 예제 실행에 대한 자세한 내용은 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

AWS SDK for Ruby - 버전 3은 Amazon S3로 객체를 업로드하는 2가지 방법을 제공합니다. 첫 번째 방법은 간편하게 디스크에서 모든 크기의 파일을 업로드할 수 있는 관리형 파일 업로더를 사용합니다. 관리형 파일 업로더 방법을 사용하려면:

  1. Aws::S3::Resource 클래스의 인스턴스를 만듭니다.

  2. 버킷 이름과 키로 대상 객체를 참조합니다. 객체가 버킷에 상주하며 각 객체를 식별하는 고유의 키가 있습니다.

  3. 객체의 #upload_file을 호출합니다.

require 'aws-sdk-s3' # Uploads an object to a bucket in Amazon Simple Storage Service (Amazon S3). # # Prerequisites: # # - An S3 bucket. # - An object to upload to the bucket. # # @param s3_client [Aws::S3::Resource] An initialized S3 resource. # @param bucket_name [String] The name of the bucket. # @param object_key [String] The name of the object. # @param file_path [String] The path and file name of the object to upload. # @return [Boolean] true if the object was uploaded; otherwise, false. # @example # exit 1 unless object_uploaded?( # Aws::S3::Resource.new(region: 'us-east-1'), # 'doc-example-bucket', # 'my-file.txt', # './my-file.txt' # ) def object_uploaded?(s3_resource, bucket_name, object_key, file_path) object = s3_resource.bucket(bucket_name).object(object_key) object.upload_file(file_path) return true rescue StandardError => e puts "Error uploading object: #{e.message}" return false end

AWS SDK for Ruby 버전 3에서 객체를 업로드하는 두 번째 방법은 #putAws::S3::Object 메서드를 사용하는 것입니다. 객체가 문자열이거나 디스크에 저장된 파일이 아닌 I/O 객체인 경우 이 방법이 유용합니다. 이 방법을 사용하려면:

  1. Aws::S3::Resource 클래스의 인스턴스를 만듭니다.

  2. 버킷 이름과 키로 대상 객체를 참조합니다.

  3. 문자열 또는 I/O 객체를 전달하는 #put을 호출합니다.

require 'aws-sdk-s3' # Uploads an object to a bucket in Amazon Simple Storage Service (Amazon S3). # # Prerequisites: # # - An S3 bucket. # - An object to upload to the bucket. # # @param s3_client [Aws::S3::Resource] An initialized S3 resource. # @param bucket_name [String] The name of the bucket. # @param object_key [String] The name of the object. # @param file_path [String] The path and file name of the object to upload. # @return [Boolean] true if the object was uploaded; otherwise, false. # @example # exit 1 unless object_uploaded?( # Aws::S3::Resource.new(region: 'us-east-1'), # 'doc-example-bucket', # 'my-file.txt', # './my-file.txt' # ) def object_uploaded?(s3_resource, bucket_name, object_key, file_path) object = s3_resource.bucket(bucket_name).object(object_key) File.open(file_path, 'rb') do |file| object.put(body: file) end return true rescue StandardError => e puts "Error uploading object: #{e.message}" return false end

객체를 업로드하기 위해 REST 요청을 보낼 수 있습니다. PUT 요청을 전송하여 단일 작업에서 데이터를 업로드할 수 있습니다. 자세한 내용은 PUT Object 단원을 참조하세요.

PUT 요청을 보내 한 번의 작업으로 최대 5GB의 객체를 업로드할 수 있습니다. 자세한 내용은 AWS CLI 명령 참조PutObject 예시를 참조하세요.