本文导读

功能介绍
请求消息样式
请求消息参数
请求消息头
请求消息元素
响应消息样式
响应消息头
响应消息元素
错误响应消息
请求示例
响应示例

展开导读

文档首页/ 对象存储服务 OBS/ API参考/ API/ 桶的高级配置/ 设置镜像回源规则

设置镜像回源规则

更新时间：2025-07-30 GMT+08:00

查看PDF

功能介绍

本接口用于为指定桶配置镜像回源策略。接口是幂等的，如果桶上已存在相同策略内容，则返回成功，status code返回值为200；否则status code返回值为201。

请求消息样式

PUT /?mirrorBackToSource HTTP/1.1
Host: bucketname.obs.cn-north-4.myhuaweicloud.com 
Authorization: authorization
Content-Type: application/json
Content-Length: length
Date: date

policy json body

请求消息参数

该请求消息中不使用消息参数。

请求消息头

该请求使用公共消息头，具体参见表3。

请求消息元素

表1 请求消息元素
参数名称	是否必选	参数类型	描述
rules	是	Container	参数解释：策略规则数组。rules是id、 condition、redirect的父节点。约束限制：同一个桶下的不同策略前缀不能重复和起始包含，委托建议使用同一个。取值范围：因为每个桶最多创建10条镜像数据回源规则，所以数组长度的取值范围是[1,10]。具体请详见rules参数说明。默认取值：不涉及

表2 rules参数说明
参数名称	是否必选	参数类型	描述
id	是	String	参数解释：设置镜像回源规则的ID。当前桶上配置的镜像回源规则的唯一标识。约束限制：该规则ID为桶内唯一，不能与桶内其他策略重复。取值范围：长度为1~256的字符串，并且字符只能是大写字母、小写字母、数字、下划线（_）或连字符（-）。默认取值：不涉及
condition	是	Container	参数解释：触发回源功能的条件。condition是httpErrorCodeReturnedEquals、objectKeyPrefixEquals的父节点。约束限制：不涉及取值范围：请详见表3。默认取值：不涉及
redirect	是	Container	参数解释：实现回源功能的相关参数。redirect是agency、publicSource、retryConditions、passQueryString、mirrorFollowRedirect、replaceKeyWith、replaceKeyPrefixWith、vpcEndpointURN、redirectWithoutReferer、mirrorAllowHttpMethod的父节点。约束限制：不涉及取值范围：请详见表4。默认取值：不涉及

表3 condition参数说明
参数名称	是否必选	参数类型	描述
httpErrorCodeReturnedEquals	是	Integer	参数解释：触发回源功能的错误码。当下载请求返回此错误码时，会触发回源功能。约束限制：不涉及取值范围： 404：指对象在OBS桶中不存在。默认取值： 404
objectKeyPrefixEquals	否	String	参数解释：触发回源功能的对象名前缀。当触发回源的请求里对象名满足此前缀，才会继续执行回源功能。约束限制：当前缀配置为空时，默认所有对象都匹配。同一个桶上多条规则的前缀之间不允许重复和起始包含。取值范围：长度为0~1023的字符串，值允许为任意字符。默认取值：不涉及

