# HTML 表单 (AWS Signature Version 2) **Topics** + [HTML 表单编码](#HTTPPOSTFormEncoding) + [HTML 表单声明](#HTTPPOSTFormDeclaration) + [HTML 表单字段](#HTTPPOSTFormFields) + [策略构建](#HTTPPOSTConstructPolicy) + [构建签名](#HTTPPOSTConstructingPolicySignature) + [重定向](#HTTPPOSTConstructingPolicyRedirection) 与 Amazon S3 进行通信时，通常可以使用 REST 或 SOAP API 来执行放置、获取、删除和其他操作。借助 POST，用户可通过其浏览器将数据直接上传到 Amazon S3，浏览器无法处理 SOAP API 或创建 REST `PUT` 请求。 **注意** Amazon S3 的 SOAP API 不适用于新客户，并将于 2025 年 8 月 31 日接近使用寿命终止（EOL）。我们建议您使用 REST API 或 AWS 开发工具包。要允许用户使用其浏览器将内容上传到 Amazon S3，要使用 HTML 表单。HTML 表单由表单声明和表单字段组成。表单声明包含关于请求的高级别信息。表单字段包含关于请求的详细信息，同时还包含用于对请求进行身份验证并确保其满足指定条件的策略。 **注意** 表单数据和边界 (不包括文件的内容) 不得超过 20 KB。本部分说明如何使用 HTML 表单。 ## HTML 表单编码必须采用 UTF-8 编码表单和策略。您可以将 UTF-8 编码应用于表单，方法是在 HTML 标题中指定它或将它指定为请求标头。 **注意** HTML 表单声明不接受查询字符串身份验证参数。下面是 HTML 标题中 UTF-8 编码的示例： ``` 1. 2. 3. ... 4. 5. ... 6. 7. ``` 下面是请求标头中 UTF-8 编码的示例： ``` 1. Content-Type: text/html; charset=UTF-8 ``` ## HTML 表单声明表单声明包含三个部分：操作、方法和附件类型。如果这些值当中的任意一个设置不正确，请求将失败。操作将指定处理请求的 URL，必须将它设置为存储桶的 URL。例如，如果您的存储桶名称为 `awsexamplebucket1`，区域为美国西部（加利福尼亚北部），则 URL 为 `https://awsexamplebucket1.s3.us-west-1.amazonaws.com/`。 **注意** 在表单字段中指定键名。方法必须是 POST。必须为文件上传和文本区域上传都指定附件类型 (enctype) 并将其设置为“分段/表单数据”。有关更多信息，请转到 [RFC 1867](http://www.ietf.org/rfc/rfc1867.txt)。 **Example** 以下示例是用于存储桶“awsexamplebucket1”的表单声明。 ``` 1.

