Amazon S3 객체 이름 지정 - Amazon Simple Storage Service
객체 키 이름 선택객체 키 명명 지침객체 키 정렬 순서

Amazon S3 객체 이름 지정

객체 키(또는 키 이름)는 Amazon S3 버킷 내 객체를 고유하게 식별합니다. 객체를 만들 때 키 이름을 지정합니다. 예를 들어, Amazon S3 콘솔에서 버킷을 선택하면 버킷 내 객체의 목록이 표시됩니다. 이러한 이름이 객체 키입니다.

객체 키 이름은 UTF-8로 인코딩된 유니코드 문자 시퀀스로 구성되며, 최대 길이는 1,024바이트 또는 약 1,024개의 라틴 문자입니다. 일부 로캘에서는 인코딩을 위해 단일 문자에 2바이트가 필요할 수 있습니다. 객체의 이름을 지정할 때는 다음 사항에 유의하세요.

  • 객체 키 이름은 대/소문자를 구분합니다.

  • 객체 키 이름에는 접두사(콘솔에서 폴더라고 함)가 포함됩니다. 예를 들어 Development/Projects.xls는 Development 접두사(또는 폴더) 내에 있는 Projects.xls 객체의 전체 객체 키 이름입니다. 접두사, 구분 기호(/) 및 객체 이름은 객체 키 이름의 1,024바이트 제한에 포함됩니다. 접두사 및 폴더에 대한 자세한 정보는 객체 키 이름 선택 섹션을 참조하세요.

  • 특정 문자는 객체 키 이름에 사용될 때 특별한 처리가 필요할 수 있습니다. 자세한 내용은 객체 키 명명 지침 섹션을 참조하세요.

참고

값이 "soap"인 객체 키 이름은 가상 호스팅 방식 요청에 지원되지 않습니다. "soap"이 사용되는 객체 키 이름 값의 경우 경로 스타일 URL을 대신 사용해야 합니다.

객체 키 이름 선택

Amazon S3 데이터 모델은 단순한 구조를 가지고 있습니다. 사용자가 버킷을 만들면 이 버킷에 객체가 저장됩니다. 하위 버킷 또는 하위 폴더의 계층 구조는 없습니다. 그러나 Amazon S3 콘솔과 같이 키 이름 접두사 및 구분 기호를 사용하여 논리적인 계층 구조를 추론할 수 있습니다. Amazon S3 콘솔은 폴더 개념을 지원합니다. Amazon S3 콘솔에서 메타데이터를 편집하는 방법에 대한 자세한 내용은 Amazon S3 콘솔에서 객체 메타데이터 편집 섹션을 참조하십시오.

버킷(admin-created)에 다음과 같은 객체 키를 가진 4개의 객체가 있다고 가정해 보겠습니다.

Development/Projects.xls

Finance/statement1.pdf

Private/taxdocument.pdf

s3-dg.pdf

콘솔은 키 이름 접두사(Development/, Finance/, Private/) 및 구분 기호(/)를 사용하여 폴더 구조를 표현합니다. s3-dg.pdf 키에는 슬래시로 구분된 접두사가 없으므로 해당 객체는 버킷의 루트 수준에 곧바로 표시됩니다. Development/ 폴더를 열면 그 안에 Projects.xlsx 객체가 표시됩니다.

  • Amazon S3는 버킷과 객체를 지원하며 계층 구조가 없습니다. 다만 객체 키 이름에 접두사와 구분 기호를 사용하면 Amazon S3 콘솔과 AWS SDK에서 계층 구조를 추론하고 폴더 개념을 도입할 수 있습니다.

  • Amazon S3 콘솔은 폴더 접두사 및 구분 기호 값을 키로 사용하여 0바이트 객체를 만들어 폴더 객체 생성을 구현합니다. 이러한 폴더 객체는 콘솔에 표시되지 않습니다. 그렇지 않으면 다른 객체처럼 동작하며 REST API, AWS CLI 및 AWS SDK를 통해 볼 수 있고 조작도 할 수 있습니다.

객체 키 명명 지침

객체 키 이름에 임의의 UTF-8 문자를 사용할 수 있습니다. 하지만 특정 문자는 키 이름에 사용하면 일부 애플리케이션 또는 프로토콜에 문제가 발생할 수도 있습니다. 다음 지침에 따르면 DNS, 웹 안전 문자, XML 파싱 프로그램 및 기타 API의 호환성을 극대화할 수 있습니다.

사용 가능 문자

다음 문자 조합은 일반적으로 키 이름으로 사용해도 문제가 되지 않습니다.

Alphanumeric characters

  • 0~9

  • a-z

  • A-Z
