# 为 Amazon S3 对象命名
<a name="object-keys"></a>

*对象键*（或键名称）唯一标识 Amazon S3 存储桶中的对象。创建对象时，需要指定键名称。例如，在 [Amazon S3 控制台](https://console.aws.amazon.com/s3/home)上，当您选择存储桶时，将显示存储桶中对象的列表。这些名称是*对象键*。

对象键名称由以 UTF-8 编码的 Unicode 字符序列组成，最大长度为 1024 字节或大约 1024 个拉丁字符。在某些区域设置中，单个字符可能需要 2 个字节进行编码。命名对象时，请注意以下几点：
+ 对象键名称区分大小写。
+ 对象键名称包括任何前缀（在控制台中称为*文件夹*）。例如，`Development/Projects.xls` 是位于 `Development` 前缀（或文件夹）内的 `Projects.xls` 对象的完整对象键名称。前缀、分隔符（`/`）和对象名称包含在对象键名称的 1024 字节限制中。有关前缀和文件夹的更多信息，请参阅[选择对象键名称](#object-key-choose)。
+ 在对象键名称中使用某些字符时，可能需要特殊处理。有关更多信息，请参阅 [对象键命名准则](#object-key-guidelines)。

**注意**  
对于[虚拟托管类型请求](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#virtual-hosted-style-access)，不支持值为 `"soap"` 的对象键名称。对于使用 `"soap"` 的对象键名称值，必须改用[路径类型 URL](https://docs.aws.amazon.com//AmazonS3/latest/userguide/VirtualHosting.html#path-style-access)。

## 选择对象键名称
<a name="object-key-choose"></a>

Amazon S3 数据模型是一种扁平结构：您创建一个存储桶，存储桶存储对象。不存在子存储桶或子文件夹的层次结构。但您可以使用键名前缀和分隔符推断逻辑层次结构（如同 Amazon S3 控制台一样）。Amazon S3 控制台支持文件夹的概念。有关如何从 Amazon S3 控制台编辑元数据的更多信息，请参阅[在 Amazon S3 控制台中编辑对象元数据](add-object-metadata.md)。

假设您的存储桶（`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 进行查看和操作。

## 对象键命名准则
<a name="object-key-guidelines"></a>

您可以在对象键名中使用任意 UTF-8 字符。但是，在键名中使用某些字符可能导致一些应用程序和协议出现问题。以下指导原则有助于最大程度符合 DNS、Web 安全字符、XML 分析器和其他 API 的要求。

### 安全字符
<a name="object-key-guidelines-safe-characters"></a>

以下字符集通常可安全地用于键名称：


|  |  | 
| --- |--- |
| 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` 无效。

### 仅限句点的路径分段
<a name="object-key-guidelines-period-only-segments"></a>

对象键包含仅限句点的路径分段（`.` 或 `..`）时，可能会导致将路径分段解释为相对路径引用的应用程序、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 可能以不同的方式处理这些模式

**重要**  
为避免这些问题，建议避免在对象键名称中使用仅限句点的路径分段。出于组织管理的目的，应使用替代命名约定。

### 可能需要特殊处理的字符
<a name="object-key-guidelines-special-handling"></a>

键名称中的以下字符可能需要另外进行代码处理，并且很可能需要以十六进制形式在 URL 中编码或引用。其中部分字符是不可打印的字符，浏览器可能无法处理它们，这也需要特殊处理：
+ 与符号 (`&`) 
+ 美元符号 (`$`) 
+ ASCII 字符范围 00–1F 十六进制（0–31 十进制）和 7F（127 十进制） 
+ @ 符号 (`@`) 
+ 等号 (`=`) 
+ 分号 (`;`) 
+ 正斜杠 (`/`)
+ 冒号 (`:`) 
+ 加号 (`+`) 
+ 空格：大量连续空格可能会在某些情况下丢失（特别是多个空格） 
+ 逗号 (`,`) 
+ 问号 (`?`) 

### 要避免的字符
<a name="object-key-guidelines-avoid-characters"></a>

我们建议不要在键名称中使用以下字符，因为特殊字符的处理方式差异显著，且并非所有应用程序都保持一致：
+ 反斜杠 (`\`) 
+ 左花括号 (`{`) 
+ 不可打印的 ASCII 字符（128–255 十进制字符）
+ 脱字符或音调符号 (`^`) 
+ 右花括号 (`}`) 
+ 百分比字符 (`%`) 
+ 重音符/反勾号 (```) 
+ 右方括号 (`]`) 
+ 引号 (`"`)
+ 大于号 (`>`) 
+ 左方括号 (`[`) 
+ 波浪字符 (`~`) 
+ 小于号 (`<`) 
+ 英镑符号 (`#`) 
+ 竖线或管道符 (`|`) 

### XML 相关的对象键约束
<a name="object-key-xml-related-constraints"></a>

正如[关于尾行处理的 XML 标准](https://www.w3.org/TR/REC-xml/#sec-line-ends)所指定的那样，所有 XML 文本都规范化，这样单个回车符（ASCII 代码 13）和回车符紧跟换行符（ASCII 代码 10，也称为换行字符）将替换为单个换行符。为了确保正确解析 XML 请求中的对象键，当将回车符和其它特殊字符插入 XML 标签时，回车符和[其它特殊字符必须使用其等效的 XML 实体代码进行替换](https://www.w3.org/TR/xml/#syntax)。

以下是此类特殊字符及其等效 XML 实体代码的列表：
+ 撇号 (`'`) 必须替换为 `&apos;`
+ 引号 (`"`) 必须替换为 `&quot;`
+ 与符号 (`&`) 必须替换为 `&amp;`
+ 小于号 (`<`) 必须替换为 `&lt;`
+ 大于号 (`>`) 必须替换为 `&gt;`
+ 回车符 (`\r`) 必须替换为 `&#13;` 或 `&#x0D;`
+ 换行符 (`\n`) 必须替换为 `&#10;` 或 `&#x0A;`

**Example**  
以下示例说明了使用 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>
```

## 对象键排序顺序
<a name="object-key-sort-order"></a>

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`）