Amazon S3 객체에 주석 달기

Amazon S3 객체에 주석 달기

Annotation을 사용해 Amazon S3 객체에 이름이 있는 데이터 페이로드를 붙일 수 있어요. 각 주석은 1바이트에서 1MiB 크기의 사용자 지정 메타데이터 페이로드이며, 객체 자체를 수정하지 않고 생성, 검색, 나열, 삭제할 수 있어요.

객체 버전당 최대 1,000개의 주석을 연결할 수 있어요. 각 주석은 고유한 이름을 가지며, AI 생성 라벨, 문서 컨텍스트, 처리 결과, 규정 준수 기록 같은 구조화된 데이터를 저장할 수 있어요.

출처: 문서

본문

일반적인 사용 사례는 머신 러닝 추론 결과, AI 생성 임베딩, 콘텐츠 조정 라벨, 문서 분류 출력, 데이터 계보(lineage) 및 감사 추적, PII 플래그나 보존 정책 같은 규정 준수 라벨, 의료 영상 메타데이터, 디지털 자산 권리 정보, ETL 파이프라인 상태를 원본 객체와 함께 저장하는 것입니다.

주석은 전용 API 작업으로 관리되므로, 메타데이터를 추가하거나 업데이트하기 위해 객체를 다시 업로드할 필요가 없어요.

S3 Metadata 구성의 일부로 **주석 테이블(annotation table)**을 활성화하면 Athena 등 분석 서비스를 사용해 주석 데이터를 규모 있게 조회할 수 있어요. S3 Metadata는 주석 데이터를 완전 관리형 Apache Iceberg 테이블에 저장하고 Amazon S3가 자동으로 최신 상태로 유지해요.

주석은 모든 상용 AWS 리전과 중국 리전(베이징, 닝샤)에서 사용할 수 있어요. Middle East (UAE)와 Middle East (Bahrain) 리전에서는 사용할 수 없어요.

주석 vs 객체 태그: 언제 무엇을 쓸까

사용 사례에 더 잘 맞는 것이 무엇인지 다음 비교를 참고하세요.

JSON이나 XML 같은 구조화된 데이터, 256자보다 큰 페이로드, 객체당 10개 이상의 메타데이터 항목을 저장해야 할 때는 주석을 선택하세요. IAM 정책 통합, S3 Lifecycle 규칙 필터링, 비용 할당 보고가 필요할 때는 객체 태그를 선택하세요.

주석 API 작업

Amazon S3는 주석 작업을 위해 다음 API 작업을 지원해요.

• PutObjectAnnotation – 객체에 주석을 생성하거나 덮어써요. 요청에 주석 이름과 페이로드를 지정해요.
• GetObjectAnnotation – 이름으로 특정 주석의 페이로드를 반환해요.
• ListObjectAnnotations – 객체의 주석 목록을 반환해요. 각 주석의 이름, 크기, ETag, 마지막 수정 날짜를 포함해요.
• DeleteObjectAnnotation – 이름으로 특정 주석을 제거해요.

Amazon S3는 다음 API 작업에서도 주석을 지원해요.

• CopyObject – 기본적으로 소스 객체의 주석을 복사해요. x-amz-annotation-directive 헤더로 주석을 복사할지(COPY) 제외할지(EXCLUDE) 제어할 수 있어요.
• UpdateBucketMetadataAnnotationTableConfiguration – S3 Metadata 구성에서 주석 테이블을 활성화·비활성화해요.
• CreateBucketMetadataConfiguration – S3 Metadata 구성을 만들 때 주석 테이블을 활성화하는 AnnotationTableConfiguration 파라미터를 받아요.
• GetBucketMetadataConfiguration – 응답에 주석 테이블의 현재 상태를 나타내는 AnnotationTableConfigurationResult를 반환해요.

주석 제한 (Annotation limits)

각 객체 버전은 최대 1,000개의 주석을 지원해요. 같은 객체 버전에 연결된 주석은 고유한 이름을 가져야 해요. 다음 제한이 적용돼요.

