You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /对象存储/API 参考/存储桶/回源规则/PutBucketMirrorBack
PutBucketMirrorBack
最近更新时间：2024.09.12 18:02:53首次发布时间：2023.03.14 21:02:15
我的收藏

功能描述

此接口可以设置 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/"]
                }
            },
            "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

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 信息后，服务端会解析后进行加密存储。

父节点：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}
        }
    }]
}

响应示例

HTTP/1.1 200 OK
Date: Fri, 30 Jul 2021 13:53:55 GMT
Server: TosServer
x-tos-id-2: 1e89f203jld00006-a444fd0
x-tos-request-id: 1e89f203b2d00006-a444ed0