``` ## HTML 表单字段下表介绍可以在 HTML 表单中使用的字段。 **注意** 变量 `${filename}` 将自动替换为用户提供的文件的名称，并且可由所有表单字段识别。如果浏览器或客户端提供完整或部分文件路径，则只会使用跟在最后一个斜杠 (/) 或反斜杠 (\\) 之后的文本。例如，“C:\\Program Files\\directory1\\file.txt”会解释为“file.txt”。如果没有提供文件或文件名，变量将替换为空字符串。 | 字段名称 | 说明 | 必需 | | --- | --- | --- | | AWSAccessKeyId | 存储桶拥有者的 AWS 访问密钥 ID，该拥有者授予匿名用户对满足策略中一组约束的请求的访问权限。如果请求包含策略文档，则此字段为必填字段。 | 条件 | | acl | Amazon S3 访问控制列表 (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 的标头。有关更多信息，请参阅 [PUT Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html)。 | 否 | | key | 已上传的键的名称。
要使用由用户提供的文件名，请使用 ${filename} 变量。例如，如果用户 Betty 上传了文件 lolcatz.jpg 并且您指定了 /user/betty/${filename}，则该文件将存储为 /user/betty/lolcatz.jpg。
有关更多信息，请参阅[使用对象元数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 | 是 | | policy | 描述请求中允许的内容的安全策略。不带安全策略的请求被认为是匿名的，只会在公共可写的存储桶上成功。 | 否 | | success\_action\_redirect, redirect | 上传成功后客户端重定向到的 URL。Amazon S3 将存储桶、密钥和 etag 值作为查询字符串参数附加到 URL。
如果未指定 success\_action\_redirect，Amazon S3 将返回在 success\_action\_status 字段中指定的空文档类型。
如果 Amazon S3 无法解释 URL，它将忽略该字段。
如果上传失败，Amazon S3 将显示错误并且不会将用户重定向到某个 URL。
有关更多信息，请参阅[重定向](#HTTPPOSTConstructingPolicyRedirection)。已弃用重定向字段名称并且将在以后移除对重定向字段名称的支持。 | 否 | | success\_action\_status | 如果没有指定 success\_action\_redirect，上传成功后状态代码将返回到客户端。
有效值为 200、201 或 204 (默认)。
如果值设置为 200 或 204，Amazon S3 将返回一个空文档和一个 200 或 204 状态代码。
如果值设置为 201，Amazon S3 将返回一个 XML 文档和一个 201 状态代码。有关 XML 文档内容的信息，请参阅 [POST Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html)。
如果没有设置值或者设置了无效的值，Amazon S3 将返回一个空文档和一个 204 状态代码。某些版本的 Adobe Flash player 无法正确处理使用空白正文的 HTTP 响应。要通过 Adobe Flash 支持上传，建议您将 `success_action_status` 设置为 201。 | 否 | | signature | HMAC 签名，使用与提供的 AWSAccessKeyId 对应的秘密访问密钥构建。如果策略文档随请求一起提供，则此字段为必填字段。
有关更多信息，请参阅 [Amazon S3 的身份和访问权限管理](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-iam.html)。 | 有条件 | | x-amz-security-token | 会话凭证使用的安全令牌
如果请求使用 Amazon DevPay，则它需要两个 `x-amz-security-token` 表单字段：一个用于产品令牌，另一个用于用户令牌。
如果请求使用会话凭证，则它需要一个 `x-amz-security-token` 表单。有关更多信息，请参阅《IAM 用户指南》**中的[临时安全凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。
| 否 | | 其他以 x-amz-meta- 为前缀的字段名称 | 特定于用户的元数据。
Amazon S3 没有验证或使用此数据。
有关更多信息，请参阅 [PUT Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html)。 | 否 | | file | 文件或文本内容。
文件或内容必须是表单中的最后一个字段。其下的任何字段都会忽略。
您一次仅能上传一个文件。 | 是 | ## 策略构建 **Topics** + [过期](#HTTPPOSTExpiration) + [条件](#PolicyConditions) + [条件匹配](#ConditionMatching) + [字符转义](#HTTPPOSTEscaping) 策略是使用 UTF-8 和 Base64 编码的 JSON 文档，它指定了请求必须满足的条件并且用于对内容进行身份验证。根据您设计策略文档的方式，您可以对每次上传、每个用户、所有上传或根据其他能够满足您需要的设计来使用它们。 **注意** 尽管策略文档是可选的，我们强烈建议您使用它来创建公开可写的存储桶。下面是策略文档的示例： ``` 1. { "expiration": "2007-12-01T12:00:00.000Z", 2. 3. "conditions": [ 4. 5. {"acl": "public-read" }, 6. 7. {"bucket": "awsexamplebucket1" }, 8. 9. ["starts-with", "$key", "user/eric/"], 10. 11. ] 12. 13. } ``` 策略文档包括过期和条件。 ### 过期过期元素采用 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}" ]`。有关更多信息，请参阅 [条件匹配](#ConditionMatching)。下表介绍策略文档条件。 | 元素名称 | 说明 | | --- | --- | | acl | 指定 ACL 必须满足的条件。
支持精确匹配和 `starts-with`。 | | content-length-range | 指定已上传内容允许的最小和最大大小。
支持范围匹配。 | | Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires | 特定于 REST 的标头。
支持精确匹配和 `starts-with`。 | | key | 已上传的键的名称。
支持精确匹配和 `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=" }`。 | | 其他以 x-amz-meta- 为前缀的字段名称 | 特定于用户的元数据。
支持精确匹配和 `starts-with`。 | **注意** 如果您的工具包添加了其他字段 (例如，Flash 添加了文件名)，您必须将它们添加到策略文档。如果您可以控制此功能，将 `x-ignore-` 添加为字段的前缀以使 Amazon S3 忽略此功能并使其不影响此功能的未来版本。 ### 条件匹配下表介绍条件匹配类型。尽管您必须为您在表单中指定的每个表单字段指定一个条件，您也可以通过为某个表单字段指定多个条件来创建更复杂的匹配条件。 | Condition | 说明 | | --- | --- | | 精确匹配 | 精确匹配将验证字段是否匹配特定的值。此示例指示 ACL 必须设置为公共读取：

{"acl": "public-read" }

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

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

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

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

| | 匹配任何内容 | 要配置策略以允许字段中的任何内容，请使用 starts-with 和一个空值。本示例允许任何 success\_action\_redirect：

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

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

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

| ### 字符转义下表介绍策略文档中必须进行转义的字符。 | 转义序列 | 说明 | | --- | --- | | \\\\ | 反斜杠 | | \\$ | 美元符号 | | \\b | 退格键 | | \\f | 换页 | | \\n | 新建行 | | \\r | 回车 | | \\t | 水平选项卡 | | \\v | 垂直选项卡 | | \\u{{xxxx}} | 所有 Unicode 字符 | ## 构建签名 | 步骤 | 说明 | | --- | --- | | 1 | 使用 UTF-8 对策略进行编码。 | | 2 | 使用 Base64 对这些 UTF-8 字节进行编码。 | | 3 | 使用 HMAC SHA-1，通过您的秘密访问密钥签署策略。 | | 4 | 使用 Base64 对 SHA-1 签名进行编码。 | 有关身份验证的一般信息，请参阅 [Amazon S3 的身份和访问管理](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-iam.html)。 ## 重定向本节描述了如何处理重定向。 ### 一般重定向完成 POST 请求后，用户将重定向至您在 `success_action_redirect` 字段中指定的位置。如果 Amazon S3 无法解释 URL，它将忽略 `success_action_redirect` 字段。如果未指定 `success_action_redirect`，Amazon S3 将返回在 `success_action_status` 字段中指定的空文档类型。如果 POST 请求失败，Amazon S3 将显示错误并且不会提供重定向。 ### 预先上传重定向如果您的存储桶是使用创建的，您的最终用户可能会需要重定向。如果出现这种要求，某些浏览器可能无法正确处理重定向。这是比较罕见的，但在创建存储桶之后最有可能发生这种情况。