Amazon Simple Storage Service
开发人员指南 (API Version 2006-03-01)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

HTML 表单 (AWS 签名版本 2)。

与 Amazon S3 进行通信时,通常可以使用 REST 或 SOAP API 来执行放置、获取、删除和其他操作。借助 POST,用户可通过其浏览器将数据直接上传到 Amazon S3,浏览器无法处理 SOAP API 或创建 REST PUT 请求。

注意

HTTP 上的 SOAP 支持已弃用,但是仍可在 HTTPS 上使用。对于 SOAP 将不支持新 Amazon S3 功能。我们建议您使用 REST API 或 AWS 开发工具包。

要允许用户使用其浏览器将内容上传到 Amazon S3,要使用 HTML 表单。HTML 表单由表单声明和表单字段组成。表单声明包含关于请求的高级别信息。表单字段包含关于请求的详细信息,同时还包含用于对请求进行身份验证并确保其满足指定条件的策略。

注意

表单数据和边界 (不包括文件的内容) 不得超过 20 KB。

本部分说明如何使用 HTML 表单。

HTML 表单编码

必须采用 UTF-8 编码表单和策略。您可以将 UTF-8 编码应用于表单,方法是在 HTML 标题中指定它或将它指定为请求标头。

注意

HTML 表单声明不接受查询字符串身份验证参数。

下面是 HTML 标题中 UTF-8 编码的示例:

Copy
<html> <head> ... <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> ... </head> <body>

下面是请求标头中 UTF-8 编码的示例:

Copy
Content-Type: text/html; charset=UTF-8

HTML 表单声明

表单声明包含三个部分:操作、方法和附件类型。如果这些值当中的任意一个设置不正确,请求将失败。

操作将指定处理请求的 URL,必须将它设置为存储段的 URL。例如,如果存储段的名称是“johnsmith”,则 URL 为“http://johnsmith.s3.amazonaws.com/”。

注意

在表单字段中指定键名称。

方法必须是 POST。

必须为文件上传和文本区域上传都指定附件类型 (enctype) 并将其设置为“分段/表单数据”。有关更多信息,请转到 RFC 1867

以下示例是用于存储桶“johnsmith”的表单声明。

Copy
<form action="http://johnsmith.s3.amazonaws.com/" method="post" enctype="multipart/form-data">

HTML 表单字段

下表介绍可以在 HTML 表单中使用的字段。

注意

变量 ${filename} 将自动替换为用户提供的文件的名称,并且可由所有表单字段识别。如果浏览器或客户端提供完整或部分文件路径,则只会使用跟在最后一个斜杠 (/) 或反斜杠 (\) 之后的文本。例如,“C:\Program Files\directory1\file.txt”会解释为“file.txt”。如果没有提供文件或文件名,变量将替换为空字符串。

字段名称 说明 必需
AWSAccessKeyId

存储桶拥有者的 AWS 访问密钥 ID,该拥有者将授予匿名用户对满足策略中一组约束的请求的访问权限。如果请求包含策略文档,则此字段为必填字段。

条件

acl

Amazon S3 访问控制列表 (ACL)。如果指定了无效的访问控制列表,将产生错误。有关 ACL 的更多信息,请参阅 访问控制列表

类型:字符串

默认值:private

Valid Values: 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 的标头。有关更多信息,请参阅 PUT Object

key

已上传的密钥的名称。

要使用由用户提供的文件名,请使用 ${filename} 变量。例如,如果用户 Betty 上传了文件 lolcatz.jpg 并且您指定了 /user/betty/${filename},则该文件将存储为 /user/betty/lolcatz.jpg。

有关更多信息,请参阅 对象键和元数据

policy

描述请求中允许的内容的安全策略。不带安全策略的请求被认为是匿名的,只会在公共可写的存储桶上成功。

success_action_redirect, redirect

上传成功后客户端重定向到的 URL。Amazon S3 将存储桶、键和 etag 值作为查询字符串参数附加到 URL。

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

如果 Amazon S3 无法解释 URL,它将忽略该字段。

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

有关更多信息,请参阅重定向

注意

已弃用重定向字段名称并且将在以后移除对重定向字段名称的支持。

success_action_status

如果没有指定 success_action_redirect,上传成功后状态代码将返回到客户端。

有效值为 200、201 或 204 (默认)。

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

如果值被设置为 201,Amazon S3 将返回一个 XML 文档和一个 201 状态代码。有关 XML 文档内容的信息,请参阅 POST 对象

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

注意

某些版本的 Adobe Flash player 无法正确处理使用空白正文的 HTTP 响应。要通过 Adobe Flash 支持上传,建议您将 success_action_status 设置为 201。

signature

HMAC 签名,使用与提供的 AWSAccessKeyId 对应的秘密访问密钥构建。如果策略文档没有随请求一起提供,则此字段为必填字段。

有关更多信息,请参阅使用身份验证访问

条件

x-amz-security-token

Amazon DevPay 和会话证书使用的安全令牌。

如果请求使用 Amazon DevPay,则它需要两个 x-amz-security-token 表单字段:一个用于产品标识,另一个用于用户令牌。有关更多信息,请转到使用 DevPay

如果请求使用会话凭证,则它需要一个 x-amz-security-token 表单。有关更多信息,请参阅 IAM 用户指南 中的临时安全凭证

其他以 x-amz-meta- 为前缀的字段名称

特定于用户的元数据。

Amazon S3 没有验证或使用此数据。

有关更多信息,请参阅 PUT Object

文件

文件或文本内容。

文件或内容必须是表单中的最后一个字段。其下的任何字段都会忽略。

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

策略构建

