View a markdown version of this page

POST Object - Amazon Simple Storage Service
说明请求示例相关资源
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

POST Object

说明

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 的第 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 用户指南》中的使用服务器端加密保护数据。

重要

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

请求

语法

POST / HTTP/1.1
Host: destinationBucket.s3.amazonaws.com
User-Agent: browser_data
Accept: file_types
Accept-Language: Regions
Accept-Encoding: encoding
Accept-Charset: character_set
Keep-Alive: 300
Connection: keep-alive
Content-Type: multipart/form-data; boundary=9431149156168
Content-Length: length

--9431149156168
Content-Disposition: form-data; name="key"

acl
--9431149156168
Content-Disposition: form-data; name="tagging"

<Tagging><TagSet><Tag><Key>Tag Name</Key><Value>Tag Value</Value></Tag></TagSet></Tagging>
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"

success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Type"

content_type
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-uuid"

uuid
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-tag"

metadata
--9431149156168
Content-Disposition: form-data; name="AWSAccessKeyId"

access-key-id
--9431149156168
Content-Disposition: form-data; name="Policy"

encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"

signature=
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg

file_content
--9431149156168
Content-Disposition: form-data; name="submit"

Upload to Amazon S3
--9431149156168--

请求参数

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

表单字段

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

名称 描述 必需
AWSAccessKeyId

存储桶拥有者的 Amazon 访问密钥 ID，该拥有者向匿名用户授予对满足策略中一组约束的请求的访问权限。

类型：字符串

默认值：无

约束：如果策略文档随请求一起提供，则为必需项。

有条件
acl

指定的 Amazon S3 访问控制列表（ACL）。如果指定的 ACL 无效，将生成错误。有关 ACL 的更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的访问控制列表（ACL）概述。

类型：字符串

默认值：private

有效值：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。

类型：字符串

默认值：无

否
file

文件或文本内容。

文件或文本内容必须是表单中的最后一个字段。

您一次仅能上传一个文件。

类型：文件或文本内容

默认值：无

是
key

已上传的键的名称。

要使用由用户提供的文件名，请使用 ${filename} 变量。例如，如果名为 Mary 的用户上传了文件 example.jpg，而您指定了 /user/mary/${filename}，则键名称为 /user/mary/example.jpg。

有关更多信息，请参阅 Amazon Simple Storage Service 用户指南中的对象键和元数据。

类型：字符串

默认值：无

是
policy

描述请求中允许的内容的安全策略。不带安全策略的请求被认为是匿名的，只在公共可写的存储桶上有效。有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的 HTML 表单和上传示例。

类型：字符串

默认值：无

约束：如果存储桶不是可公开写入的，则需要安全策略。

有条件
success_action_redirect, redirect

上传成功后客户端重定向到的 URL。

如果未指定 success_action_redirect，Amazon S3 将返回在 success_action_status 字段中指定的空文档类型。

如果 Amazon S3 无法解释该 URL，则其行为就像该字段不存在一样。

如果上传失败，Amazon S3 将显示错误并且不会将用户重定向到某个 URL。

类型：字符串

默认值：无

注意

已弃用 redirect 字段名称，并且以后将移除对 redirect 字段名称的支持。

否
success_action_status

如果您未指定 success_action_redirect，则上传成功后，状态代码将返回给客户端。

此字段接受值 200、201 或 204（默认值）。

如果值设置为 200 或 204，Amazon S3 将返回一个空文档和一个 200 或 204 状态代码。

如果值设置为 201，Amazon S3 将返回一个 XML 文档和一个 201 状态代码。

如果没有设置值或设置为无效的值，Amazon S3 将返回一个空文档和一个 204 状态代码。

类型：字符串

默认值：无

否
tagging

要添加到对象的指定标签集。要添加标签，请使用以下编码方案。

<Tagging>
  <TagSet>
    <Tag>
      <Key>TagName</Key>
      <Value>TagValue</Value>
    </Tag>
    ...
  </TagSet>
</Tagging>

有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的为对象添加标签。

类型：字符串

默认值：无

否
x-amz-storage-class

要用于存储对象的存储类别。如果您未指定存储类别，Amazon S3 将使用默认存储类别 STANDARD。Amazon S3 支持其它存储类别。有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的存储类别。

类型：字符串

默认：STANDARD

有效值： REDUCED_REDUNDANCY| EXPRESS_ONEZONE | DEEP_ARCHIVE | GLACIER | GLACIER_IR | INTELLIGENT_TIERING | ONEZONE_IA | STANDARD | STANDARD_IA

否
x-amz-meta-*

以此前缀开头的标头是用户定义的元数据。每个元数据均以一组键-值对的形式存储和返回。Amazon S3 不验证或解释用户定义的元数据。有关更多信息，请参阅 PutObject。

