Amazon S3 객체 이름 짓기

Amazon S3 객체 이름 짓기

객체 키(또는 키 이름)는 Amazon S3 버킷에서 객체를 고유하게 식별해요. 객체를 만들 때 키 이름을 지정해요. 예를 들어 Amazon S3 콘솔에서 버킷을 선택하면 버킷 안 객체 목록이 나타나는데, 이 이름들이 곧 객체 키예요.

객체 키 이름은 UTF-8로 인코딩된 일련의 Unicode 문자로 구성되며, 최대 길이는 1,024바이트(약 1,024개의 라틴 문자)예요. 일부 로케일에서는 한 문자가 2바이트로 인코딩될 수도 있어요. 객체 이름을 지을 때 다음 사항을 유의하세요.

• 객체 키 이름은 대소문자를 구분해요.
• 객체 키 이름에는 모든 접두사(콘솔에서 폴더라고 함)가 포함돼요. 예를 들어 Development/Projects.xls는 Development 접두사(또는 폴더) 안에 있는 Projects.xls 객체의 전체 키 이름이에요. 접두사, 구분자(/), 객체 이름이 모두 객체 키 이름의 1,024바이트 제한에 포함돼요.
• 일부 문자는 객체 키 이름에 사용할 때 특별한 처리가 필요할 수 있어요.

참고: 값이 "soap"인 객체 키 이름은 가상 호스트 스타일 요청에서 지원되지 않아요. "soap"이 사용된 키 이름은 경로 스타일 URL을 사용해야 해요.

출처: 문서

본문

객체 키 이름 선택 (Choosing object key names)

Amazon S3 데이터 모델은 평면 구조예요. 버킷을 만들고 버킷이 객체를 저장하며, 하위 버킷이나 하위 폴더의 계층은 없어요. 하지만 키 이름 접두사와 구분자를 사용해 논리적 계층을 유추할 수 있어요(Amazon S3 콘솔이 그렇게 해요). 콘솔은 폴더 개념을 지원해요.

예를 들어 내 버킷(admin-created)에 다음 네 개의 객체 키가 있다고 가정해요:

Development/Projects.xls
Finance/statement1.pdf
Private/taxdocument.pdf
s3-dg.pdf

콘솔은 키 이름 접두사(Development/, Finance/, Private/)와 구분자(/)를 사용해 폴더 구조를 보여줘요. s3-dg.pdf 키는 슬래시 구분 접두사가 없으므로 버킷의 루트 수준에 직접 표시돼요. Development/ 폴더를 열면 Projects.xlsx 객체가 보여요.

• Amazon S3는 버킷과 객체를 지원하며 계층이 없어요. 하지만 객체 키 이름에 접두사와 구분자를 사용하면 콘솔과 AWS SDK가 계층을 유추하고 폴더 개념을 도입할 수 있어요.
• Amazon S3 콘솔은 폴더 접두사와 구분자 값을 키로 하는 0바이트 객체를 만들어 폴더 객체 생성을 구현해요. 이 폴더 객체는 콘솔에 표시되지 않지만, 다른 객체처럼 동작하며 REST API, AWS CLI, AWS SDK로 보고 조작할 수 있어요.

객체 키 명명 가이드라인

객체 키 이름에 어떤 UTF-8 문자든 사용할 수 있어요. 하지만 일부 문자는 특정 애플리케이션과 프로토콜에서 문제를 일으킬 수 있어요.

안전한 문자 (Safe characters) — 키 이름 사용에 일반적으로 안전한 문자 세트:

유효한 객체 키 이름 예시:

• 4my-organization
• my.great_photos-2014/jan/myvacation.jpg
• videos/2014/birthday/video1.wmv

참고: Amazon S3 콘솔로 마침표(.)로 끝나는 키 이름의 객체를 다운로드하면 다운로드된 객체 키 이름 끝의 마침표가 제거돼요. 다운로드한 객체의 키 이름 끝에 마침표를 유지하려면 AWS CLI, AWS SDK, 또는 Amazon S3 REST API를 사용해야 해요.

추가 접두사 제한 사항:

• ./ 접두사의 객체는 AWS CLI, AWS SDK, REST API로만 업로드·다운로드할 수 있어요. 콘솔로는 업로드할 수 없어요.
• 상대 경로 요소(예: ../)를 포함하는 객체 키는, 왼쪽에서 오른쪽으로 파싱할 때 상대 경로 세그먼트의 누적 개수가 만난 비상대 경로 요소 수를 초과하지 않으면 유효해요. 이 규칙은 콘솔, REST API, AWS CLI, SDK의 모든 요청에 적용돼요. 예: videos/2014/../../video1.wmv는 유효하지만, videos/../../video1.wmv와 videos/../../2014/video1.wmv는 유효하지 않아요.

