View a markdown version of this page

사용자 객체에 주석 달기 - Amazon Simple Storage Service
주석과 객체 태그의 사용 시점주석에 대한 API 작업주석 제한주석 이름 지정 규칙암호화체크섬버전 관리 동작동작 및 일관성 복사고려 사항추가 구성

사용자 객체에 주석 달기

주석을 사용하여 명명된 데이터 페이로드를 Amazon S3 객체에 연결합니다. 각 주석은 객체 자체를 수정하지 않고 생성, 검색, 나열 및 삭제할 수 있는 1바이트~1MiB 크기의 사용자 지정 메타데이터 페이로드입니다.

객체 버전에 최대 1,000개의 주석을 연결할 수 있습니다. 각 주석에는 고유한 이름이 있으며 AI 생성 레이블, 문서 컨텍스트, 처리 결과 또는 규정 준수 레코드와 같은 정형 데이터를 저장할 수 있습니다.

일반적인 사용 사례로는 기계 학습 추론 결과, AI 생성 임베딩, 콘텐츠 조정 레이블, 문서 분류 출력, 데이터 리니지 및 감사 추적, PII 플래그 또는 보존 정책과 같은 규정 준수 레이블, 의료 영상 메타데이터, 디지털 자산 권리 정보, 소스 객체와 함께 ETL 파이프라인 상태를 저장하는 것이 있습니다.

전용 API 작업을 사용하여 주석을 관리하므로 메타데이터를 추가하거나 업데이트하기 위해 객체를 다시 업로드할 필요가 없습니다.

S3 Metadata 구성의 일부로 주석 테이블을 활성화하여 Athena 및 기타 분석 서비스를 사용하여 주석 데이터를 대규모로 쿼리할 수 있습니다. S3 Metadata는 Amazon S3가 자동으로 최신 상태로 유지하는 완전 관리형 Apache Iceberg 테이블에 주석 데이터를 저장합니다. 자세한 내용은 S3 메타데이터 테이블을 사용하여 데이터 검색 섹션을 참조하세요.

주석은 모든 상용 AWS 리전 및 중국 리전(베이징 및 닝샤)에서 사용할 수 있습니다. 중동(UAE) 및 중동(바레인) 리전에서는 주석을 사용할 수 없습니다. S3 Metadata 주석 테이블은 S3 Metadata를 사용할 수 있는 모든 리전에서 사용할 수 있습니다.

주석과 객체 태그의 사용 시점

다음 비교를 사용하여 주석 또는 객체 태그가 사용 사례에 가장 적합한지 확인합니다.

기능 객체 태그 Annotations
객체당 최댓값 객체 버전당 10개 객체 버전당 1,000개
최대 크기 128자(키) + 256자(값) 512바이트(이름) + 1MiB(페이로드)
데이터 형식 키-값 문자열 페어 모든 UTF-8 텍스트(JSON, XML, YAML 등)
변경 가능성 예(PutObjectTagging) 예(PutObjectAnnotation)
업로드 중 설정 예(PutObject, POST) 아니요(업로드 후 PutObjectAnnotation만 해당)

정형 데이터(예: JSON 또는 XML), 256자를 초과하는 페이로드 또는 객체당 10개 이상의 메타데이터 항목을 저장해야 하는 경우 주석을 선택합니다. IAM 정책 통합, Amazon S3 수명 주기 규칙 필터링 또는 비용 할당 보고가 필요한 경우 객체 태그를 선택합니다.

주석에 대한 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를 반환하며, 이는 주석 테이블의 현재 상태를 나타냅니다.

주석 제한

각 객체 버전은 최대 1,000개의 주석을 지원합니다. 객체 버전과 연결된 주석에는 고유한 주석 이름이 있어야 합니다. 다음과 같은 제한이 적용됩니다.

  • 주석 이름은 아래 이름 지정 규칙에 따라 최대 512바이트 길이(UTF-8)일 수 있습니다.

  • 주석 페이로드의 크기는 1바이트~1MiB여야 합니다.

  • 객체당 총 주석 스토리지는 최대 1GiB(각각 1MiB에서 주석 1,000개)일 수 있습니다.

  • 지원되는 체크섬 알고리즘: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, XXHASH64, XXHASH3, XXHASH128.

주석 이름 지정 규칙

주석 이름은 다음 요건을 충족해야 합니다.

  • 길이는 1~512바이트여야 합니다.

  • 문자(모든 언어), 숫자(0~9), 밑줄(_), 마침표(.), 하이픈(-)만 포함할 수 있습니다.

  • aws 또는 s3로 시작할 수 없습니다(대소문자 구분 없음). 예를 들어 aws, AWS, s3 및 S3는 모두 예약된 접두사입니다.

  • 비워 두거나 공백으로만 구성해서는 안 됩니다.

암호화

주석은 상위 객체와 동일한 암호화 구성을 사용하여 저장 시 자동으로 암호화됩니다. 암호화 유형은 버킷 기본값이 아닌 상위 객체에서 상속됩니다.

  • SSE-S3 - 상위 객체가 Amazon S3 관리형 키를 사용한 서버 측 암호화(SSE-S3)를 사용하는 경우 주석은 SSE-S3로 암호화됩니다. 상위 객체에 서버 측 암호화가 구성되어 있지 않은 경우 주석은 기본적으로 SSE-S3로 암호화됩니다.

  • SSE-KMS - 상위 객체가 AWS KMS 키를 사용한 서버 측 암호화(SSE-KMS)를 사용하는 경우 주석은 동일한 KMS 키로 암호화됩니다. 이는 AWS 관리형 키와 고객 관리형 키 모두에 적용됩니다. S3 버킷 키가 지원됩니다.

  • DSSE-KMS - 상위 객체가 AWS KMS 키를 사용한 이중 계층 서버 측 암호화(DSSE-KMS)를 사용하는 경우 주석은 동일한 키를 사용하여 DSSE-KMS로 암호화됩니다.

  • SSE-C – 주석의 경우 고객이 제공한 키를 사용한 서버 측 암호화(SSE-C)는 지원되지 않습니다. SSE-C로 암호화된 객체에 주석을 추가하려고 하면 Amazon S3가 오류를 반환합니다.

