## 功能描述此接口可以设置 Bucket 的回源规则。您可以根据规则中不同的 Condition 设置多条规则。 ## 注意事项 * 只有 Bucket Owner 可以设置回源规则。 * 最多支持设置 20 条回源规则。详细介绍，请参见镜像回源[注意事项](/docs/6349/1209430#3317ff52)和重定向回源[注意事项](/docs/6349/1209431#a3d01eb5)。 ## 请求消息样式 ```JSON 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" } } } }] } ``` ## 请求参数和消息头该请求使用的公共请求消息头，请参见[公共参数](/docs/6349/75044)。 |**名称** |**位置** |**参数类型** |**是否必选** |**示例值** |**说明** | |---|---|---|---|---|---| |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`: 不携带请求参数。|\ | | | | ||\ | | | | |:::warning|\ | | | | |即使设置了 `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。|\ | | | | |:::tip|\ | | | | |源站为公共桶时，必填。|\ | | | | ||\ | | | | |:::| |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|\ | | | | |:::tip|\ | | | | |源站为私有桶时，必填。|\ | | | | ||\ | | | | |:::| |Endpoint |String |否 |http://s3.bj.bcebos.com |源站服务商的访问域名，不带桶名，最大长度 255。|\ | | | | |父节点：Primary。|\ | | | | |:::tip|\ | | | | |源站为私有桶时，必填。|\ | | | | ||\ | | | | |:::| |BucketName |String |否 |bucket |回源的存储桶名称。|\ | | | | |父节点：Primary。|\ | | | | |:::tip|\ | | | | |源站为私有桶时，必填。|\ | | | | ||\ | | | | |:::| |CredentialProvider |Object |否 |\- |私有回源鉴权方式。|\ | | | | |父节点：Primary。|\ | | | | |:::tip|\ | | | | |源站为私有桶时，必填。|\ | | | | ||\ | | | | |:::| |Role |String |否 |ServiceRoleBackSourceAccessTOS |AssumeRole 的名称，仅当回源到 TOS 的私有桶时，可以使用 AssumeRole 进行鉴权。|\ | | | | |父节点：CredentialProvider。|\ | | | | |:::tip|\ | | | | |Role 鉴权和 AK/SK 方式鉴权为二选一，无法同时设置。|\ | | | | ||\ | | | | |:::| |Region |String |否 |cn\-beijing |回源桶所属的 Region，使用 AK/SK 方式鉴权时必填。|\ | | | | |父节点：CredentialProvider。 | |StaticCredential |Object |否 |\- |使用 AK/SK 方式鉴权。|\ | | | | |父节点：CredentialProvider。|\ | | | | |:::tip|\ | | | | |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 信息后，服务端会解析后进行加密存储。|\ | | | | | :::tip|\ | | | | | 由于首次创建回源规则已对 SecretKey 进行 AES256 加密，修改回源规则，且不涉及 `SecretKey` 参数变更场景下，则必须先对 SecretKey 进行解密，然后再进行加密存储。|\ | | | | | 因此仅调用 PutBucketMirrorBack 接口修改回源规则时，修改其他参数，不涉及 `SecretKey` 参数变更，才可以设置 `SKEncryptType` 为 `AES256`。|\ | | | | | :::|\ | | | | |父节点：StaticCredential。 | ## 响应消息头该请求返回的公共响应消息头，请参见[公共参数](/docs/6349/75044)。 ## 响应元素该响应不使用消息元素。 ## 请求示例 * **请求示例一：源站为公共桶** ```JSON 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 私有桶** ```JSON 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 存储协议的云厂商的私有桶** ```JSON 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} } }] } ``` ## 响应示例 ```JSON 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 ```

对象存储