# POST 策略
<a name="sigv4-HTTPPOSTConstructPolicy"></a>

**Topics**
+ [过期](#sigv4-HTTPPOSTExpiration)
+ [条件匹配](#sigv4-ConditionMatching)
+ [条件](#sigv4-PolicyConditions)
+ [字符转义](#sigv4-HTTPPOSTEscaping)

使用 HTTP POST 发出经过身份验证的请求所需的策略是使用 JavaScript 对象表示法（JSON）编写的以 UTF-8 和 base64 编码的文档，该文档指定了请求必须满足的条件。根据您设计策略文档的方式，您可以对每次上传、每个用户、所有上传或根据其它可满足您需要的设计来控制访问权限粒度。

本节介绍 POST 策略。有关使用 POST 策略计算签名的示例，请参阅[示例：使用 HTTP POST 的基于浏览器的上传（使用 Amazon 签名版本 4）](sigv4-post-example.md)。

**注意**  
尽管策略文档是可选的，但我们强烈建议您使用策略文档来控制请求中支持的内容。如果您将存储桶设置为可公开写入，您根本无法控制哪些用户可以向您的存储桶写入内容。  
 

下面是 POST 策略文档的示例。

```
1. { "expiration": "2007-12-01T12:00:00.000Z",
2.   "conditions": [
3.     {"acl": "public-read" },
4.     {"bucket": "johnsmith" },
5.     ["starts-with", "$key", "user/eric/"],
6.   ]
7. }
```

POST 策略始终包含 `expiration` 和 `conditions` 元素。示例策略使用两种条件匹配类型（精确匹配和开头为匹配）。以下各节介绍了这些元素。

## 过期
<a name="sigv4-HTTPPOSTExpiration"></a>

`expiration` 元素以 ISO8601 GMT 日期格式指定 POST 策略的过期日期和时间。例如，`2013-08-01T12:00:00.000Z` 指定 POST 策略在 GMT 时间 2013 年 8 月 1 日午夜之后无效。

## 条件匹配
<a name="sigv4-ConditionMatching"></a>

下表描述了可用于指定 POST 策略条件的条件匹配类型（将在下一节中介绍）。尽管您必须为您在表单中指定的每个表单字段指定至少一个条件，但您也可以通过为某个表单字段指定多个条件来创建更复杂的匹配条件。


|  条件匹配类型 |  说明  | 
| --- | --- | 
| 精确匹配 | 表单字段值必须与指定的值匹配。此示例指示 ACL 必须设置为公共读取：<pre>{"acl": "public-read" }</pre><br />此示例是指示 ACL 必须设置为公共读取的替代方法：<pre>[ "eq", "$acl", "public-read" ]</pre> | 
| Starts With | 值必须以指定的值开头。本示例指示对象键必须以 user/user1 开头：<pre>["starts-with", "$key", "user/user1/"]</pre> | 
| 与逗号分隔列表中的 Content-Type 匹配 | 包含逗号的 `starts-with` 条件的 Content-Type 值解释为列表。列表中的每个值都必须满足该条件，才能满足整个条件。例如，给定以下条件：<pre>["starts-with", "$Content-Type", "image/"]</pre><br />以下值将满足条件：<pre>"image/jpg,image/png,image/gif"</pre><br />以下值将无法满足条件：<pre>["image/jpg,text/plain"]</pre>不管是否存在逗号，`Content-Type` 以外的数据元素都被视为字符串。 | 
| 匹配任何内容 | 要配置 POST 策略以支持表单字段中的任何内容，请使用 `starts-with` 以及一个空值（""）。此示例对于 `success_action_redirect` 支持任意值：<pre>["starts-with", "$success_action_redirect", ""]</pre> | 
| 指定范围 | 对于接受范围的表单字段，请使用逗号来分隔上限和下限。本示例支持 1 到 10 MiB 的文件大小：<pre>["content-length-range", 1048576, 10485760]</pre> | 

[条件](#sigv4-PolicyConditions)中介绍了 POST 策略中支持的特定条件。

## 条件
<a name="sigv4-PolicyConditions"></a>

POST 策略中的 `conditions` 是一个对象数组，其中的每个对象均用于验证请求。您可以使用这些条件来限制请求中支持的内容。例如，前面的策略条件要求符合以下各项：

 
+ 请求必须指定 `johnsmith` 存储桶名称。
+ 对象键名称必须有 `user/eric` 前缀。
+ 对象 ACL 必须设置为 `public-read`。

您在表单中指定的每个表单字段（`x-amz-signature`、`file`、`policy` 以及带有 `x-ignore-` 前缀的字段名称除外）都必须出现在条件列表中。

**注意**  
 在验证 POST 策略之前，表单中的所有变量都会扩展。因此，所有条件匹配都应该针对扩展的表单字段。假设您想将对象键名称限制为特定的前缀 (`user/user1`)。在这种情况下，您可以将键表单字段设置为 `user/user1/${filename}`。您的 POST 策略应为 `[ "starts-with", "$key", "user/user1/" ]`（请勿输入 `[ "starts-with", "$key", "user/user1/${filename}" ]`）。有关更多信息，请参阅 [条件匹配](#sigv4-ConditionMatching)。

下表中介绍了策略文档条件。


| 元素名称 | 说明 | 
| --- | --- | 
| acl | 指定提交表单时必须使用的 ACL 值。<br />此条件支持下一节中讨论的精确匹配和 `starts-with` 条件匹配类型。 | 
| bucket | 指定可接受的存储桶名称。<br />此条件支持精确匹配条件匹配类型。 | 
| content-length-range | 已上传的内容支持的最小和最大大小。<br />此条件支持 `content-length-range` 条件匹配类型。 | 
| Cache-Control`Content-Type`<br />`Content-Disposition`<br />`Content-Encoding`<br />`Expires` | 特定于 REST 的标头。有关更多信息，请参阅 [POST Object](RESTObjectPOST.md)。<br />此条件支持精确匹配和 `starts-with` 条件匹配类型。 | 
| key | 可接受的键名称或已上传对象的前缀。<br />此条件支持精确匹配和 `starts-with` 条件匹配类型。 | 
| success\_action\_redirect`redirect` | 上传成功后客户端重定向到的 URL。<br />此条件支持精确匹配和 `starts-with` 条件匹配类型。 | 
| success\_action\_status | 在未指定 `success_action_redirect` 的情况下，成功上传后返回到客户端的状态代码。<br />此条件支持精确匹配。 | 
| x-amz-algorithm | 计算签名时必须使用的签名算法。对于 Amazon 签名版本 4，该值为 `AWS4-HMAC-SHA256`。<br />此条件支持精确匹配。 | 
| x-amz-credential | 用于计算签名的凭证。它提供访问密钥 ID 和范围信息，用于标识签名对其有效的区域和服务。这应该与您在计算签名密钥以进行签名计算时使用的范围相同。<br />它是采用以下形式的字符串：<br />`{{<your-access-key-id>}}/{{<date>}}/{{<aws-region>}}/{{<aws-service>}}/aws4_request`<br />例如：<br />` AKIAIOSFODNN7EXAMPLE/20130728/us-east-1/s3/aws4_request`<br />对于 Amazon S3，aws-service 字符串为 `s3`。有关 Amazon S3 `aws-region` 字符串的列表，请参阅《Amazon Web Services 一般参考》**中的[区域和端点](https://docs.amazonaws.cn/general/latest/gr/rande.html#s3_region)。如果 POST 策略文档随请求一起提供，则此元素为必需项。<br />此条件支持精确匹配。 | 
| x-amz-date | 以 ISO8601 格式字符串指定的日期值。例如 `20130728T000000Z`。该日期必须与您在创建用于计算签名的签名密钥时使用的日期相同。<br />如果 POST 策略文档随请求一起提供，则此元素为必需项。<br />此条件支持精确匹配。 | 
| x-amz-security-token | Amazon DevPay 安全令牌。<br />使用 Amazon DevPay 的每个请求都需要两个 `x-amz-security-token` 表单字段：一个用于产品令牌，一个用于用户令牌。因此，必须使用逗号来分隔值。例如，如果用户令牌是 `eW91dHViZQ==`，产品令牌是 `b0hnNVNKWVJIQTA=`，您可以将 POST 策略条目设置为：`{ "x-amz-security-token": "eW91dHViZQ==,b0hnNVNKWVJIQTA=" }`。<br />有关 Amazon DevPay 的更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[使用 DevPay](https://docs.amazonaws.cn/AmazonS3/latest/userguide/UsingDevPay.html)。 | 
| x-amz-meta-\* | 特定于用户的元数据。<br />此条件支持精确匹配和 `starts-with` 条件匹配类型。 | 
| x-amz-\* | 有关其它 `x-amz-*` 标头，请参阅 POST 对象（[POST Object](RESTObjectPOST.md)）。<br />此条件支持精确匹配。 | 

**注意**  
 如果您的工具包添加了更多表单字段（例如，Flash 添加了 `filename`），您必须将它们添加到 POST 策略文档。如果您可以控制此功能，将 `x-ignore-` 添加为字段的前缀以使 Amazon S3 忽略此功能并使其不影响此功能的未来版本。

## 字符转义
<a name="sigv4-HTTPPOSTEscaping"></a>

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


|  转义序列  |  说明  | 
| --- | --- | 
| \\\\ | 反斜杠 | 
| \\$ | 美元符号 | 
| \\b | 退格键 | 
| \\f | 换页 | 
| \\n | 新建行 | 
| \\r | 回车 | 
| \\t | 水平选项卡 | 
| \\v | 垂直选项卡 | 
| \\u{{xxxx}} | 所有 Unicode 字符 | 

现在，您已经熟悉了表单和策略，并了解了签名的工作原理，可以尝试使用 POST 上传示例。您需要编写代码来计算签名。该示例提供了一个示例表单和一个可用于测试签名计算的 POST 策略。有关更多信息，请参阅 [示例：使用 HTTP POST 的基于浏览器的上传（使用 Amazon 签名版本 4）](sigv4-post-example.md)。