# POST Object
<a name="RESTObjectPOST"></a>

## 说明
<a name="RESTObjectPOST-description"></a>

`POST` 操作使用 HTML 表单将对象添加到指定的存储桶。`POST` 是 `PUT` 的另一种形式，它支持基于浏览器的上传，以作为将对象放入存储桶的一种方式。通过 HTTP 标头传递给 `PUT` 的参数将作为表单字段传递到以分段/表单数据编码的消息正文中的 `POST`。要向存储桶添加对象，您必须对存储桶拥有 `WRITE` 访问权限。Amazon S3 从不存储不完整的对象。如果您收到成功的响应，则可以确信已存储整个对象。

Amazon S3 是一个分布式系统。除非您为存储桶启用了版本控制，否则，如果 Amazon S3 同时收到针对同一对象的多个写入请求，则只存储写入的对象的最后一个版本。

要确保数据在穿过网络时不会损坏，请使用 `Content-MD5` 表单字段。当您使用此表单字段时，Amazon S3 会根据提供的 MD5 值检查对象。如果它们不匹配，Amazon S3 将返回错误。此外，您可以在将对象发布到 Amazon S3 时计算 MD5 值，并将返回的 `ETag` 与计算出的 MD5 值进行比较。ETag 仅反映对于对象内容的更改，而不反映对于其元数据的更改。