类型：字符串

默认值：无

否
x-amz-security-token

Amazon DevPay 安全令牌。

使用 Amazon DevPay 的每个请求都需要两个 x-amz-security-token 表单字段：一个用于产品令牌，一个用于用户令牌。

类型：字符串

默认值：无

否
x-amz-signature

（Amazon 签名版本 4）安全策略的 HMAC-SHA256 哈希值。

类型：字符串

默认值：无

有条件
x-amz-website-redirect-location

如果存储桶配置为网站，则此字段会将对此对象的请求重定向到同一存储桶中的另一个对象，或者重定向到外部 URL。Amazon S3 将此标头的值存储在对象元数据中。有关对象元数据的信息，请参阅《Amazon Simple Storage Service 用户指南》中的对象键和元数据。

在以下示例中，请求标头将重定向设置为同一存储桶中的对象（anotherPage.html）：

x-amz-website-redirect-location: /anotherPage.html

在以下示例中，请求标头将对象重定向设置为另一个网站：

x-amz-website-redirect-location: http://www.example.com/

有关 Amazon S3 中的网站托管的更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的在 Amazon S3 上托管网站和如何配置网站页面重定向。

类型：字符串

默认值：无

约束：该值必须以 /、http:// 或 https:// 为前缀。值的长度限制为 2 KB。

 否

其它校验和请求表单字段

上传对象时，您可以指定要用于验证数据完整性的各种校验和。您可以指定一个额外的校验和算法供 Amazon S3 使用。有关其它校验和值的更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的检查对象完整性。

名称 描述 必填
x-amz-checksum-algorithm

表示用于为对象创建校验和的算法。如果指定了值，则必须包括匹配的校验和标头。否则，您的请求将生成 400 错误。

可能的值包括 CRC32、CRC32C、SHA1 和 SHA256。

 否
x-amz-checksum-crc32

指定对象的 base64 编码的 32 位 CRC32 校验和。

如果 x-amz-checksum-algorithm 的值为 CRC32，则此参数是必需的。

 有条件
x-amz-checksum-crc32c

指定对象的 base64 编码的 32 位 CRC32C 校验和。

如果 x-amz-checksum-algorithm 的值为 CRC32C，则此参数是必需的。

 有条件
x-amz-checksum-sha1

指定对象的 base64 编码的 160 位 SHA-1 摘要。

如果 x-amz-checksum-algorithm 的值为 SHA1，则此参数是必需的。

 有条件
x-amz-checksum-sha256

指定对象的 base64 编码的 256 位 SHA-256 摘要。

如果 x-amz-checksum-algorithm 的值为 SHA256，则此参数是必需的。

 有条件

特定于服务器端加密的请求表单字段

服务器端加密是静态数据加密。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。

有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的使用服务器端加密保护数据。

根据您要使用的服务器端加密类型，指定以下表单字段。

  • 使用 SSE-S3、SSE-KMS 或 DSSE-KMS：如果您要使用这些类型的服务器端加密，请在请求中指定以下表单字段。

    名称 描述 必填
    x-amz-server-side-encryption

    指定 Amazon S3 创建对象时要使用的服务器端加密算法。要使用 SSE-S3，请指定 AES256。要使用 SSE-KMS，请指定 aws:kms。要使用 DSSE-KMS，请指定 aws:kms:dsse。

    类型：字符串

    有效值：aws:kms、AES256、aws:kms:dsse

    		 是
    x-amz-server-side-encryption-aws-kms-key-id

    如果 x-amz-server-side-encryption 标头的有效值为 aws:kms 或 aws:kms:dsse，则此标头指定用于加密对象的 Amazon KMS key的 ID。

    类型：字符串

    		 是，如果 x-amz-server-side-encryption 的值为 aws:kms 或 aws:kms:dsse
    x-amz-server-side-encryption-context

    如果 x-amz-server-side-encryption 的有效值为 aws:kms 或 aws:kms:dsse，则此标头指定对象的加密上下文。此标头的值是 base64 编码的 UTF-8 字符串，其中包含加密上下文的 JSON 格式的键-值对。

    类型：字符串

    		 否
    x-amz-server-side-encryption-bucket-key-enabled

    如果 x-amz-server-side-encryption 的有效值为 aws:kms 或 aws:kms:dsse，则此标头指定 Amazon S3 是否应将 S3 存储桶密钥与 SSE-KMS 或 DSSE-KMS 结合使用。将此标头设置为 true，会导致 Amazon S3 将 S3 存储桶密钥与 SSE-KMS 或 DSSE-KMS 结合使用来进行对象加密。

    类型：布尔值

    		 否
    注意

    如果您指定 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。

    名称 描述 必填
    x-amz-server-side-encryption-customer-algorithm

    指定加密对象时要使用的算法。

    类型：字符串

    默认值：无

    有效值：AES256

    约束：必须附有有效的 x-amz-server-side-encryption-customer-key 和 x-amz-server-side-encryption-customer-key-MD5 字段。

    		 是
    x-amz-server-side-encryption-customer-key

    指定 Amazon S3 加密数据时要使用的客户提供的 base64 编码的加密密钥。此值用于存储对象，然后将其丢弃。Amazon 不存储加密密钥。密钥必须适合用于 x-amz-server-side-encryption-customer-algorithm 标头中指定的算法。

    类型：字符串

    默认值：无

    约束：必须附有有效的 x-amz-server-side-encryption-customer-algorithm 和 x-amz-server-side-encryption-customer-key-MD5 字段。

    		 是
    x-amz-server-side-encryption-customer-key-MD5

    根据 RFC 1321 指定加密密钥的 base64 编码的 128 位 MD5 摘要。Amazon S3 使用此标头进行消息完整性检查，以确保加密密钥传输无误。

    类型：字符串

    默认值：无

    约束：必须附有有效的 x-amz-server-side-encryption-customer-algorithm 和 x-amz-server-side-encryption-customer-key 字段。

    		 是