表4 redirect参数说明
参数名称	是否必选	参数类型	描述
agency	是	String	参数解释：委托名。客户通过委托赋予OBS服务“查询用户桶内指定对象是否存在”以及“向用户桶内上传对象”的权限。约束限制：不涉及取值范围：不涉及默认取值：不涉及
publicSource	否	Container	参数解释：公共可访问的源端配置。当源端为公共可访问的资源时，必选。publicSource是sourceEndpoint的父节点。约束限制：不涉及取值范围：请详见publicSource参数说明。默认取值：不涉及
retryConditions	否	Array	参数解释：回源地址切换的条件。约束限制： 4XX和4开头的具体错误码不能同时配置，5XX和5开头的错误码不能同时配置。取值范围：最大支持同时配置20个错误码，如4XX，5XX以及400~499，500~599等具体错误码。默认取值：不涉及
passQueryString	是	Boolean	参数解释：是否携带请求字符串。约束限制：如果取值为true，但query参数里有签名信息，则将签名信息去掉，再传递剩余参数。取值范围： false：不会将OBS请求中的queryString传递到源站。 true：会将OBS请求中的queryString传递到源站。默认取值： false（如果设置为false则会忽略）
mirrorFollowRedirect	是	Boolean	参数解释：是否跟随源站3xx重定向请求获取到资源。约束限制：不涉及取值范围： false：OBS会透传3XX响应，不获取资源。 true：跟随源站3XX重定向请求获取到资源。默认取值： false（如果设置为false则会忽略）
mirrorHttpHeader	否	Container	参数解释： HTTP header传递规则。mirrorHttpHeader是passAll、pass、remove、set的父节点。约束限制：不涉及取值范围：请详见mirrorHttpHeader参数说明。默认取值：不涉及
replaceKeyWith	否	String	参数解释：去源端下载对象的时候是否添加前后缀。约束限制：如果replaceKeyWith和ReplaceKeyPrefixWith同时为空，则ReplaceKeyPrefixWith生效。同时非空为非法请求。取值范围： prefix${key}suffix：需要添加前缀或后缀。 ${key}：不需要增加前缀或后缀。 ${key}为关键字，prefix为要添加的前缀，suffix为要添加的后缀。同时prefix和suffix的总长度为[0, 1023]。默认取值：不涉及
replaceKeyPrefixWith	否	String	参数解释：替换前缀objectKeyPrefixEquals的字符串。如果去源端下载对象时，需要替换当前的对象名前缀，则修改此项配置。约束限制：如果replaceKeyWith和ReplaceKeyPrefixWith同时为空，则ReplaceKeyPrefixWith生效。同时非空为非法请求。取值范围：长度为0~1023的字符串。默认取值：不涉及
vpcEndpointURN	否	String	参数解释：终端节点服务的URN。约束限制：不涉及取值范围：长度为0~127的字符串。默认取值：不涉及
redirectWithoutReferer	否	Boolean	参数解释：是否将原host作为referer头域携带到重定向的目的地址去。约束限制：不涉及取值范围： false：将原host作为referer头域携带到重定向的目的地址去。 true：不会将原host作为referer头域携带到重定向的目的地址去。默认取值： false（如果设置为false则会忽略）
mirrorAllowHttpMethod	否	Array	参数解释：支持透传的请求方法。约束限制：不涉及取值范围： GET：请求获取桶内对象。 HEAD：请求获取桶内对象的元数据信息。默认取值：不涉及

表5 publicSource参数说明
参数名称	是否必选	参数类型	描述
sourceEndpoint	否	Container	参数解释：公共可访问的源端地址。sourceEndpoint是master、slave的父节点。约束限制：不涉及取值范围：请详见sourceEndpoint参数说明。默认取值：不涉及

表6 sourceEndpoint参数说明
参数名称	是否必选	参数类型	描述
master	否	Array	参数解释：主源端地址。如果源端为HTTP公共可访问的桶，则此地址为桶域名地址。如果源端为其他云厂商的私有桶，则此地址为区域域名地址。约束限制：回源时会优先使用主源站地址，如果同时配置1~5个主地址，会轮询访问所有主地址。如果配置2个及以上主地址，第一次请求主地址失败，并且满足重试条件时，会选用另一个主地址重试一次。取值范围：单个源站地址的格式为https://xxx.yyy.zzz或http://xxx.yyy.zzz，长度为10~255的字符串。默认取值：不涉及
slave	否	Array	参数解释：备源端地址。如果源端为HTTP公共可访问的桶，则此地址为桶域名地址。如果源端为其他云厂商的私有桶，则此地址为区域域名地址。约束限制：主地址回源失败时，会选用一个备地址进行重试。最多同时配置5个备地址。取值范围：单个源站地址的格式为https://xxx.yyy.zzz或http://xxx.yyy.zzz，长度为10~255的字符串。默认取值：不涉及

