功能描述

此接口可以设置 Bucket 的回源规则。您可以根据规则中不同的 Condition 设置多条规则。

注意事项

只有 Bucket Owner 可以设置回源规则。

最多支持设置 20 条回源规则。

详细介绍，请参见镜像回源注意事项和重定向回源注意事项。

请求消息样式

PUT /?mirror HTTP/1.1​
Host: bucketname.tos-cn-beijing.volces.com​
Date: Fri, 30 Jul 2021 08:05:36 +0000​
Authorization: authorization string​
{​
    "Rules":[{​
        "ID":"1",​
        "Condition":{​
            "HttpCode":404,  ​
            "KeyPrefix":"object-key-prefix",  ​
            "KeySuffix": "object-key-suffix",​
            "AllowHost": [​
                    "example.volcengine.com"​
                ],​
            "HttpMethod": [​
                    "GET",​
                    "HEAD"​
               ]​
        },​
        "Redirect":{​
            "RedirectType": "Mirror",        ​
            "FetchSourceOnRedirect": false,​
            "PublicSource":{      ​
                "SourceEndpoint":{ ​
                    "Primary":["http://abc.123/"],​
                    "Follower":["http://abc.456/"]​
                }​
            },​
            "PassQuery": true,     ​
            "FollowRedirect": true, ​
            "MirrorHeader":{       ​
                "PassAll": true,​
                "Pass": ["aaa", "bbb"],​
                "Remove": ["xxx", "yyy"]​
            },​
            "Transform": { ​
               "WithKeyPrefix": "addtional-key-prefix", ​
               "WithKeySuffix": "addtional-key-suffix",  ​
               "ReplaceKeyPrefix": { ​
                  "KeyPrefix": "key-prefix",​
                  "ReplaceWith": "replace-with"​
               }​
            }​
        }​
    }]​
}​

请求参数和消息头

该请求使用的公共请求消息头，请参见公共参数。

名称	位置	参数类型	是否必选	示例值	说明
mirror	Query	String	是	-	代表 PutBucketMirrorBack 请求的特殊标识。

请求元素

Rules

名称	参数类型	是否必选	示例值	说明
Rules	Array	是	-	回源策略规则数组。根节点，无父节点。
ID	String	否	1	规则 ID。当前桶上配置的回源规则的唯一标识，您可以自行设定，在有多个规则的标记不同的规则。限制如下：字符支持字母、数字、 -和 _。最大支持 32 个字符。父节点：Rules。

Condition

名称	参数类型	是否必选	示例值	说明
Condition	Object	是	-	触发回源功能的条件。父节点：Rules。
HttpCode	int	是	404	触发回源功能的错误码。当下载请求返回此错误码时，会触发回源功能。限制：目前只支持 404。父节点：Condition。
KeyPrefix	String	否	object-key-prefix	回源对象匹配的对象名前缀。限制：最大支持 512 个字符。父节点：Condition。
KeySuffix	String	否	object-key-suffix	回源对象匹配的对象名后缀。限制：最大支持 512 个字符。父节点：Condition。
AllowHost	Array	否	["example.volcengine.com"]	支持指定域名才会触发回源。域名需要能访问到桶，建议填写桶绑定的自定义域名。限制：最大支持 30 个域名。父节点：Condition。
HttpMethod	Array	否	["GET","HEAD"]	触发回源的请求类型，取值说明如下： ["GET","HEAD"]：表示 GetObject 请求或 HeadObject 请求都可以触发回源。 ["GET"]：表示仅 GetObject 请求可以触发回源。默认为 ["GET"]。

Redirect

