객체 업로드

객체 업로드 (Uploading objects)

파일을 Amazon S3에 업로드하면 S3 *객체(object)*로 저장돼요. 객체는 파일 데이터와 객체를 설명하는 메타데이터로 구성돼요. 버킷에는 무제한으로 객체를 저장할 수 있어요. 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는 기존 객체를 대체하는 대신 객체의 또 다른 버전을 만들어요. 버전 관리 활성화에 대한 자세한 내용은 버킷에서 버전 관리 활성화를 참고하세요.

업로드하는 데이터의 크기에 따라 Amazon S3는 다음 옵션을 제공해요.

AWS SDK, REST API 또는 AWS CLI로 단일 작업으로 객체 업로드 – 단일 PUT 작업으로 최대 5GB 크기의 객체 하나를 업로드할 수 있어요.
Amazon S3 콘솔로 단일 객체 업로드 – Amazon S3 콘솔로 최대 160GB 크기의 객체 하나를 업로드할 수 있어요.
AWS SDK, REST API 또는 AWS CLI로 객체를 여러 부분으로 나눠 업로드 – 멀티파트 업로드 API 작업을 사용해 최대 50TB 크기의 단일 대형 객체를 업로드할 수 있어요. 멀티파트 업로드 API 작업은 대형 객체의 업로드 경험을 개선하도록 설계됐어요. 객체를 여러 부분으로 나눠 업로드할 수 있어요. 이러한 객체 부분은 서로 독립적으로, 어떤 순서로든, 병렬로 업로드할 수 있어요. 5MB에서 50TB 크기의 객체에 멀티파트 업로드를 사용할 수 있어요. 자세한 내용은 Amazon S3에서 멀티파트 업로드를 사용한 객체 업로드 및 복사를 참고하세요.

5TB보다 큰 파일을 업로드하려면 Java v1/v2, Python 또는 AWS CLI SDK의 S3 Transfer Manager를 사용해요. 최상의 성능을 위해 이러한 SDK와 함께 최신 AWS Common Runtime(CRT)을 사용하세요. CRT는 더 나은 리소스 활용을 위해 최적화되어 있어요.

메모리 스트림에서 대형 객체를 업로드할 때 CRT는 각 부분을 메모리에 최대 5GB까지 버퍼링하므로, 할당된 메모리에 따라 전체 처리량이 제한돼요. Java SDK의 maxNativeMemoryLimitInBytes 같은 구성 옵션을 사용해 CRT 메모리 한도를 조정할 수 있어요. 디스크에서 업로드할 때 CRT는 중간 부분 버퍼링 대신 직접 디스크 스트리밍으로 자동 전환해 메모리 사용을 개선해요. 이 동작은 대형 객체에 자동으로 활성화되지만, AWS CLI의 should_stream이나 Java SDK의 CRT_MEMORY_BUFFER_DISABLED 같은 요청 파라미터를 통해 더 작은 파일에도 활성화할 수 있어요.

객체를 업로드하면 기본적으로 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에서 Access Denied(403 Forbidden) 오류가 발생하면 Amazon S3의 접근 거부(403 Forbidden) 오류 문제 해결을 참고해 일반적인 원인에 대해 알아보세요.

객체 업로드 (Upload an object)

이 절차는 콘솔을 사용해 객체와 폴더를 Amazon S3 버킷에 업로드하는 방법을 설명해요.

객체를 업로드하면 객체 키 이름은 파일 이름과 선택적 접두사가 돼요. Amazon S3 콘솔에서 객체를 정리하기 위해 폴더를 만들 수 있어요. Amazon S3에서 폴더는 객체 키 이름에 나타나는 접두사로 표현돼요. Amazon S3 콘솔의 폴더에 개별 객체를 업로드하면 폴더 이름이 객체 키 이름에 포함돼요.

예를 들어 backup 폴더에 sample1.jpg라는 객체를 업로드하면 키 이름은 backup/sample1.jpg가 돼요. 하지만 콘솔에서는 객체가 backup 폴더 안의 sample1.jpg로 표시돼요. 키 이름에 대한 자세한 내용은 객체 메타데이터 작업을 참고하세요.

참고 Amazon S3 콘솔에서 객체 이름을 바꾸거나 속성(예: 스토리지 클래스(Storage Class), 암호화(Encryption), 메타데이터(Metadata))을 변경하면, 기존 객체를 대체하는 새 객체가 만들어져요. S3 버전 관리가 활성화되어 있으면 객체의 새 버전이 생성되고 기존 객체는 이전 버전이 돼요. 속성을 변경하는 역할도 새 객체(또는 객체 버전)의 소유자가 돼요.