체크섬

PutObjectAnnotation을 사용하여 주석을 업로드할 때 체크섬을 제공하여 데이터 무결성을 확인할 수 있습니다. 주석에 대한 체크섬 알고리즘은 상위 객체의 체크섬 알고리즘과 독립적입니다.

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

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

주석에 지정된 체크섬 알고리즘 또는 체크섬 값이 없는 경우 Amazon S3는 CRC-64/NVME 알고리즘을 사용하여 주석의 체크섬 값을 계산합니다.

버전 관리 동작

주석은 특정 객체 버전에 연결됩니다.

한 객체 버전에 대한 주석은 동일한 객체의 다른 버전에 대한 주석과 독립적입니다. 새 버전을 생성해도 이전 버전의 주석은 복사되지 않습니다. 한 버전에서 주석을 삭제하거나 추가해도 다른 버전의 주석에는 영향을 주지 않습니다. 객체를 덮어쓰면 해당 주석이 새 버전에 있는 주석으로 바뀝니다(없을 경우 사실상 해당 주석을 삭제함).

주석을 추가, 업데이트 또는 제거해도 상위 객체의 ETag는 수정되지 않습니다.

버전이 지정되지 않은 버킷에서 객체를 삭제하거나 덮어쓰면 주석이 함께 삭제됩니다.

버전이 지정된 버킷에서는 다음 동작이 적용됩니다.

  • 간단한 DELETE 요청(버전 ID를 지정하지 않음)은 삭제 마커를 생성하지만 기본 버전에 대한 주석은 그대로 유지합니다.

  • 특정 버전 ID를 삭제하면 해당 버전과 연결된 모든 주석이 삭제됩니다.

  • 주석은 독립적으로 버전이 지정되지 않습니다. 동일한 이름으로 주석을 덮어쓰면 Amazon S3는 새 객체 버전을 생성하지 않고 이전 값을 대체합니다.

중요

주석 삭제는 버전이 지정된 버킷에서도 영구적이고 되돌릴 수 없습니다. 버전이 지정된 버킷의 객체와 달리 주석에는 삭제 마커 또는 버전 기록이 없습니다. 주석을 삭제한 후에는 복구할 수 없습니다.

동작 및 일관성 복사

CopyObject API를 사용하여 객체를 복사하는 경우(5GiB보다 작은 객체의 경우) Amazon S3는 단일 작업으로 객체와 함께 주석을 복사합니다.

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

고려 사항

  • PutObject 또는 멀티파트 업로드 요청의 일부로 주석을 추가할 수 없습니다. 객체에 주석을 추가하려면 객체가 업로드된 후 PutObjectAnnotation을 직접적으로 호출합니다. 주석이 있는 기존 객체를 새 위치에 복사하려면 기본 주석 지시어와 함께 CopyObject를 사용합니다.

  • 많은 객체에 주석을 대량으로 추가하거나 업데이트하려면 배치 작업을 사용하여 각 객체에서 PutObjectAnnotation을 직접적으로 호출하는 Lambda 함수를 간접적으로 호출합니다. 자세한 내용은 AWS 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로 데이터를 인코딩합니다.

  • 객체를 먼저 복원하지 않고도 S3 Glacier 및 S3 Glacier Deep Archive를 포함한 모든 스토리지 클래스의 객체에서 주석 API 작업(PutObjectAnnotation, GetObjectAnnotation, ListObjectAnnotations, DeleteObjectAnnotation)을 직접적으로 호출할 수 있습니다.

추가 구성

이 섹션에서는 주석이 다른 구성과 어떤 관계를 맺는지에 대해 설명합니다.

복제

버킷에 S3 복제가 구성된 경우 Amazon S3는 주석을 자동으로 복제합니다. 각 주석은 독립적으로 복제됩니다. 자세한 내용은 Amazon S3는 무엇을 복제합니까? 섹션을 참조하세요.

주석을 복제하려면 복제 IAM 역할의 소스 버킷 권한에 s3:GetObjectVersionAnnotationForReplication을 추가합니다. 자세한 내용은 라이브 복제에 대한 권한 설정 섹션을 참조하세요.

객체 복제를 허용하는 동안 주석 복제를 방지하려면 복제 역할 정책에 s3:ReplicateObjectAnnotation에 대한 거부 문을 추가합니다. 객체 복제는 계속 성공적으로 진행되며 주석 복제만 차단되어 있습니다.

이벤트 알림

Amazon S3는 주석이 생성, 업데이트 또는 삭제될 때 이벤트 알림을 보낼 수 있습니다. 다음과 같은 이벤트 유형을 구성할 수 있습니다.

  • s3:ObjectAnnotation:Put - 주석이 생성되거나 업데이트될 때 전송됩니다.

  • s3:ObjectAnnotation:Delete - 주석이 삭제될 때 전송됩니다.

자세한 내용은 이벤트 알림 유형 및 대상 섹션을 참조하세요.