名称	参数类型	是否必选	示例值	说明
Redirect	Object	是	-	指定匹配此规则后执行的动作。父节点：Rules。
RedirectType	String	否	Mirror	指定跳转的类型。取值范围如下： Mirror：镜像回源。 Async：重定向回源。父节点：Redirect。
FetchSourceOnRedirect	Boolean	否	false	重定向后是否去配置的源站拉取数据，取值说明如下： true：重定向后去配置的源站拉取数据。 false：重定向后不去配置的源站拉取数据。父节点：Redirect。
FetchSourceOnRedirectWithQuery	Boolean	否	false	重定向后去拉取数据时是否携带请求参数，若未配置则继承 PassQuery 配置： true: 携带请求参数。 false: 不携带请求参数父节点：Redirect。
PublicSource	Object	否	-	源站为公共桶时的回源地址配置。具体请参见下文的 PublicSource。父节点：Redirect。
PrivateSource	Object	否	-	源站为私有桶时的回源地址配置。具体请参见下文的 PrivateSource。父节点：Redirect。
PassQuery	Boolean	否	true	执行跳转或者镜像回源规则时，是否携带请求参数。取值说明如下： true: 携带请求参数。 false: 不携带请求参数。注意即使设置了 true，请求 TOS 鉴权相关的 Query 参数也不会被携带。父节点：Redirect。
FollowRedirect	Boolean	否	true	如果镜像回源获取的结果为 3xx，是否继续跳转到指定的 Location 获取数据。取值说明如下： true: TOS 会继续请求 Location 对应的地址。 false: TOS 会返回 302。父节点：Redirect。
MirrorHeader	Object	否	-	指定镜像回源时携带的 Header。父节点：Redirect。
PassAll	Boolean	否	true	是否透传全部 HTTP header 到源端。取值说明如下： true: 会透传全部 HTTP header 到源端。 false: 不会透传全部 HTTP header 到源端。以下 HTTP header 类型不支持透传： Host Content-Length Date Authorization 父节点：MirrorHeader。
Pass	Array	否	["aaa", "bbb"]	透传指定的 Header 到源站。限制：最大数量 64。父节点：MirrorHeader。
Remove	Array	否	["xxx", "yyy"]	禁止透传指定的 Header 到源站。限制：最大数量 64。父节点：MirrorHeader。
Transform	Object	否	-	定义对于请求源站的对象名的变换。父节点：Redirect。
WithKeyPrefix	String	否	addtional-key-prefix	请求源站的时候，在对象名字前面加上的前缀。限制：最大支持 512 个字符。父节点：Transform。
WithKeySuffix	String	否	addtional-key-suffix	请求源站的时候，在对象名字后加上的后缀。限制：最大支持 512 个字符。父节点：Transform。
ReplaceKeyPrefix	Object	否	-	请求源站的时候，替换对象名前缀。父节点：Transform
KeyPrefix	String	否	key-prefix	请求源站的时候，需要被替换的对象名前缀。限制：最大支持 512 个字符。父节点：ReplaceKeyPrefix。
ReplaceWith	String	否	replace-with	请求源站的时候，对象名前缀替换后的值。限制：最大支持 512 个字符。父节点：ReplaceKeyPrefix。

PublicSource

名称	参数类型	是否必选	示例值	说明
PublicSource	Object	否	-	源站为公共桶时的回源地址配置。父节点：Redirect。
SourceEndpoint	Object	否	-	公共可访问的源端地址。父节点：PublicSource。说明源站为公共桶时，必填。
Primary	Array	否	["http://abc.123/"]	源站地址。限制：最大长度 255，最多支持 5 个回源地址。父节点：SourceEndpoint。在回源时会优先从该配置中选择源站。
Follower	Array	否	["http://abc.456/"]	源站地址。限制：最大长度 255，最多支持 5 个回源地址。父节点：SourceEndpoint。在 Primary 中所有源站回源失败时从该配置中选择源站。

PrivateSource