폴더를 업로드하면 Amazon S3는 지정된 폴더의 모든 파일과 하위 폴더를 버킷에 업로드해요. 그런 다음 업로드한 파일 이름과 폴더 이름을 결합한 객체 키 이름을 할당해요. 예를 들어 sample1.jpg와 sample2.jpg 두 파일이 들어 있는 /images 폴더를 업로드하면, Amazon S3는 파일을 업로드한 다음 해당 키 이름 images/sample1.jpg와 images/sample2.jpg를 할당해요. 키 이름에는 폴더 이름이 접두사로 포함돼요. Amazon S3 콘솔은 키 이름 중 마지막 / 뒤 부분만 표시해요. 예를 들어 images 폴더 안의 images/sample1.jpg와 images/sample2.jpg 객체는 sample1.jpg와 sample2.jpg로 표시돼요.

폴더와 파일을 S3 버킷에 업로드 (To upload folders and files to an S3 bucket)

AWS Management Console에 로그인하고 https://console.aws.amazon.com/s3/에서 Amazon S3 콘솔을 엽니다.
왼쪽 탐색 창에서 **버킷(Buckets)**을 선택해요.
버킷(Buckets) 목록에서 폴더나 파일을 업로드할 버킷 이름을 선택해요.
**업로드(Upload)**를 선택해요.
업로드(Upload) 창에서 다음 중 하나를 수행해요.
- 파일과 폴더를 업로드(Upload) 창으로 끌어다 놓아요.
- 파일 추가(Add file) 또는 **폴더 추가(Add folder)**를 선택하고 업로드할 파일이나 폴더를 선택한 다음 **열기(Open)**를 선택해요.
버전 관리를 활성화하려면 대상(Destination) 아래에서 **버킷 버전 관리 활성화(Enable Bucket Versioning)**를 선택해요.
추가 업로드 옵션을 구성하지 않고 나열된 파일과 폴더를 업로드하려면 **업로드(Upload)**를 선택해요. Amazon S3가 객체와 폴더를 업로드해요. 업로드가 끝나면 업로드: 상태(Upload: status) 페이지에 성공 메시지가 표시돼요.

추가 객체 속성 구성 (To configure additional object properties)

접근 제어 목록 권한을 변경하려면 **권한(Permissions)**을 선택해요.
접근 제어 목록(ACL) 아래에서 권한을 편집해요. 객체 접근 권한에 대한 자세한 내용은 S3 콘솔을 사용해 객체에 ACL 권한 설정하기를 참고하세요. 업로드하는 모든 파일에 대해 객체에 대한 공개 읽기 접근(전 세계 모든 사용자)을 부여할 수 있어요. 다만 공개 읽기 접근의 기본 설정을 변경하지 않는 것을 권장해요. 공개 읽기 접근 부여는 버킷을 웹사이트에 사용하는 경우처럼 소수의 사용 사례에만 적용 가능해요. 객체를 업로드한 후 언제든지 객체 권한을 변경할 수 있어요.
다른 추가 속성을 구성하려면 **속성(Properties)**을 선택해요.
스토리지 클래스(Storage class) 아래에서 업로드할 파일의 스토리지 클래스를 선택해요. 스토리지 클래스에 대한 자세한 내용은 Amazon S3 스토리지 클래스 이해 및 관리를 참고하세요.
객체의 암호화 설정을 업데이트하려면 서버 측 암호화 설정(Server-side encryption settings) 아래에서 다음을 수행해요.
- **암호화 키 지정(Specify an encryption key)**을 선택해요.
- 암호화 설정(Encryption settings) 아래에서 기본 암호화에 버킷 설정 사용(Use bucket settings for default encryption) 또는 **기본 암호화에 버킷 설정 재정의(Override bucket settings for default encryption)**를 선택해요.
- **기본 암호화에 버킷 설정 재정의(Override bucket settings for default encryption)**를 선택했다면 다음 암호화 설정을 구성해야 해요.
  - Amazon S3가 관리하는 키로 업로드된 파일을 암호화하려면 **Amazon S3 관리형 키(SSE-S3)**를 선택해요. 자세한 내용은 Amazon S3 관리형 키를 사용한 서버 측 암호화(SSE-S3)를 참고하세요.
  - AWS Key Management Service(AWS KMS)에 저장된 키로 업로드된 파일을 암호화하려면 **AWS Key Management Service 키(SSE-KMS)**를 선택해요. 그런 다음 **AWS KMS 키(AWS KMS key)**에 대해 다음 옵션 중 하나를 선택해요.
    - 사용 가능한 KMS 키 목록에서 선택하려면 **AWS KMS 키에서 선택(Choose from your AWS KMS keys)**을 선택한 다음 사용 가능한 키 목록에서 **KMS 키(KMS key)**를 선택해요. AWS 관리형 키(aws/s3)와 고객 관리형 키가 모두 이 목록에 나타나요. 고객 관리형 키에 대한 자세한 내용은 AWS Key Management Service 개발자 가이드의 고객 키와 AWS 키를 참고하세요.
    - KMS 키 ARN을 입력하려면 **AWS KMS 키 ARN 입력(Enter AWS KMS key ARN)**을 선택한 다음 나타나는 필드에 KMS 키 ARN을 입력해요.
    - AWS KMS 콘솔에서 새 고객 관리형 키를 만들려면 **KMS 키 만들기(Create a KMS key)**를 선택해요. AWS KMS 키 생성에 대한 자세한 내용은 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 키 식별을 참고하세요.