• 주석 이름은 최대 512바이트(UTF-8) 길이.
• 주석 페이로드는 1바이트에서 1MiB 사이 크기.
• 객체당 총 주석 스토리지는 최대 1GiB(1MiB씩 1,000개).
• 지원되는 체크섬 알고리즘: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.

주석 명명 규칙 (Annotation naming rules)

주석 이름은 다음 요구 사항을 충족해야 해요.

• 길이 1~512바이트.
• 문자(모든 언어), 숫자(0-9), 밑줄(_), 마침표(.), 하이픈(-)만 사용 가능.
• aws 또는 s3로 시작 불가(대소문자 무시). aws, AWS, s3, S3는 모두 예약된 접두사예요.
• 비어 있거나 공백만으로 구성되면 안 됨.

암호화 (Encryption)

주석은 부모 객체와 동일한 암호화 구성을 사용해 재사용(rest) 시 자동으로 암호화돼요. 암호화 유형은 버킷 기본값이 아니라 부모 객체에서 상속돼요.

• SSE-S3 – 부모 객체가 Amazon S3 관리형 키(SSE-S3)를 사용하면 주석도 SSE-S3로 암호화돼요. 부모 객체에 서버 측 암호화가 구성되어 있지 않아도 주석은 기본적으로 SSE-S3로 암호화돼요.
• SSE-KMS – 부모 객체가 AWS KMS 키(SSE-KMS)를 사용하면 주석도 같은 KMS 키로 암호화돼요. 고객 관리형 키와 AWS 관리형 키 모두에 적용되며, S3 Bucket Keys를 지원해요.
• DSSE-KMS – 부모 객체가 AWS KMS 키를 사용한 이중 계층 서버 측 암호화(DSSE-KMS)를 사용하면 주석도 같은 키로 DSSE-KMS 암호화돼요.
• SSE-C – 고객 제공 키(SSE-C)를 사용한 서버 측 암호화는 주석에서 지원되지 않아요. SSE-C로 암호화된 객체에 주석을 추가하려고 하면 Amazon S3가 오류를 반환해요.

체크섬 (Checksums)

PutObjectAnnotation으로 주석을 업로드할 때 데이터 무결성을 검증하는 체크섬을 제공할 수 있어요. 주석의 체크섬 알고리즘은 부모 객체의 체크섬 알고리즘과 독립적이에요.

CopyObject로 객체를 복사하면 Amazon S3는 소스의 주석 체크섬 값을 보존해요. 복사 요청에서 다른 체크섬 알고리즘을 지정하면 새 알고리즘이 객체와 그 주석 모두에 적용돼요.

지원 알고리즘: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.

주석에 지정된 체크섬 알고리즘·값이 없으면 Amazon S3는 CRC-64/NVME 알고리즘으로 주석의 체크섬 값을 계산해요.

버전 관리 동작 (Versioning behavior)

주석은 특정 객체 버전에 붙어요. 한 객체 버전의 주석은 같은 객체의 다른 버전의 주석과 독립적이에요. 새 버전을 만들면 이전 버전에서 주석을 복사하지 않아요. 한 버전에서 주석을 삭제하거나 추가해도 다른 버전의 주석에 영향을 주지 않아요. 객체를 덮어쓰면 새 버전이 가진 주석으로 교체돼요(없으면 사실상 삭제).

주석을 추가·업데이트·제거해도 부모 객체의 ETag는 수정되지 않아요.

버전 관리 버킷에서는 다음 동작이 적용돼요.

• 버전 ID 없이 보낸 단순 DELETE 요청은 삭제 마커를 만들지만 기본 버전의 주석을 보존해요.
• 특정 버전 ID를 삭제하면 그 버전과 연결된 모든 주석을 삭제해요.
• 주석은 독립적으로 버전 관리되지 않아요. 같은 이름으로 주석을 덮어쓰면 Amazon S3는 새 객체 버전을 만들지 않고 이전 값을 교체해요.

중요: 주석 삭제는 버전 관리 버킷에서도 영구적이고 되돌릴 수 없어요. 버전 관리 버킷의 객체와 달리 주석에는 삭제 마커나 버전 기록이 없어요. 주석을 삭제하면 복구할 수 없어요.