**注意**  
要将您的应用程序配置为在发送请求正文之前发送请求标头，请使用 HTTP 状态代码 100（继续）。对于 `POST` 操作，使用此状态代码有助于您避免在消息根据标头遭拒绝时（例如，由于身份验证失败或重定向）发送消息正文。有关 HTTP 状态代码 100（继续）的更多信息，请参阅 [http://www.ietf.org/rfc/rfc2616.txt](http://www.ietf.org/rfc/rfc2616.txt) 的第 8.2.3 节。

Amazon S3 会自动加密上传到 S3 存储桶的所有新对象。已上传对象的加密设置取决于目标存储桶的默认加密配置。默认情况下，所有存储桶都有默认加密配置，该配置使用具有 Amazon S3 托管式密钥的服务器端加密（SSE-S3）。

如果目标存储桶的加密配置使用具有 Amazon Key Management Service（Amazon KMS）密钥的服务器端加密（SSE-KMS）、具有 Amazon KMS 密钥的双层服务器端加密（DSSE-KMS）或采用客户提供的加密密钥（SSE-C），则 Amazon S3 使用相应的 KMS 密钥或客户提供的密钥来加密已上传的对象。上传对象时，如果您想更改已上传对象的加密设置，可以指定服务器端加密的类型。您可以配置 SSE-S3、SSE-KMS、DSSE-KMS 或 SSE-C。有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[使用服务器端加密保护数据](https://docs.amazonaws.cn/AmazonS3/latest/userguide/serv-side-encryption.html)。

**重要**  
构造请求时，请确保 `file` 字段是表单中的最后一个字段。

## 请求
<a name="RESTObjectPOST-requests"></a>

### 语法
<a name="RESTObjectPOST-requests-syntax"></a>

```
 1. POST / HTTP/1.1
 2. Host: {{destinationBucket}}.s3.amazonaws.com
 3. User-Agent: {{browser_data}}
 4. Accept: {{file_types}}
 5. Accept-Language: {{Regions}}
 6. Accept-Encoding: {{encoding}}
 7. Accept-Charset: {{character_set}}
 8. Keep-Alive: 300
 9. Connection: keep-alive
10. Content-Type: multipart/form-data; boundary=9431149156168
11. Content-Length: {{length}}
12. 
13. --9431149156168
14. Content-Disposition: form-data; name="key"
15. 
16. acl
17. --9431149156168
18. Content-Disposition: form-data; name="tagging"
19. 
20. <Tagging><TagSet><Tag><Key>{{Tag Name}}</Key><Value>{{Tag Value}}</Value></Tag></TagSet></Tagging>
21. --9431149156168
22. Content-Disposition: form-data; name="success_action_redirect"
23. 
24. success_redirect
25. --9431149156168
26. Content-Disposition: form-data; name="Content-Type"
27. 
28. content_type
29. --9431149156168
30. Content-Disposition: form-data; name="x-amz-meta-uuid"
31. 
32. uuid
33. --9431149156168
34. Content-Disposition: form-data; name="x-amz-meta-tag"
35. 
36. metadata
37. --9431149156168
38. Content-Disposition: form-data; name="AWSAccessKeyId"
39. 
40. access-key-id
41. --9431149156168
42. Content-Disposition: form-data; name="Policy"
43. 
44. encoded_policy
45. --9431149156168
46. Content-Disposition: form-data; name="Signature"
47. 
48. signature=
49. --9431149156168
50. Content-Disposition: form-data; name="file"; filename="{{MyFilename.jpg}}"
51. Content-Type: image/jpeg
52. 
53. file_content
54. --9431149156168
55. Content-Disposition: form-data; name="submit"
56. 
57. Upload to Amazon S3
58. --9431149156168--
```

### 请求参数
<a name="RESTObjectPOST-requests-request-parameters"></a>

此操作的实施不使用请求参数。

### 表单字段
<a name="RESTObjectPOST-requests-form-fields"></a>

此操作可以使用以下表单字段。


| 名称 | 描述 | 必需 | 
| --- | --- | --- | 
| AWSAccessKeyId | 存储桶拥有者的 Amazon 访问密钥 ID，该拥有者向匿名用户授予对满足策略中一组约束的请求的访问权限。<br />类型：字符串<br />默认值：无<br />约束：如果策略文档随请求一起提供，则为必需项。 | 有条件 | 
| acl | 指定的 Amazon S3 访问控制列表（ACL）。如果指定的 ACL 无效，将生成错误。有关 ACL 的更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[访问控制列表（ACL）概述](https://docs.amazonaws.cn/AmazonS3/latest/userguide/acl-overview.html)。<br />类型：字符串<br />默认值：private<br /> 有效值：`private \| public-read \| public-read-write \| aws-exec-read \| authenticated-read \| bucket-owner-read \| bucket-owner-full-control ` | 否 | 
| Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires | 特定于 REST 的标头。有关更多信息，请参阅 [PutObject](https://docs.amazonaws.cn/AmazonS3/latest/API/API_PutObject.html)。<br />类型：字符串<br />默认值：无 | 否 | 
| file | 文件或文本内容。<br />文件或文本内容必须是表单中的最后一个字段。<br />您一次仅能上传一个文件。<br />类型：文件或文本内容<br />默认值：无 | 是 | 
| key | 已上传的键的名称。<br />要使用由用户提供的文件名，请使用 `${filename}` 变量。例如，如果名为 Mary 的用户上传了文件 `example.jpg`，而您指定了 `/user/mary/${filename}`，则键名称为 `/user/mary/example.jpg`。<br />有关更多信息，请参阅 *Amazon Simple Storage Service 用户指南*中的[对象键和元数据](https://docs.amazonaws.cn/AmazonS3/latest/userguide/UsingMetadata.html)。<br />类型：字符串<br />默认值：无 | 是 | 
| policy | 描述请求中允许的内容的安全策略。不带安全策略的请求被认为是匿名的，只在公共可写的存储桶上有效。有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的 [HTML 表单](https://docs.amazonaws.cn/AmazonS3/latest/userguide/HTTPPOSTForms.html)和[上传示例](https://docs.amazonaws.cn/AmazonS3/latest/userguide/HTTPPOSTExamples.html)。<br />类型：字符串<br />默认值：无<br />约束：如果存储桶不是可公开写入的，则需要安全策略。 | 有条件 | 
| success\_action\_redirect, redirect | 上传成功后客户端重定向到的 URL。<br />如果未指定 `success_action_redirect`，Amazon S3 将返回在 `success_action_status` 字段中指定的空文档类型。<br />如果 Amazon S3 无法解释该 URL，则其行为就像该字段不存在一样。<br />如果上传失败，Amazon S3 将显示错误并且不会将用户重定向到某个 URL。<br />类型：字符串<br />默认值：无 已弃用 `redirect` 字段名称，并且以后将移除对 `redirect` 字段名称的支持。  | 否 | 
| success\_action\_status | 如果您未指定 `success_action_redirect`，则上传成功后，状态代码将返回给客户端。<br />此字段接受值 `200`、`201` 或 `204`（默认值）。<br />如果值设置为 `200` 或 `204`，Amazon S3 将返回一个空文档和一个 200 或 204 状态代码。<br />如果值设置为 `201`，Amazon S3 将返回一个 XML 文档和一个 201 状态代码。<br />如果没有设置值或设置为无效的值，Amazon S3 将返回一个空文档和一个 204 状态代码。<br />类型：字符串<br />默认值：无 | 否 | 
| tagging | 要添加到对象的指定标签集。要添加标签，请使用以下编码方案。<br /> <pre><Tagging><br />  <TagSet><br />    <Tag><br />      <Key>{{TagName}}</Key><br />      <Value>{{TagValue}}</Value><br />    </Tag><br />    ...<br />  </TagSet><br /></Tagging></pre><br />有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[为对象添加标签](https://docs.amazonaws.cn/AmazonS3/latest/userguide/object-tagging.html)。<br />类型：字符串<br />默认值：无 | 否 | 
| x-amz-storage-class | 要用于存储对象的存储类别。如果您未指定存储类别，Amazon S3 将使用默认存储类别 `STANDARD`。Amazon S3 支持其它存储类别。有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[存储类别](https://docs.amazonaws.cn/AmazonS3/latest/userguide/storage-class-intro.html)。<br />类型：字符串<br />默认：`STANDARD`<br />有效值： `REDUCED_REDUNDANCY`\| `EXPRESS_ONEZONE` \| `DEEP_ARCHIVE` \| `GLACIER` \| `GLACIER_IR` \| `INTELLIGENT_TIERING` \| `ONEZONE_IA` \| `STANDARD` \| `STANDARD_IA`  | 否 | 
| x-amz-meta-\* | 以此前缀开头的标头是用户定义的元数据。每个元数据均以一组键-值对的形式存储和返回。Amazon S3 不验证或解释用户定义的元数据。有关更多信息，请参阅 [PutObject](https://docs.amazonaws.cn/AmazonS3/latest/API/API_PutObject.html)。<br />类型：字符串<br />默认值：无 | 否 | 
| x-amz-security-token | Amazon DevPay 安全令牌。<br />使用 Amazon DevPay 的每个请求都需要两个 `x-amz-security-token` 表单字段：一个用于产品令牌，一个用于用户令牌。<br />类型：字符串<br />默认值：无 | 否 | 
| x-amz-signature | （Amazon 签名版本 4）安全策略的 HMAC-SHA256 哈希值。<br />类型：字符串<br />默认值：无 | 有条件 | 
| x-amz-website-redirect-location  | 如果存储桶配置为网站，则此字段会将对此对象的请求重定向到同一存储桶中的另一个对象，或者重定向到外部 URL。Amazon S3 将此标头的值存储在对象元数据中。有关对象元数据的信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[对象键和元数据](https://docs.amazonaws.cn/AmazonS3/latest/userguide/UsingMetadata.html)。<br />在以下示例中，请求标头将重定向设置为同一存储桶中的对象（`anotherPage.html`）：<br />`x-amz-website-redirect-location: /anotherPage.html`<br />在以下示例中，请求标头将对象重定向设置为另一个网站：<br />`x-amz-website-redirect-location: http://www.example.com/`<br />有关 Amazon S3 中的网站托管的更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[在 Amazon S3 上托管网站](https://docs.amazonaws.cn/AmazonS3/latest/userguide/WebsiteHosting.html)和[如何配置网站页面重定向](https://docs.amazonaws.cn/AmazonS3/latest/userguide/how-to-page-redirect.html)。<br />类型：字符串<br />默认值：无<br />约束：该值必须以 `/`、`http://` 或 `https://` 为前缀。值的长度限制为 2 KB。 |  否  | 

#### 其它校验和请求表单字段
<a name="post-object-additional-checksums"></a>

上传对象时，您可以指定要用于验证数据完整性的各种校验和。您可以指定一个额外的校验和算法供 Amazon S3 使用。有关其它校验和值的更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[检查对象完整性](https://docs.amazonaws.cn/AmazonS3/latest/userguide/checking-object-integrity.html)。


|  名称  |  描述  |  必填  | 
| --- | --- | --- | 
|  x-amz-checksum-algorithm  | 表示用于为对象创建校验和的算法。如果指定了值，则必须包括匹配的校验和标头。否则，您的请求将生成 400 错误。<br />可能的值包括 `CRC32`、`CRC32C`、`SHA1` 和 `SHA256`。 | 否 | 
|  x-amz-checksum-crc32  | 指定对象的 base64 编码的 32 位 CRC32 校验和。<br />如果 `x-amz-checksum-algorithm` 的值为 `CRC32`，则此参数是必需的。 | 有条件 | 
|  x-amz-checksum-crc32c  | 指定对象的 base64 编码的 32 位 CRC32C 校验和。<br />如果 `x-amz-checksum-algorithm` 的值为 `CRC32C`，则此参数是必需的。 | 有条件 | 
|  x-amz-checksum-sha1  | 指定对象的 base64 编码的 160 位 SHA-1 摘要。<br />如果 `x-amz-checksum-algorithm` 的值为 `SHA1`，则此参数是必需的。 | 有条件 | 
|  x-amz-checksum-sha256  | 指定对象的 base64 编码的 256 位 SHA-256 摘要。<br />如果 `x-amz-checksum-algorithm` 的值为 `SHA256`，则此参数是必需的。 | 有条件 | 

#### 特定于服务器端加密的请求表单字段
<a name="post-object-sse-specific-request-headers"></a>

服务器端加密是静态数据加密。Amazon S3 在将数据写入 Amazon 数据中心的磁盘时对数据进行加密，并在您访问数据时对其进行解密。上传对象时，您可以指定您希望 Amazon S3 用于加密对象的服务器端加密的类型。

服务器端加密有四种类型：
+ **具有 Amazon S3 托管式密钥的服务器端加密（SSE-S3）**：从 2022 年 5 月开始，所有 Amazon S3 存储桶都默认配置了加密。默认的服务器端加密选项是使用 SSE-S3。每个对象都使用唯一的密钥来进行加密。作为额外的保护措施，SSE-S3 使用定期轮换的根密钥加密密钥本身。SSE-S3 使用可用的最强数据块密码之一 [即 256 位高级加密标准（AES-256）] 来加密您的数据。
+ **具有 Amazon KMS 密钥的服务器端加密（SSE-KMS）**：通过将 Amazon KMS 服务与 Amazon S3 集成来提供 SSE-KMS。使用 Amazon KMS，您可以更好地控制您的密钥。例如，您可以查看单独的密钥、编辑控制策略以及遵循 Amazon CloudTrail 中的密钥。此外，您还可以创建和管理客户自主管理型密钥，或者使用对于您、服务和区域为唯一的 Amazon 托管式密钥。
+ **具有 Amazon KMS 密钥的双层服务器端加密（DSSE-KMS）**：具有 Amazon KMS keys的双层服务器端加密（DSSE-KMS）与 SSE-KMS 类似，但前者应用的是两层单独的对象级加密，而不是一层。
+ **具有客户提供的密钥的服务器端加密（SSE-C）**：使用 SSE-C，您管理加密密钥，而 Amazon S3 管理加密（在它对磁盘进行写入时）和解密（在您访问您的对象时）。
**注意**  
在对通用存储桶阻止了具有客户提供密钥的服务器端加密（SSE-C）的情况下，如果在向存储桶写入新数据时指定 SSE-C 请求标头，您将收到“HTTP 403 拒绝访问”错误。有关更多信息，请参阅[对通用存储桶阻止或取消阻止 SSE-C](https://docs.amazonaws.cn/AmazonS3/latest/userguide/blocking-unblocking-s3-c-encryption-gpb.html)。

有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[使用服务器端加密保护数据](https://docs.amazonaws.cn/AmazonS3/latest/userguide/serv-side-encryption.html)。

根据您要使用的服务器端加密类型，指定以下表单字段。
+ **使用 SSE-S3、SSE-KMS 或 DSSE-KMS**：如果您要使用这些类型的服务器端加密，请在请求中指定以下表单字段。    
[See the AWS documentation website for more details](http://docs.amazonaws.cn/AmazonS3/latest/developerguide/RESTObjectPOST.html)
**注意**  
如果您指定 `x-amz-server-side-encryption:aws:kms` 或 `x-amz-server-side-encryption:aws:kms:dsse`，但未提供 `x-amz-server-side-encryption-aws-kms-key-id`，Amazon S3 将使用 Amazon 托管式密钥 (`aws/S3`) 来保护数据。
+ **使用 SSE-C**：如果您想管理自己的加密密钥，则必须在请求中提供以下所有表单字段。
**注意**  
如果您使用 SSE-C，Amazon S3 在响应中返回的 `ETag` 值不是对象的 MD5。    
[See the AWS documentation website for more details](http://docs.amazonaws.cn/AmazonS3/latest/developerguide/RESTObjectPOST.html)

### 响应
<a name="RESTObjectPOST-requests-responses"></a>

#### 响应标头
<a name="RESTObjectPOST-requests-responses-response-headers"></a>

除了所有响应通用的响应标头之外，此操作的实现还可以包括以下响应标头。有关更多信息，请参阅[通用响应标头](RESTCommonResponseHeaders.md)。


|  名称  |  描述  | 
| --- | --- | 
|  x-amz-checksum-crc32  | 对象的 base64 编码的 32 位 CRC32 校验和。<br />类型：字符串 | 
|  x-amz-checksum-crc32c  | 对象的 base64 编码的 32 位 CRC32C 校验和。<br />类型：字符串 | 
|  x-amz-checksum-sha1  | 对象的 base64 编码的 160 位 SHA-1 摘要。<br />类型：字符串 | 
|  x-amz-checksum-sha256  | 对象的 base64 编码的 256 位 SHA-256 摘要。<br />类型：字符串 | 
|  x-amz-expiration  | 如果在存储桶的生命周期配置中为对象配置了 `Expiration` 操作，则 Amazon S3 会返回此标头。 标头值包括一个 `expiry-date` 组件和一个 URL 编码的 `rule-id` 组件。 对于启用版本控制的存储桶，此标头仅适用于当前版本。Amazon S3 不提供标头来指示非当前版本何时符合永久删除条件。有关更多信息，请参阅 [PutBucketLifecycleConfiguration](https://docs.amazonaws.cn/AmazonS3/latest/API/API_PutBucketLifecycleConfiguration.html)。<br />类型：字符串 | 
|  success\_action\_redirect, redirect  | 上传成功后客户端重定向到的 URL。<br />类型：字符串<br />原级：PostResponse | 
|  x-amz-server-side-encryption  | 在 Amazon S3 中存储此对象时使用的服务器端加密算法（例如 `AES256`、`aws:kms`、`aws:kms:dsse`）。<br />类型：字符串 | 
|  x-amz-server-side-encryption-aws-kms-key-id  | 如果 `x-amz-server-side-encryption` 标头的有效值为 `aws:kms`，则此标头指定用于加密对象的 KMS 密钥的 ID。<br />类型：字符串 | 
|  x-amz-server-side-encryption-bucket-key-enabled  | 如果 `x-amz-server-side-encryption` 的有效值为 `aws:kms`，则此标头表示是否使用 S3 存储桶密钥通过 SSE-KMS 为对象加密。如果此标头设置为 `true`，则对象会将 S3 存储桶密钥与 SSE-KMS 结合使用。<br />类型：布尔值 | 
|  x-amz-server-side-encryption-customer-algorithm  | 如果请求了 SSE-C，则响应将包含此标头，用于确认所使用的加密算法。<br />类型：字符串<br />有效值：`AES256` | 
|  x-amz-server-side-encryption-customer-key-MD5  | 如果请求了 SSE-C，则响应将包含此标头，用于验证客户提供的加密密钥的往返消息完整性。<br />类型：字符串 | 
| x-amz-version-id | 对象的版本。<br />类型：字符串 | 

#### 响应元素
<a name="RESTObjectPOST-requests-responses-response-elements"></a>


|  名称  |  描述  | 
| --- | --- | 
|  Bucket  | 存储对象的存储桶的名称。<br />类型：字符串<br />原级：PostResponse | 
|  ETag  | 实体标签（ETag）是对象的 MD5 哈希值，使用该值，您可以通过在 `GET` 请求操作中使用 `If-Modified` 请求标签来执行有条件 `GET` 操作。`ETag` 仅反映对于对象内容的更改，而不反映对于其元数据的更改。<br />类型：字符串<br />原级：PostResponse | 
|  Key  | 对象键名称。<br />类型：字符串<br />原级：PostResponse | 
|  Location  | 对象的 URI。<br />类型：字符串<br />原级：PostResponse | 

#### 特殊错误
<a name="RESTObjectPOST-requests-responses-special-errors"></a>

此操作的实施不返回特殊错误。有关 Amazon S3 错误的一般信息以及错误代码列表，请参阅[错误响应](ErrorResponses.md)。

## 示例
<a name="RESTObjectPOST-requests-examples"></a>

### 示例请求
<a name="ExampleVersionObjectPost"></a>

```
1. POST /Neo HTTP/1.1
2. Content-Length: 4
3. Host: quotes.s3.amazonaws.com
4. Date: Wed, 01 Mar  2006 12:00:00 GMT
5. Authorization: {{authorization string}}
6. Content-Type: text/plain
7. Expect: the 100-continue HTTP status code
8. 
9. {{ObjectContent}}
```

### 暂停版本控制时的响应示例
<a name="RESTObjectPOST-requests-examples-sample-response-with-versioning-suspended"></a>

以下是暂停存储桶版本控制时的响应示例：

```
 1. HTTP/1.1 100 Continue
 2. HTTP/1.1 200 OK
 3. x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
 4. x-amz-request-id: 0A49CE4060975EAC
 5. x-amz-version-id: default
 6. Date: Wed, 12 Oct 2009 17:50:00 GMT
 7. ETag: "1b2cf535f27731c974343645a3985328"
 8. Content-Length: 0
 9. Connection: close
10. Server: AmazonS3
```

在此响应中，版本 ID 为 `null`。

### 启用版本控制时的响应示例
<a name="RESTObjectPOST-requests-examples-sample-response-with-versioning-enabled"></a>

以下是启用存储桶版本控制时的响应示例。

```
 1. HTTP/1.1 100 Continue
 2. HTTP/1.1 200 OK
 3. x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
 4. x-amz-request-id: 0A49CE4060975EAC
 5. x-amz-version-id: 43jfkodU8493jnFJD9fjj3HHNVfdsQUIFDNsidf038jfdsjGFDSIRp
 6. Date: Wed, 01 Mar  2006 12:00:00 GMT
 7. ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f"
 8. Content-Length: 0
 9. Connection: close
10. Server: AmazonS3
```

## 相关资源
<a name="RESTObjectPOST-requests-related-resources"></a>
+  [CopyObject](https://docs.amazonaws.cn/AmazonS3/latest/API/API_CopyObject.html) 
+  [POST Object](#RESTObjectPOST) 
+  [GetObject](https://docs.amazonaws.cn/AmazonS3/latest/API/API_GetObject.html)