为 Amazon S3 对象命名 - Amazon Simple Storage Service
选择对象键名称对象键命名准则

为 Amazon S3 对象命名

对象键（或键名称）唯一标识 Amazon S3 存储桶中的对象。创建对象时，需要指定键名称。例如，在 Amazon S3 控制台上，当您选择存储桶时，将显示存储桶中对象的列表。这些名称是对象键。

对象键名称是 Unicode 字符序列，采用 UTF-8 编码，长度最大为 1024 字节，或 1204 个拉丁字符。在某些区域设置中，单个字符可以等于 2 个字节。命名对象时，请注意以下几点：

  • 对象键名称区分大小写。

  • 对象键名称包括任何前缀（在控制台中称为文件夹）。例如，Development/Projects.xls 是位于 Development 前缀（或文件夹）内的 Projects.xls 对象的完整对象键名称。前缀、分隔符（/）和对象名称包含在对象键名称的 1024 字节限制中。有关前缀和文件夹的更多信息，请参阅选择对象键名称。

  • 在对象键名称中使用某些字符时，可能需要特殊处理。有关更多信息，请参阅 对象键命名准则。

注意

对于虚拟托管类型请求，不支持值为 "soap" 的对象键名称。对于使用 "soap" 的对象键名称值，必须改用路径类型 URL。

选择对象键名称

Amazon S3 数据模型是一种扁平结构：您创建一个存储桶，存储桶存储对象。不存在子存储桶或子文件夹的层次结构。但您可以使用键名前缀和分隔符推断逻辑层次结构（如同 Amazon S3 控制台一样）。Amazon S3 控制台支持文件夹的概念。有关如何从 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 支持存储桶和对象且没有层次结构。但是，通过在对象键名中使用前缀和分隔符，Amazon S3 控制台和 AWS SDK 可以推断层次结构并引入文件夹的概念。

  • Amazon S3 控制台通过创建以文件夹前缀和分隔符值作为键的零字节对象来实现文件夹对象创建。这些文件夹对象不会显示在控制台中。否则，它们的行为与任何其他对象一样，可以通过 REST API、AWS CLI 和 AWS SDK 进行查看和操作。

对象键命名准则

您可以在对象键名中使用任意 UTF-8 字符。但是，在键名中使用某些字符可能导致一些应用程序和协议出现问题。以下指导原则有助于最大程度符合 DNS、Web 安全字符、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 无效。

可能需要特殊处理的字符

键名称中的以下字符可能需要另外进行代码处理，并且很可能需要以十六进制形式在 URL 中编码或引用。其中部分字符是不可打印的字符，浏览器可能无法处理它们，这也需要特殊处理：

  • 与符号 (&)

  • 美元符号 ($)

  • ASCII 字符范围 00–1F 十六进制（0–31 十进制）和 7F（127 十进制）

  • @ 符号 (@)

  • 等号 (=)

  • 分号 (;)

  • 正斜杠 (/)

  • 冒号 (:)

  • 加号 (+)

  • 空格：大量连续空格可能会在某些情况下丢失（特别是多个空格）

  • 逗号 (,)

  • 问号 (?)

要避免的字符

我们建议不要在键名称中使用以下字符，因为特殊字符的处理方式差异显著，且并非所有应用程序都保持一致：

  • 反斜杠 (\)

  • 左花括号 ({)

  • 不可打印的 ASCII 字符（128–255 十进制字符）

  • 脱字符或音调符号 (^)

  • 右花括号 (})

  • 百分比字符 (%)

  • 重音符/反勾号 (`)

  • 右方括号 (])

  • 引号 (")

  • 大于号 (>)

  • 左方括号 ([)

  • 波浪字符 (~)

  • 小于号 (<)

  • 英镑符号 (#)

  • 竖线或管道符 (|)

正如关于尾行处理的 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>