策略是使用 UTF-8 和 Base64 编码的 JSON 文档,它指定了请求必须满足的条件并且用于对内容进行身份验证。根据您设计策略文档的方式,您可以对每次上传、每个用户、所有上传或根据其他能够满足您需要的设计来使用它们。

注意

尽管策略文档是可选的,我们强烈建议您使用它来创建公开可写的存储桶。

下面是策略文档的示例:

Copy
{ "expiration": "2007-12-01T12:00:00.000Z", "conditions": [ {"acl": "public-read" }, {"bucket": "johnsmith" }, ["starts-with", "$key", "user/eric/"], ] }

策略文档包括过期和条件。

过期

过期元素采用 ISO 8601 UTC 日期格式来指定策略的过期日期。例如,“2007-12-01T12:00:00.000Z”指定策略在 2007 年 12 月 1 日午夜 UTC 之后失效。在策略中过期是必需的。

条件

策略文档中的条件验证上传的对象的内容。您在表单中指定的每个表单字段 (AWSAccessKeyId、签名、文件、策略和带 x-ignore- 前缀的字段名称除外) 必须包含在条件列表中。

注意

如果您拥有多个具有相同名称的字段,必须使用逗号分隔值。例如,如果您拥有两个名为“x-amz-meta-tag”的字段,第一个字段的值为“Ninja”,第二个字段的值为“Stallman”,您可以将策略文档设置为 Ninja,Stallman

表单中的所有变量会在验证策略之前进行扩展。因此,应该针对扩展的字段执行所有条件匹配。例如,如果您将键字段设置为 user/betty/${filename},您的策略可能是 [ "starts-with", "$key", "user/betty/" ]。请勿输入 [ "starts-with", "$key", "user/betty/${filename}" ]。有关更多信息,请参阅 条件匹配

下表介绍策略文档条件。

元素名称 说明
acl

指定 ACL 必须满足的条件。

支持精确匹配和 starts-with

content-length-range

指定已上传内容允许的最小和最大大小。

支持范围匹配。

Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires

特定于 REST 的标头。

支持精确匹配和 starts-with

已上传的键的名称。

支持精确匹配和 starts-with

success_action_redirect, 重定向

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

支持精确匹配和 starts-with

success_action_status

如果没有指定 success_action_redirect,上传成功后状态代码将返回到客户端。

支持精确匹配。

x-amz-security-token

Amazon DevPay 安全令牌。

使用 Amazon DevPay 的每个请求都需要两个 x-amz-security-token 表单字段:一个用于产品标识,另一个用于用户令牌。因此,必须使用逗号来分隔值。例如,如果用户令牌是 eW91dHViZQ==,产品令牌是 b0hnNVNKWVJIQTA=,您可以将策略条目设置为:{ "x-amz-security-token": "eW91dHViZQ==,b0hnNVNKWVJIQTA=" }

有关 Amazon DevPay 的更多信息,请参阅使用 DevPay

其他以 x-amz-meta- 为前缀的字段名称

特定于用户的元数据。

支持精确匹配和 starts-with

注意

如果您的工具包添加了其他字段 (例如,Flash 添加了文件名),您必须将它们添加到策略文档。如果您可以控制此功能,将 x-ignore- 添加为字段的前缀以使 Amazon S3 忽略此功能并使其不影响此功能的未来版本。

条件匹配

下表介绍条件匹配类型。尽管您必须为您在表单中指定的每个表单字段指定一个条件,您也可以通过为某个表单字段指定多个条件来创建更复杂的匹配条件。

Condition 说明

精确匹配

精确匹配将验证字段是否匹配特定的值。此示例指示 ACL 必须设置为公共读取:

Copy
{"acl": "public-read" }

此示例是指示 ACL 必须设置为公共读取的替代方法:

Copy
[ "eq", "$acl", "public-read" ]

Starts With

如果值必须从某个特定的值开始,请使用 starts-with。本示例指示键必须以 user/betty 开头:

Copy
["starts-with", "$key", "user/betty/"]

匹配任何内容

要配置策略以允许字段中的任何内容,请使用 starts-with 和一个空值。本示例允许任何 success_action_redirect:

Copy
["starts-with", "$success_action_redirect", ""]

指定范围

对于接受范围的字段,请使用逗号来分隔上限和下限值。本示例允许 1 到 10 MB 的文件大小:

Copy
["content-length-range", 1048579, 10485760]

字符转义

下表介绍策略文档中必须进行转义的字符。

转义序列 描述

\\

反斜杠

\$

美元符号

\b

退格键

\f

换页

\n

新建行

\r

回车

\t

水平选项卡

\v

垂直选项卡

\uxxxx

所有 Unicode 字符

构建签名

步骤 说明
1

使用 UTF-8 对策略进行编码。

2

使用 Base64 对这些 UTF-8 字节进行编码。

3

使用 HMAC SHA-1,通过您的秘密访问密钥签署策略。

4

使用 Base64 对 SHA-1 签名进行编码。

有关身份验证的常见信息,请参阅使用身份验证访问

重定向

本节描述了如何处理重定向。

一般重定向

完成 POST 请求后,用户将重定向至您在 success_action_redirect 字段中指定的位置。如果 Amazon S3 无法解释 URL,它将忽略 success_action_redirect 字段。

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

如果 POST 请求失败,Amazon S3 将显示错误并且不会提供重定向。

预先上传重定向

如果您的存储桶是使用 <CreateBucketConfiguration> 创建的,您的最终用户可能会需要重定向。如果出现这种要求,某些浏览器可能无法正确处理重定向。这是比较罕见的,但在创建存储桶之后最有可能发生这种情况。