Special characters

  • 느낌표(!)

  • 하이픈(-)

  • 밑줄(_)

  • 마침표(.)

  • 별표(*)

  • 작은따옴표(')

  • 여는 괄호(()

  • 닫는 괄호())

다음은 유효한 객체 키 이름의 예입니다.

  • 4my-organization

  • my.great_photos-2014/jan/myvacation.jpg

  • videos/2014/birthday/video1.wmv

참고

Amazon S3 콘솔을 사용하여 키 이름이 마침표(.)로 끝나는 객체를 다운로드하는 경우, 다운로드한 객체의 키 이름에서 마침표가 제거됩니다. 다운로드한 객체 이름 끝에 마침표를 유지하려면 AWS Command Line Interface(AWS CLI), AWS SDK 또는 Amazon S3 REST API를 사용해야 합니다.

또한 다음 접두사 제한 사항을 숙지해야 합니다.

  • 접두사가 ./인 객체는 AWS CLI, AWS SDK 또는 REST API를 사용하여 업로드하거나 다운로드해야 합니다. Amazon S3 콘솔을 사용하여 이러한 객체를 업로드할 수 없습니다.

  • 상대 경로 요소(예: ../)가 포함된 객체 키는 왼쪽에서 오른쪽으로 구문 분석할 때 상대 경로 세그먼트의 누적 수가 상대 경로가 아닌 요소의 수를 초과하지 않는 경우 유효합니다. 이 규칙은 Amazon S3 콘솔, Amazon S3 REST API, AWS CLI 및 AWS 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 - 기간들이 독립 실행형이 아닌 파일 이름의 일부

애플리케이션이 기간 전용 세그먼트가 있는 객체 키를 처리할 때 다음과 같은 동작 영향이 발생할 수 있습니다.

  • 경로 정규화 - 많은 시스템이 자동으로 . 및 .. 참조를 확인하므로 유효 경로가 변경될 수 있습니다(예: folder/./file.txt가 folder/file.txt로 됨).

  • 액세스 문제 - 경로 해결 차이로 인해 애플리케이션이 객체를 찾지 못할 수 있습니다.

  • 일관되지 않은 동작 - 서로 다른 도구와 SDK는 이러한 패턴을 다르게 처리할 수 있습니다.

중요

이러한 문제를 방지하려면 객체 키 이름에 기간 전용 경로 세그먼트를 사용하지 않는 것이 좋습니다. 조직의 목적을 위해 대체 명명 규칙을 사용합니다.

특별한 처리가 필요한 문자

키 이름에서 다음 문자는 추가 코드 처리가 필요할 수도 있으며 URL 인코딩되거나 HEX로 참조해야 할 가능성이 큽니다. 이러한 문자 중 일부는 인쇄가 되지 않으며 브라우저에서 처리하지 못할 수 있으므로 특별한 처리가 필요합니다.

  • 앰퍼샌드(&)

  • 달러 기호($)

  • ASCII 문자 범위 00-1F(16진수, 10진수: 0~31) 및 7F(10진수: 127)

  • At 기호(@)

  • 같음 기호(=)

  • 세미콜론(;)

  • 슬래시(/)

  • 콜론(:)

  • 더하기 기호(+)

  • 공백 – 경우에 따라 많은 공백이 연달아 사라질 수 있음(특히 공백이 여러 개 있는 경우)

  • 쉼표(,)

  • 물음표(?)

피해야 하는 문자

모든 애플리케이션 간에 일관되지 않은 상당한 특수 문자 처리로 인해 다음과 같은 문자는 키 이름에 사용하지 않는 것이 좋습니다.

  • 백슬래시(\)

  • 왼쪽 중괄호({)

  • 인쇄되지 않는 ASCII 문자(128~255 사이의 10진수)

  • 캐럿 또는 곡절(^)

  • 오른쪽 중괄호(})

  • 백분율 문자(%)

  • 억음 부호(`)

  • 오른쪽 대괄호(])

  • 따옴표(")

  • 보다 큼 기호(>)

  • 왼쪽 대괄호([)

  • 물결표(~)

  • 보다 작음 기호(<)

  • 파운드 기호(#)

  • 세로 막대 또는 파이프(|)

줄 끝 처리의 XML 표준에서 지정한 대로 모든 XML 텍스트는 단일 캐리지 리턴(ASCII 코드 13) 및 캐리지 리턴 바로 뒤에 오는 줄 바꿈(ASCII 코드 10), 즉 새 줄 바꿈 문자가 단일 줄 바꿈 문자로 대체되도록 정규화됩니다. XML 요청에서 객체 키를 올바르게 구문 분석하려면 캐리지 리턴 및 기타 특수 문자가 XML 태그 내에 삽입될 때 해당 XML 엔터티 코드로 대체되어야 합니다.

다음은 이러한 특수 문자 및 대응하는 XML 엔터티 코드의 목록입니다.

  • 아포스트로피(')를 &apos;로 바꿔야 함

  • 따옴표(")를 &quot;로 바꿔야 함

  • 앰퍼샌드(&)를 &amp;로 바꿔야 함

  • 보다 작음 기호(<)를 &lt;로 바꿔야 함

  • 보다 큼 기호(>)를 &gt;로 바꿔야 함

  • 캐리지 리턴(\r)을 &#13; 또는 &#x0D;로 바꿔야 함

  • 줄 바꿈(\n)을 &#10; 또는 &#x0A;로 바꿔야 함

다음 예에서는 캐리지 리턴의 대체물로 XML 엔터티 코드를 사용하는 방법을 보여줍니다. 이 DeleteObjects 요청은 key 파라미터 /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>

객체 키 정렬 순서

Amazon S3는 접두사를 포함한 객체 키를 UTF-8 인코딩 바이트 값을 기준으로 사전순으로 정렬합니다.

ASCII 문자는 다음 순서로 정렬됩니다.

  • 특수 문자(예: !, /)

  • 대문자(A–Z)

  • 소문자(a–z)

ASCII가 아닌 문자(예: é, 中文)는 멀티바이트 UTF-8 시퀀스로 인코딩되며, 바이트 값이 높기 때문에 일반적으로 ASCII 문자 뒤에 정렬됩니다(예: é의 경우 0xC3, 中의 경우 0xE4).

예를 들어 apple/, Apple/, éclair/, 中 文/ 등 접두사는 다음과 같이 정렬됩니다.

1. Apple/(0x41로 시작)

2. apple/(0x61로 시작)

3. éclair/(0xC3 0xA9로 시작)

4. 中 文/(0xE4 0xB8 0xAD 0xE6 0x96 0x87로 시작)