表7 mirrorHttpHeader参数说明
参数名称	是否必选	参数类型	描述
passAll	否	Boolean	参数解释：是否透传全部HTTP header到源端。约束限制： passAll与pass互斥。以下HTTP header类型不支持透传：以下前缀开头的header： x-obs- x-amz- 所有标准HTTP header，例如： Content-Length Authorization Date 取值范围： false：不透传全部HTTP header到源端 true：透传全部HTTP header到源端默认取值： false
pass	否	Array	参数解释：指定透传的HTTP header列表。约束限制：取值仅支持由大小写字母、数字、中划线、下划线组成。取值范围：最多展示10个HTTP header，每个HTTP header的长度范围是[1, 63]。默认取值：不涉及
remove	否	Array	参数解释：不允许透传的HTTP header列表。约束限制： remove优先级高于pass和passAll。取值仅支持由大小写字母、数字、中划线、下划线组成。取值范围：最多展示10个HTTP header，每个HTTP header的长度范围是[1, 63]。默认取值：不涉及
set	否	Array	参数解释：设置透传的HTTP header值列表。约束限制： set优先级高于remove，pass和passAll。如果自定义头域中包含了Referer头域，必须将redirectWithoutReferer设置为true，否则会被覆盖。取值范围： set最多展示10个HTTP header，每个HTTP header包含一个key和一个value。key和value的具体介绍请参见set参数说明。默认取值：不涉及

表8 set参数说明
参数名称	是否必选	参数类型	描述
key	否	String	参数解释：设置需要透传HTTP header的关键字。约束限制：多条key之间不允许重复。取值仅支持由大小写字母、数字、中划线、下划线组成。取值范围：长度为1~63的字符串。默认取值：不涉及
value	否	String	参数解释：设置需要透传HTTP header的值。约束限制：不涉及取值范围：长度为1~2048的字符串。默认取值：不涉及

响应消息样式

HTTP/1.1 status
Server: OBS
Date: date
Content-Length: length

响应消息头

该请求的响应消息使用公共消息头，具体请参考表1。

响应消息元素

该请求的响应消息中不带消息元素。

错误响应消息

无特殊错误，所有错误已经包含在表2和OEF错误码中。

请求示例

PUT /?mirrorBackToSource HTTP/1.1
Host: bucketname.obs.cn-north-4.myhuaweicloud.com 
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:sc2PM13Wlfcoc/YZLK0MwsI2Zpo=
Content-Type: application/json
Content-Length: 1049
Date: Tue, 21 Jul 2020 15:38:30 GMT

{
    "rules": [{
        "id": "abc123",
        "condition": {
            "httpErrorCodeReturnedEquals": "404",
            "objectKeyPrefixEquals": "video/"
        },
        "redirect": {
            "agency": "agency",
            "publicSource": {
                "sourceEndpoint": {
                    "master":["http://bucket1.xxx.yyy.com", "https://bucket2.xxx.yyy.com"],
                    "slave": ["http://bucket3.xxx.yyy.com", "https://bucket4.xxx.yyy.com"]
                }
            },
            "retryConditions": ["4XX", "5XX"],
            "passQueryString": true,
            "mirrorFollowRedirect": true,
            "redirectWithoutReferer": true,
            "mirrorAllowHttpMethod":["HEAD"],
            "mirrorHttpHeader": {
                "passAll": false,
                "pass": ["content-encoding"],
                "remove": ["content-type"],
                "set": [{
                    "key": "helloworld",
                    "value": "2222"
                }]
            },
            "replaceKeyWith": "prefix${key}suffix",
            "replaceKeyPrefixWith": "picture/",
            "vpcEndpointURN": "001"
        }
    }]
}

响应示例

HTTP/1.1 201 Created
Server: OBS
Date: Tue, 07 Jul 2020 07:29:13 GMT
Content-Length: 0

父主题：桶的高级配置

上一篇：删除桶归档存储对象直读策略

下一篇：获取镜像回源规则

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

盘古Doer提问云社区提问