마침표만 있는 경로 세그먼트 — 마침표만 있는 경로 세그먼트(. 또는 ..)를 포함하는 객체 키는 이를 상대 경로 참조로 해석하는 애플리케이션, SDK, 도구에서 처리될 때 예상치 못한 동작을 일으킬 수 있어요.

문제를 일으킬 수 있는 패턴:

• folder/./file.txt – 현재 디렉터리 참조 포함
• folder/../file.txt – 부모 디렉터리 참조 포함
• ./file.txt – 현재 디렉터리 참조로 시작
• ../file.txt – 부모 디렉터리 참조로 시작

정상적으로 작동하는 패턴:

• folder/.hidden/file.txt – 마침표가 파일 이름의 일부
• folder/..backup/file.txt – 마침표가 파일 이름의 일부

마침표만 있는 세그먼트의 영향 — 많은 시스템이 .와 .. 참조를 자동으로 해석해 실제 경로를 바꾸거나, 애플리케이션이 경로 해석 차이로 객체를 찾지 못하거나, 도구·SDK마다 다르게 처리하는 등 문제가 생길 수 있어요.

중요: 이런 문제를 피하려면 객체 키 이름에 마침표만 있는 경로 세그먼트를 사용하지 않는 것을 권장해요. 조직 목적에는 다른 명명 규칙을 사용하세요.

특별 처리가 필요한 문자 — 키 이름의 다음 문자는 추가 코드 처리가 필요할 수 있고 대부분 URL 인코딩하거나 HEX로 참조해야 해요. 일부는 브라우저가 처리하지 못할 수 있는 비출력 문자예요:

• 앰퍼샌드(&)
• 달러 기호($)
• ASCII 00–1F hex(0–31진수) 및 7F(127진수) 범위
• @ 기호(@)
• 등호(=)
• 세미콜론(;)
• 슬래시(/)
• 콜론(:)
• 더하기(+)
• 공백 – 일부 경우(특히 여러 공백) 유효한 공백 시퀀스가 손실될 수 있음
• 쉼표(,)
• 물음표(?)

피해야 할 문자 — 모든 애플리케이션에서 일관되지 않은 상당한 특수 문자 처리 때문에 키 이름에 다음 문자를 사용하지 않는 것을 권장해요:

• 백슬래시(\)
• 왼쪽 중괄호({)
• 비출력 ASCII 문자(128–255)
• 캐럿(^)
• 오른쪽 중괄호(})
• 퍼센트(%)
• 백틱( )
• 오른쪽 대괄호(])
• 큰따옴표(")
• 보다 큼(>)
• 왼쪽 대괄호([)
• 틸드(~)
• 보다 작음(<)
• 파운드(#)
• 세로 막대(|)

XML 관련 객체 키 제약 — XML 표준의 줄 끝 처리에 따라 모든 XML 텍스트는 단일 캐리지 리턴(ASCII 13)과 캐리지 리턴 뒤에 줄 바꿈(ASCII 10)이 단일 줄 바꿈 문자로 대체되도록 정규화돼요. XML 요청에서 객체 키를 올바르게 파싱하려면 캐리지 리턴과 기타 특수 문자를 XML 태그 안에 삽입할 때 등가 XML 엔티티 코드로 바꿔야 해요.

캐리지 리턴 대신 XML 엔티티 코드를 사용하는 예시. 이 DeleteObjects 요청은 키 파라미터 /some/prefix/objectwith\rcarriagereturn(여기서 \r은 캐리지 리턴)인 객체를 삭제해요.

<Delete xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Object>
    <Key>/some/prefix/objectwith&#13;carriagereturn</Key>
  </Object>
</Delete>

객체 키 정렬 순서 (Object key sort order)

Amazon S3는 접두사를 포함한 객체 키를 UTF-8 인코딩 바이트 값 기준으로 사전식으로 정렬해요.

ASCII 문자는 다음 순서로 정렬돼요:

• 특수 문자(예: !, /)
• 대문자(A–Z)
• 소문자(a–z)

비 ASCII 문자(예: é, 中文)는 멀티바이트 UTF-8 시퀀스로 인코딩되며 더 높은 바이트 값(예: é는 0xC3, 中은 0xE4) 때문에 일반적으로 ASCII 문자 뒤에 정렬돼요.

예를 들어 apple/, Apple/, éclair/, 中文/ 접두사는 다음과 같이 정렬돼요:

1. Apple/ (0x41로 시작)
2. apple/ (0x61로 시작)
3. éclair/ (0xC3 0xA9로 시작)
4. 中文/ (0xE4 0xB8 0xAD 0xE6 0x96 0x87로 시작)

더 알아보기 (Learn more)

• Amazon S3 객체 개요
• 객체 메타데이터 작업
• 객체에 주석 달기