객체 업로드 - Amazon Simple Storage Service

객체 업로드

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

이미지, 백업, 데이터, 동영상 등 모든 유형의 파일을 S3 버킷에 업로드할 수 있습니다. Amazon S3 콘솔을 사용하여 업로드할 수 있는 파일의 최대 크기는 160GB입니다. 160GB가 넘는 파일을 업로드하려면 AWS Command Line Interface(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 관리형 키(SSE-S3)를 통한 서버 측 암호화를 사용하여 객체가 자동으로 암호화됩니다. 다운로드하면 객체의 암호가 해독됩니다. 자세한 내용은 Amazon S3 버킷에 대한 기본 서버 측 암호화 동작 설정암호화로 데이터 보호 단원을 참조하세요.

객체를 업로드할 때 다른 유형의 기본 암호화를 사용하려는 경우 S3 PUT 요청에서 AWS Key Management Service(AWS KMS) 키(SSE-KMS)를 사용하여 서버 측 암호화를 지정하거나 SSE-KMS를 사용하여 데이터를 암호화하도록 대상 버킷의 기본 암호화 구성을 설정할 수도 있습니다. SSE-KMS에 대한 자세한 내용은 AWS KMS(SSE-KMS)를 사용한 서버 측 암호화 지정 단원을 참조하십시오. 다른 계정에서 소유한 KMS 키를 사용하려면 먼저 해당 키에 대한 사용 권한이 있어야 합니다. KMS 키의 크로스 계정 권한에 대한 자세한 내용은 AWS Key Management Service 개발자 안내서에서 다른 계정에서 사용할 수 있는 KMS 키 만들기를 참조하십시오.

Amazon S3에서 액세스 거부됨(403 Forbidden) 오류가 발생하는 경우 Amazon S3의 액세스 거부(403 금지) 오류 문제 해결 섹션에서 일반적인 원인에 대해 자세히 알아보세요.

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

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

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

참고

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

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

S3 버킷에 폴더 및 파일 업로드
  1. AWS Management Console에 로그인한 후 https://console.aws.amazon.com/s3/에서 Amazon S3 콘솔을 엽니다.

  2. 왼쪽 탐색 창에서 버킷(Buckets)을 선택합니다.

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

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

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

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

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

  6. 버전 관리를 사용 설정하려면 대상에서 버킷 버전 관리 사용 설정를 선택합니다.

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

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

추가 객체 속성 구성
  1. 액세스 제어 목록 권한을 변경하려면 권한(Permissions)을 선택합니다.

  2. 액세스 제어 목록(ACL)(Access control list (ACL))에서 권한을 편집합니다.

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

  3. 다른 추가 속성을 구성하려면 속성(Properties)을 선택합니다.

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

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

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

    1. 암호화 키 지정(Specify an encryption key)을 선택합니다.

    2. 암호화 설정에서 버킷 기본 암호화 설정 사용 또는 기본 암호화에 버킷 설정 재정의를 선택합니다.

    3. 기본 암호화에 버킷 설정 재정의를 선택한 경우 다음과 같은 암호화 설정을 구성해야 합니다.

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

        자세한 내용은 Amazon S3 관리형 키를 사용한 서버 측 암호화(SSE-S3) 사용 단원을 참조하십시오.

      • AWS Key Management Service(AWS KMS)에 저장된 키를 사용하여 업로드된 파일을 암호화하려면 AWS Key Management Service 키(SSE-KMS)를 선택합니다. 그리고 나서 AWS KMS 키에 다음 옵션 중 하나를 선택합니다.

        • 사용 가능한 KMS 키 목록에서 AWS KMS keys 중에서 선택을 선택한 다음, 사용 가능한 키 목록에서 KMS 키를 선택합니다.

          AWS 관리형 키(aws/s3)와 고객 관리형 키가 모두 목록에 표시됩니다. 고객 관리형 키에 대한 자세한 내용은 AWS Key Management Service 개발자 안내서의 고객 키 및 AWS 키를 참조하세요.

        • KMS 키 ARN을 입력하려면 AWS KMS key ARN 입력을 선택한 다음 나타나는 필드에 KMS 키 ARN을 입력합니다.

        • AWS KMS 콘솔에서 고객 관리형 키를 생성하려면 KMS 키 생성을 선택합니다.

          AWS KMS key 생성에 대한 자세한 내용은 AWS Key Management Service 개발자 가이드키 생성을 참조하십시오.

        중요

        버킷과 동일한 AWS 리전에서 사용할 수 있는 KMS 키만 사용 가능합니다. Amazon S3 콘솔은 버킷과 동일한 리전에 있는 처음 100개의 KMS 키만 나열합니다. 목록에 없는 KMS 키를 사용하려면 KMS 키 ARN을 입력해야 합니다. 다른 계정에서 소유한 KMS 키를 사용하려면 먼저 해당 키에 대한 사용 권한이 있어야 하고, 다음 단계로 KMS 키 ARN을 입력해야 합니다.

        Amazon S3는 대칭 암호화 KMS 키만 지원하며 비대칭 KMS 키는 지원하지 않습니다. 자세한 내용은 AWS Key Management Service 개발자 안내서에서 대칭 및 비대칭 KMS 키 식별을 참조하세요.

  6. 추가 체크섬을 사용하려면 켜기(On)를 선택합니다. 그런 다음 체크섬 함수(Checksum function)에서 사용할 함수를 선택합니다. Amazon S3는 전체 객체를 수신한 후 체크섬 값을 계산하고 저장합니다. 미리 계산된 값(Precalculated value) 상자를 사용하여 미리 계산된 값을 제공할 수 있습니다. 이렇게 하면 Amazon S3가 제공한 값과 계산한 값을 비교합니다. 두 값이 일치하지 않으면 Amazon S3가 오류를 생성합니다.

    추가 체크섬을 사용하면 데이터를 확인하는 데 사용할 체크섬 알고리즘을 지정할 수 있습니다. 추가 체크섬에 대한 자세한 내용은 객체 무결성 확인 단원을 참조하십시오.

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

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

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

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

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

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

    3. 키 값을 입력합니다.

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

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

  10. 종료를 선택합니다.

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

이 예시는 AWS SDK for PHP의 클래스를 사용하여 최대 5GB 크기의 객체를 업로드하는 방법을 설명합니다. 더 큰 파일의 경우 멀티파트 업로드 API 작업을 사용해야 합니다. 자세한 내용은 멀티파트 업로드를 사용한 객체 업로드 및 복사 단원을 참조하십시오.

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

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

다음 PHP 예제는 putObject() 메서드를 사용한 데이터 업로드를 통해 지정된 버킷에 객체를 생성합니다. 이 가이드의 PHP 예제 실행에 대한 자세한 내용은 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 - 버전 3은 Amazon S3로 객체를 업로드하는 2가지 방법을 제공합니다. 첫 번째 방법은 더 간편하게 디스크에서 모든 크기의 파일을 업로드할 수 있는 관리형 파일 업로더를 사용합니다. 관리형 파일 업로더 방법 사용:

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

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

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

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__

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

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

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

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

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__

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

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