响应

响应标头

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

名称 描述
x-amz-checksum-crc32

对象的 base64 编码的 32 位 CRC32 校验和。

类型：字符串
x-amz-checksum-crc32c

对象的 base64 编码的 32 位 CRC32C 校验和。

类型：字符串
x-amz-checksum-sha1

对象的 base64 编码的 160 位 SHA-1 摘要。

类型：字符串
x-amz-checksum-sha256

对象的 base64 编码的 256 位 SHA-256 摘要。

类型：字符串
x-amz-expiration

如果在存储桶的生命周期配置中为对象配置了 Expiration 操作，则 Amazon S3 会返回此标头。 标头值包括一个 expiry-date 组件和一个 URL 编码的 rule-id 组件。 对于启用版本控制的存储桶，此标头仅适用于当前版本。Amazon S3 不提供标头来指示非当前版本何时符合永久删除条件。有关更多信息，请参阅 PutBucketLifecycleConfiguration。

类型：字符串
success_action_redirect, redirect

上传成功后客户端重定向到的 URL。

类型：字符串

原级：PostResponse
x-amz-server-side-encryption

在 Amazon S3 中存储此对象时使用的服务器端加密算法（例如 AES256、aws:kms、aws:kms:dsse）。

类型：字符串
x-amz-server-side-encryption-aws-kms-key-id

如果 x-amz-server-side-encryption 标头的有效值为 aws:kms，则此标头指定用于加密对象的 KMS 密钥的 ID。

类型：字符串
x-amz-server-side-encryption-bucket-key-enabled

如果 x-amz-server-side-encryption 的有效值为 aws:kms，则此标头表示是否使用 S3 存储桶密钥通过 SSE-KMS 为对象加密。如果此标头设置为 true，则对象会将 S3 存储桶密钥与 SSE-KMS 结合使用。

类型：布尔值
x-amz-server-side-encryption-customer-algorithm

如果请求了 SSE-C，则响应将包含此标头，用于确认所使用的加密算法。

类型：字符串

有效值：AES256
x-amz-server-side-encryption-customer-key-MD5

如果请求了 SSE-C，则响应将包含此标头，用于验证客户提供的加密密钥的往返消息完整性。

类型：字符串
x-amz-version-id

对象的版本。

类型：字符串

响应元素

名称 描述
Bucket

存储对象的存储桶的名称。

类型：字符串

原级：PostResponse
ETag

实体标签（ETag）是对象的 MD5 哈希值，使用该值，您可以通过在 GET 请求操作中使用 If-Modified 请求标签来执行有条件 GET 操作。ETag 仅反映对于对象内容的更改，而不反映对于其元数据的更改。

类型：字符串

原级：PostResponse
Key

对象键名称。

类型：字符串

原级：PostResponse
Location

对象的 URI。

类型：字符串

原级：PostResponse

特殊错误

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

示例

示例请求

POST /Neo HTTP/1.1
Content-Length: 4
Host: quotes.s3.amazonaws.com
Date: Wed, 01 Mar  2006 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain
Expect: the 100-continue HTTP status code

ObjectContent

暂停版本控制时的响应示例

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

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

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

启用版本控制时的响应示例

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

HTTP/1.1 100 Continue
HTTP/1.1 200 OK
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: 43jfkodU8493jnFJD9fjj3HHNVfdsQUIFDNsidf038jfdsjGFDSIRp
Date: Wed, 01 Mar  2006 12:00:00 GMT
ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f"
Content-Length: 0
Connection: close
Server: AmazonS3