복사 동작 및 일관성 (Copy behavior and consistency)

CopyObject API로 객체를 복사할 때(5GiB보다 작은 객체) Amazon S3는 단일 작업에서 객체와 함께 주석도 복사해요.

멀티파트 업로드로 객체를 복사할 때(예: AWS CLI 또는 SDK가 약 8MB보다 큰 객체에 Transfer Manager를 사용하는 경우) 주석은 기본적으로 복사되지 않아요. 주석을 포함하려면 AWS CLI에서 --copy-props all 또는 이에 상응하는 SDK 구성을 지정하세요. 이 옵트인을 사용하면 SDK가 소스 주석을 읽고, 멀티파트 업로드를 완료한 뒤 각 주석을 대상에 써요. 업로드 완료와 마지막 주석 쓰기 사이에는 대상 객체가 주석 없이 존재해요.

고려 사항 (Considerations)

• PutObject나 멀티파트 업로드 요청의 일부로 주석을 추가할 수 없어요. 객체에 주석을 추가하려면 업로드 후 PutObjectAnnotation을 호출하세요. 주석과 함께 기존 객체를 새 위치에 복사하려면 기본 주석 지시문과 함께 CopyObject를 사용하세요.
• 많은 객체에 주석을 일괄 추가·업데이트하려면 Batch Operations를 사용해 각 객체에서 PutObjectAnnotation을 호출하는 Lambda 함수를 실행하세요.
• 주석은 다음 기능에서 지원되지 않아요: S3 Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, S3 Express One Zone(디렉터리 버킷), Amazon S3 Files.
• 덮어쓰여진 것이 아니라 객체의 현재 버전에 주석을 쓰고 있는지 확인하려면 PutObjectAnnotation 또는 DeleteObjectAnnotation과 함께 x-amz-object-if-match 조건부 헤더를 사용하세요. 이 헤더는 부모 객체의 ETag를 검증해 호출자가 마지막으로 읽은 이후 객체가 덮어쓰여지지 않았는지 확인해요. 태그나 주석을 추가해도 ETag는 변하지 않아요.
• 다른 주석의 존재 유무에 따라 조건부로 주석을 추가할 수는 없어요. x-amz-object-if-match 헤더는 주석 상태가 아니라 부모 객체의 ETag만 검증해요.
• 주석 페이로드는 유효한 UTF-8 인코딩 텍스트여야 해요. 바이너리 데이터를 저장하려면 주석을 쓰기 전에 Base64로 인코딩하세요.
• 주석 API 작업(PutObjectAnnotation, GetObjectAnnotation, ListObjectAnnotations, DeleteObjectAnnotation)은 S3 Glacier와 S3 Glacier Deep Archive를 포함한 모든 스토리지 클래스의 객체에서 객체를 먼저 복원하지 않고 호출할 수 있어요.

추가 구성 (Additional configurations)

복제 (Replication) — 버킷에 S3 복제를 구성했다면 Amazon S3가 주석을 자동으로 복제해요. 각 주석은 독립적으로 복제돼요. 주석을 복제하려면 복제 IAM 역할의 소스 버킷 권한에 s3:GetObjectVersionAnnotationForReplication을 추가하세요. 객체 복제는 허용하면서 주석 복제만 막으려면 복제 역할 정책에 s3:ReplicateObjectAnnotation에 대한 deny 문장을 추가하세요. 객체 복제는 계속 성공하고 주석 복제만 차단돼요.

이벤트 알림 (Event notifications) — Amazon S3는 주석이 생성·업데이트·삭제될 때 이벤트 알림을 보낼 수 있어요. 다음 이벤트 유형을 구성할 수 있어요.

• s3:ObjectAnnotation:Put – 주석이 생성되거나 업데이트될 때 전송.
• s3:ObjectAnnotation:Delete – 주석이 삭제될 때 전송.

더 알아보기 (Learn more)

• 객체 주석 관리
• 객체 메타데이터 작업
• Amazon S3 객체 개요