最近更新时间：2023.11.21 10:22:22
首次发布时间：2023.03.15 10:52:31
预签名的 URL 仅能生成单个对象的访问链接，如果您想通过预签名 URL 生成桶下目录的访问链接，完成目录的列举，以及目录中对象的查询和下载功能，可以通过携带查询参数 X-Tos-Policy 的 URL 预签名方式实现。通过本文介绍的预签名 URL，您可以在有效期内授予一批对象的访问权限，而不需要对桶或对象本身做任何配置。
https://bucketname.tos-cn-beijing.volces.com/ ?X-Tos-Algorithm=TOS4-HMAC-SHA256 &X-Tos-Credential=<access-key-id>/<YYYYMMDD>/<region>/tos/request &X-Tos-Date=20220101T000000Z &X-Tos-Expires=86400 &X-Tos-Policy=<policy> &X-Tos-Signature=<signature> &X-Tos-Security-Token=<security-token>
参数 | 描述 | 是否必选 |
|---|---|---|
X-Tos-Algorithm | 用于标记签名的版本及算法，当前只支持 TOS4-HMAC-SHA256。 | 是 |
X-Tos-Credential | 提供 AccessKey ID、日期，区域和服务信息。 格式为 | 是 |
X-Tos-Date | 当前请求时间（UTC 时间），格式为 yyyyMMddTHHmmssZ。 | 是 |
X-Tos-Expires | 该 URL 的有效期，单位为秒。该值为整数，最小为 1，最大为 604800（7 天），即签名有效期最长为 7 天。 | 是 |
X-Tos-Policy | 预签名的 URL 对桶中对象的访问策略，值为 Policy，需要经过 Base64 编码。 | 是 |
X-Tos-Signature | 计算的签名。 | 是 |
X-Tos-Security-Token | 使用临时 AK/SK 鉴权时，必须加上该头域，值为 SecurityToken。 | 否 |
查询参数 X-Tos-Policy 的值 Policy 为一段经过 UTF-8 和 Base64 编码的 JSON 文本，声明了使用该 URL 请求必须满足的条件，用于验证请求的合法性。
Policy 示例如下：
{ "conditions": [ {"bucket": "examplebucket"}, // 等价于 ["eq", "$bucket", "examplebucket"] ["starts-with", "$key", "example"] ] }
Policy 中支持的 Conditions 项请参见下表。
参数 | 参数类型 | 说明 | 限制 |
|---|---|---|---|
bucket | string | 指定可接受的桶的名称。 | 必须有且仅能有一个。 |
key | string | 对象名或者对象名的前缀。 | 至少有一个，可以有多个。 |
匹配方式 | 说明 |
|---|---|
精确匹配 | 桶名或对象名必须精确匹配 Conditions 中声明的值。 |
Starts With | 对象名必须以指定的值开头。以下示例表明对象名必须以 user/user1 开头： |
匹配任何内容 | 不对对象名做限制，请使用 starts-with 空值 ("")。以下示例表明不对 key 做校验： |
注意当存在多个 key 的规则时，多个规则间是或的关系，任意一个规则匹配成功，则通过该次请求的合法性校验。
本文介绍携带查询参数 X-Tos-Policy 的 URL 预签名方式与 Header 签名的区别。除了构造规范化请求（CanonicalRequest）上的差异外，其余流程均相同，差异点如下：
针对桶 examplebucket，如果您想要分享对象名前缀（即对应目录概念）为 abc/ 和 aaa/abc/ 的所有对象，同时分享对象名为 exampleobject 和 exampleobject1 的两个具体对象，可以构建如下 Policy。
{ "conditions": [ {"bucket": "examplebucket"}, // 等价于 ["eq", "$bucket", "examplebucket"] ["starts-with", "$key", "abc/"] ["starts-with", "$key", "aaa/abc/"] ["eq", "$key", "exampleobject"] ["eq", "$key", "exampleobject1"] ] }
计算签名的相关信息如下。
参数 | 值 |
|---|---|
区域 | cn-beijing |
当前请求时间 | Sat, 1 Jan 2022 00:00:00 GMT |
AccessKeyId | testAK |
SecretAccessKey | testSK |
预签名有效期 | 86400 秒 |
以下是 Policy 的 JSON 文本 Base64 编码后进行 URL 编码的内容。
eyJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJleGFtcGxlYnVja2V0In0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJhYmMvIl0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJhYWEvYWJjLyJdLFsiZXEiLCIka2V5IiwiZXhhbXBsZW9iamVjdCJdLFsiZXEiLCIka2V5IiwiZXhhbXBsZW9iamVjdDEi****
X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=testAK%2F20220101%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20220101T000000Z&X-Tos-Expires=86400&X-Tos-Policy=eyJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJleGFtcGxlYnVja2V0In0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJhYmMvIl0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJhYWEvYWJjLyJdLFsiZXEiLCIka2V5IiwiZXhhbXBsZW9iamVjdCJdLFsiZXEiLCIka2V5IiwiZXhhbXBsZW9iamVjdDEi**** UNSIGNED-PAYLOAD
TOS4-HMAC-SHA256 20220101T000000Z 20220101/cn-beijing/tos/request 07f73a178c9313fb228dbac92bef3293cabcb546809e4ae8eefb16c401ba8d60
HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("testSK", "20220101"), "cn-beijing"), "tos"), "request")
b9a2a01cdaff37247fcdab58717ab20a35b338138a992b1ba0f04df9dd807ba7
将上述签名计算得到 Signature，与 CanonicalQueryString 进行拼接可以得到用于生成 ListObjects、ListObjectVersions、HeadObject、GetObject 四种方法的签名 query 参数。其他用户可以基于该签名 query 参数，自主生成相应 URL。签名 query 参数，如下所示。
X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=testAK%2F20220101%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20220101T000000Z&X-Tos-Expires=86400&X-Tos-Policy=eyJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJleGFtcGxlYnVja2V0In0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJhYmMvIl0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJhYWEvYWJjLyJdLFsiZXEiLCIka2V5IiwiZXhhbXBsZW9iamVjdCJdLFsiZXEiLCIka2V5IiwiZXhhbXBsZW9iamVjdDEiXV19&X-Tos-Signature=b9a2a01cdaff37247fcdab58717ab20a35b338138a992b1ba0f04df9dd80****
BucketName、EndPoint、Path、签名 query 参数及额外 query 参数按照如下方式进行进行拼接，即可生成请求所需的 URL。其中列举对象场景中 ObjectKey 为空；查询和获取对象场景中，ObjectKey 为对象名，额外 query 参数与方法的具体行为有关，在下一节中说明。
https://{BucketName}.{Endpoint}/{ObjectKey}?{签名query参数}&{额外query参数}
注意
在生成 URL 阶段，query 参数间的顺序没有严格要求，本文中签名 query 参数在前，额外 query 参数在后的顺序仅作说明使用。
本文示例说明如下：
如果其他用户想基于该签名 query 参数，列举分享出来的对象中，前缀为 abc 的所有对象，可以通过携带 query 查询参数 prefix=abc，生成如下具体的 URL，然后通过 Get 请求访问该 URL，实现列举对象。
https://examplebucket.tos-cn-beijing.volces.com/?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=testAK%2F20220101%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20220101T000000Z&X-Tos-Expires=86400&X-Tos-Policy=eyJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJleGFtcGxlYnVja2V0In0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJhYmMvIl0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJhYWEvYWJjLyJdLFsiZXEiLCIka2V5IiwiZXhhbXBsZW9iamVjdCJdLFsiZXEiLCIka2V5IiwiZXhhbXBsZW9iamVjdDEiXV19&X-Tos-Signature=b9a2a01cdaff37247fcdab58717ab20a35b338138a992b1ba0f04df9dd807ba7&prefix=abc
额外 query 参数
额外 query 参数可以控制该次请求的某些具体行为。例如，携带 query 参数 prefix=abc/abc/ 可以列举前缀为 abc/abc/ 的对象，携带 query 参数 versions 可以列举多版本对象，更多参数选择请参见 listObjects 和 listObjectVersions 中的请求参数和消息头部分。
查询对象和获取对象的 URL 是一致的，区别在于通过 Head 请求访问该 URL，即可实现查询对象，通过 Get 请求访问该 URL，即可实现获取对象。
针对桶 examplebucket 中 exampleobject 对象的 123 版本的多版本对象，查询元数据/获取对象：
https://examplebucket.tos-cn-beijing.volces.com/exampleobject?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=testAK%2F20220101%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20220101T000000Z&X-Tos-Expires=86400&X-Tos-Policy=eyJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJleGFtcGxlYnVja2V0In0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJhYmMvIl0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJhYWEvYWJjLyJdLFsiZXEiLCIka2V5IiwiZXhhbXBsZW9iamVjdCJdLFsiZXEiLCIka2V5IiwiZXhhbXBsZW9iamVjdDEiXV19&X-Tos-Signature=b9a2a01cdaff37247fcdab58717ab20a35b338138a992b1ba0f04df9dd807ba7&versionId=123
其中 examplebucket 为 policy 中对应的桶名，exampleobject 为查询/获取对象的对象名。
额外 query 参数：
控制该次请求的具体行为，参数选择请参见 headObject 和 getObject 中的请求参数和消息头部分。
注意
headObject 和 getObject 可以在 Header 位置携带消息头控制请求行为，如果有相关需要，在请求 URL 时携带对应消息头即可。