추가 체크섬을 사용하려면 **켜짐(On)**을 선택해요. 그런 다음 **체크섬 함수(Checksum function)**에서 사용할 함수를 선택해요. Amazon S3는 전체 객체를 수신한 후 체크섬 값을 계산해 저장해요. 사전 계산된 값(Precalculated value) 상자를 사용해 사전 계산된 값을 제공할 수 있어요. 제공하면 Amazon S3는 사용자가 제공한 값과 직접 계산한 값을 비교해요. 두 값이 일치하지 않으면 Amazon S3는 오류를 생성해요. 추가 체크섬을 사용하면 데이터를 검증하는 데 사용할 체크섬 알고리즘을 지정할 수 있어요. 추가 체크섬에 대한 자세한 내용은 Amazon S3에서 객체 무결성 확인을 참고하세요.
업로드하는 모든 객체에 태그를 추가하려면 **태그 추가(Add tag)**를 선택해요. 키(Key) 필드에 태그 이름을 입력하고 태그의 **값(Value)**을 입력해요. 객체 태깅은 스토리지를 분류하는 방법을 제공해요. 각 태그는 키-값 쌍이에요. 키와 태그 값은 대소문자를 구분해요. 객체당 최대 10개의 태그를 가질 수 있어요. 태그 키는 최대 128자(유니코드), 태그 값은 최대 255자(유니코드)까지 사용할 수 있어요. 객체 태그에 대한 자세한 내용은 객체 태깅을 참고하세요.
메타데이터를 추가하려면 **메타데이터 추가(Add metadata)**를 선택해요. 유형(Type) 아래에서 시스템 정의(System defined) 또는 **사용자 정의(User defined)**를 선택해요. 시스템 정의 메타데이터의 경우 Content-Type, Content-Disposition 같은 일반적인 HTTP 헤더를 선택할 수 있어요. 시스템 정의 메타데이터 목록과 값을 추가할 수 있는지에 대한 정보는 시스템 정의 객체 메타데이터를 참고하세요. x-amz-meta- 접두사로 시작하는 메타데이터는 모두 사용자 정의 메타데이터로 처리돼요. 사용자 정의 메타데이터는 객체와 함께 저장되고 객체를 다운로드할 때 반환돼요. 키와 값 모두 US-ASCII 표준을 따라야 해요. 사용자 정의 메타데이터는 최대 2KB까지 가능해요. 시스템 정의 및 사용자 정의 메타데이터에 대한 자세한 내용은 객체 메타데이터 작업을 참고하세요. **키(Key)**에 대해 키를 선택하고 키에 대한 **값(Value)**을 입력해요.
객체를 업로드하려면 **업로드(Upload)**를 선택해요. Amazon S3가 객체를 업로드해요. 업로드가 완료되면 업로드: 상태(Upload: status) 페이지에 성공 메시지가 표시돼요.
**종료(Exit)**를 선택해요.

단일 작업으로 최대 5GB 크기의 객체를 업로드하도록 PUT 요청을 보낼 수 있어요. 자세한 내용은 AWS CLI Command Reference의 PutObject 예시를 참고하세요.

객체를 업로드하도록 REST 요청을 보낼 수 있어요. 단일 작업으로 데이터를 업로드하도록 PUT 요청을 보낼 수 있어요. 자세한 내용은 PUT Object를 참고하세요.

AWS SDK로 객체를 업로드하는 예시는 Amazon Simple Storage Service API Reference의 코드 예시를 참고하세요.

다양한 AWS SDK 사용에 대한 일반적인 정보는 Amazon Simple Storage Service API Reference의 AWS SDK를 사용한 Amazon S3 개발을 참고하세요.

동일한 키 이름을 가진 객체 업로드 방지 (Prevent uploading objects with identical key names)

업로드 작업에 조건부 쓰기(conditional write)를 사용해 객체를 만들기 전에 버킷에 객체가 이미 존재하는지 확인할 수 있어요. 이렇게 하면 기존 데이터가 덮어써지는 것을 방지할 수 있어요. 조건부 쓰기는 업로드하는 동안 버킷에 같은 키 이름의 기존 객체가 없는지 검증해요.

PutObject 또는 CompleteMultipartUpload 요청에 조건부 쓰기를 사용할 수 있어요.

조건부 요청에 대한 자세한 내용은 조건부 요청으로 S3 작업에 사전 조건 추가를 참고하세요.