名称	参数类型	是否必选	示例值	说明
PrivateSource	Object	否	-	源站为私有桶时的回源地址配置。父节点：Redirect。
SourceEndpoint	Object	否	-	源站为私有桶时的回源地址配置。父节点：PrivateSource。
Primary	Array	否	-	请求的源站地址，最多支持 5 个回源地址。父节点：SourceEndpoint 说明源站为私有桶时，必填。
Endpoint	String	否	http://s3.bj.bcebos.com	源站服务商的访问域名，不带桶名，最大长度 255。父节点：Primary。说明源站为私有桶时，必填。
BucketName	String	否	bucket	回源的存储桶名称。父节点：Primary。说明源站为私有桶时，必填。
CredentialProvider	Object	否	-	私有回源鉴权方式。父节点：Primary。说明源站为私有桶时，必填。
Role	String	否	ServiceRoleBackSourceAccessTOS	AssumeRole 的名称，仅当回源到 TOS 的私有桶时，可以使用 AssumeRole 进行鉴权。父节点：CredentialProvider。说明 Role 鉴权和 AK/SK 方式鉴权为二选一，无法同时设置。
Region	String	否	cn-beijing	回源桶所属的 Region，使用 AK/SK 方式鉴权时必填。父节点：CredentialProvider。
StaticCredential	Object	否	-	使用 AK/SK 方式鉴权。父节点：CredentialProvider。说明 AK/SK 方式鉴权和 Role 鉴权为二选一，无法同时设置。
StorageVendor	String	否	S3	源站服务商，取值说明如下： BOS：百度云。 S3：其他 S3 存储协议的云厂商。父节点：StaticCredential。
AK	String	否	AKLTNDk3NDMxY2NmNzNhNGNiN****	回源桶的 AccessKey ID，使用 AK/SK 方式鉴权时必填。父节点：StaticCredential
SK	String	否	AADFSDfdsfa3ewdr23==d****	回源桶的 SecretKey，使用 AK/SK 方式鉴权时必填。父节点：StaticCredential。
SKEncryptType	String	否	AES256	SecretKey 使用的加密方式。取值如下：空：SecretKey 为明文，收到 SecretKey 信息后，服务端会进行加密存储。 AES256：SecretKey 已使用 AES256 加密算法进行服务端加密，收到 SecretKey 信息后，服务端会解析后进行加密存储。说明由于首次创建回源规则已对 SecretKey 进行 AES256 加密，修改回源规则，且不涉及 SecretKey 参数变更场景下，则必须先对 SecretKey 进行解密，然后再进行加密存储。因此仅调用 PutBucketMirrorBack 接口修改回源规则时，修改其他参数，不涉及 SecretKey 参数变更，才可以设置 SKEncryptType 为 AES256。父节点：StaticCredential。

响应消息头

该请求返回的公共响应消息头，请参见公共参数。

响应元素

该响应不使用消息元素。

请求示例

请求示例一：源站为公共桶

PUT /?mirror HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 +0000
Authorization: authorization string
{
"Rules":[{
"ID":"xxx",
"Condition":{
"HttpCode":404,
"KeyPrefix":"prefix"
},
"Redirect":{
"PublicSource":{
"SourceEndpoint":{
"Primary":["http://abc.123/"]
}
},
"PassQuery":true,
"FollowRedirect":true,
"MirrorHeader":{"PassAll":true}
}
}]
}

请求示例二：源站为 TOS 私有桶

PUT /?mirror HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 +0000
Authorization: authorization string
{
"Rules":[{
"ID":"xxx",
"Condition":{
"HttpCode":404,
"KeyPrefix":"prefix"
},
"Redirect":{
"PrivateSource":{
"SourceEndpoint":{
"Primary": [{
"Endpoint": "http://tos-cn-beijing.volces.com",
"BucketName": "bucket",
"CredentialProvider": {
"Role": "ServiceRoleBackSourceAccessTOS"
}
}]
}
},
"PassQuery":true,
"FollowRedirect":true,
"MirrorHeader":{"PassAll":true}
}
}]
}

请求示例三：源站为其他 S3 存储协议的云厂商的私有桶

PUT /?mirror HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 +0000
Authorization: authorization string
{
"Rules":[{
"ID":"xxx",
"Condition":{
"HttpCode":404,
"KeyPrefix":"prefix"
},
"Redirect":{
"PrivateSource":{
"SourceEndpoint":{
"Primary": [{
"Endpoint": "http://s3.com",
"BucketName": "bucket",
"CredentialProvider": {
"Region": "cn-beijing",
"StaticCredential": {
"StorageVendor": "S3",
"AK": "AKLTNDk3NDMxY2NmNzNhNGNiN****",
"SK":"AADFSDfdsfa3ewdr23==d****"
}
}
}]
}
},
"PassQuery":true,
"FollowRedirect":true,
"MirrorHeader":{"PassAll":true}
}
}]
}

响应示例

对象存储