# 设置镜像回源规则-PutMirrorBackToSource #### 功能介绍 OBS提供数据回源功能，可以在被请求的数据不存在时，通过回源规则从源站获取对应数据。可通过本接口为指定桶设置镜像回源规则。了解更多镜像回源相关信息，请参见[使用镜像回源获取源站数据](https://support.huaweicloud.com/usermanual-obs/obs_03_0006.html)。 #### 接口约束 表1约束与限制 | 限制分类 | 说明 | |:---|:---| | **桶版本限制** | 仅桶版本号为3.0及以上的桶支持镜像回源。 | | **时间限制** | 修改镜像回源规则，需要5分钟之后才能生效。 | | **规则数量限制** | 最多创建10条镜像数据回源规则。 | | **功能限制** | - 不支持匿名用户配置镜像回源规则。 - 不支持企业联邦用户使用镜像回源功能，更多关于联邦用户的相关信息请参考[华为云账号概述](https://support.huaweicloud.com/iam_faq/iam_01_0615.html)和[身份提供商概述](https://support.huaweicloud.com/usermanual-iam/iam_08_0001.html)。 - 不支持给并行文件系统配置镜像回源规则。 - 不支持OBS静态网站，即通过OBS静态网站域名下载对象出现404，不会触发镜像回源规则。 - 不支持在镜像回源规则中指定当前OBS桶域名，即源桶与目标桶不能是同一个桶。 - 私有桶的镜像回源当前仅支持部分云厂商。 - 设置回源策略时，不支持两个桶相互配置为回源桶，即A桶配置回源桶为B桶时，不支持再配置B桶的回源桶为A桶。 - 不支持源站使用Transfer-Encoding: chunked方式传输数据，即从源站下载对象的响应中必须包含Content-Length头域来指明源对象大小，使用Transfer-Encoding: chunked方式会导致回源失败。 此种场景在数据回源中的配置方式为：创建/编辑数据回源规则 \> HTTP header传递规则 \> 允许传递所有参数 \> 打开"禁止传递指定参数"开关 \> 输入"Accept-Encoding"。 - 如果同时配置了CDN加速域名和镜像回源规则，且CDN侧开启了Range回源，则需要源站至少返回Etag和Last-Modified两个Header的其中一个，否则可能会导致请求中断。 - 如果回源源站中使用Nginx反向代理源站，请关闭Nginx的chunked_transfer_encoding配置项： ``` location / { chunked_transfer_encoding off; } ``` | | **权限限制** | - 需要使用IAM的角色与策略授权功能，增加Tenant Administrator权限后才能设置、获取和删除镜像回源规则。 - 镜像回源需使用IAM的角色与策略授权功能，创建云服务委托，委托OBS获取源站数据。委托需要给OBS服务授予obs:object:PutObject、obs:object:GetObject、obs:bucket:ListBucket、obs:object:AbortMultipartUpload权限。 - 如果桶开启了SSE-KMS服务端加密功能，对OBS的云服务委托中还需要使用IAM的角色与策略授权功能，配置kms:cmk:get、kms:cmk:list、kms:cmk:create、kms:dek:create、kms:dek:encrypt、kms:dek:decrypt权限。 | | **其他限制** | - 镜像回源暂时不收费。 - 不允许多条镜像回源规则配置的文件名前缀存在相互包含或重叠的关系，即对同一个对象的请求不能同时匹配两条镜像回源规则。 - 针对镜像回源配置未遵循[RFC Range Requests标准](https://www.rfc-editor.org/rfc/rfc7233)的源站，客户在使用分段（Range）回源时，HTTP请求需携带Range头域并检查Range头域取值的有效性。 Range头域指定回源获取的内容范围，取值不能超过文件大小。例如，对大小为1024字节的对象做分段回源，可以指定回源前512字节（Range值为0\~511），Range值有效。指定回源2048个字节（Range值为0\~2048），超过对象大小，Range值无效，回源失败。 | #### 授权信息 您必须是桶拥有者或者拥有**Tenant Administrator** 权限，才能调用本接口。配置Tenant Administrator权限，需要使用**角色与策略授权** （旧版IAM，即IAM v3接口），授权操作请参考[使用IAM授权](https://support.huaweicloud.com/qs-iam/iam_01_0030.html)。 #### URI PUT / #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-obs/obs_04_0006.html)。调用前需要先[计算API签名](https://support.huaweicloud.com/api-obs/obs_04_0009.html)，并将签名添加到请求中。 您还可以使用[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/OBS/doc?api=SetBucketMirrorBackToSource)在线调试接口。 #### 请求消息样式 ``` PUT /?mirrorBackToSource HTTP/1.1 Host: bucketname.obs.cn-north-4.myhuaweicloud.com Authorization: authorization Content-Type: application/json Content-Length: length Date: date { "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", "vpcEndpointURN": "001" } }] } ``` #### URI参数（URI Parameters） 该请求消息中不使用消息参数。 #### 请求头参数（Request headers） 该请求使用公共请求头，具体参见[表3](https://support.huaweicloud.com/api-obs/obs_04_0007.html#ZH-CN_TOPIC_0136436606__table25197309)。 #### 请求体参数（Request body） 表2请求体参数 | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | rules | 是 | Container | **参数解释：** 策略规则数组。rules是id、 condition、redirect的父节点。 **约束限制：** 同一个桶下的不同策略前缀不能重复和起始包含，委托建议使用同一个。 因为每个桶最多创建10条镜像数据回源规则，所以数组长度的取值范围是\[1,10\]。具体请详见[rules参数说明]。 **默认取值：** 不涉及 | 表3rules参数说明 | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | id | 是 | String | **参数解释：** 设置镜像回源规则的ID。当前桶上配置的镜像回源规则的唯一标识。 **约束限制：** 该规则ID为桶内唯一，不能与桶内其他策略重复。 **取值范围：** 长度为1\~256的字符串，并且字符只能是大写字母、小写字母、数字、下划线（_）或连字符（-）。 **默认取值：** 不涉及 | | condition | 是 | Container | **参数解释：** 触发回源功能的条件。condition是httpErrorCodeReturnedEquals、objectKeyPrefixEquals的父节点，请详见[表4]。 **约束限制：** 不涉及 **默认取值：** 不涉及 | | redirect | 是 | Container | **参数解释：** 实现回源功能的相关参数。redirect是agency、publicSource、retryConditions、passQueryString、mirrorFollowRedirect、replaceKeyWith、replaceKeyPrefixWith、vpcEndpointURN、redirectWithoutReferer、mirrorAllowHttpMethod的父节点，请详见[表5]。 **约束限制：** 不涉及 **默认取值：** 不涉及 | 表4condition参数说明 | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | httpErrorCodeReturnedEquals | 是 | String | **参数解释：** 触发回源功能的错误码。当下载请求返回此错误码时，会触发回源功能。 **约束限制：** 不涉及 **取值范围：** 404：指对象在OBS桶中不存在。 **默认取值：** 404 | | objectKeyPrefixEquals | 否 | String | **参数解释：** 触发回源功能的对象名前缀。当触发回源的请求里对象名满足此前缀，才会继续执行回源功能。 **约束限制：** - 当前缀配置为空时，默认所有对象都匹配。 - 同一个桶上多条规则的前缀之间不允许重复和起始包含。 **取值范围：** 长度为0\~1023的字符串，值允许为任意字符。 **默认取值：** 不涉及 | 表5redirect参数说明 | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | agency | 是 | String | **参数解释：** 委托名。客户通过委托赋予OBS服务"查询用户桶内指定对象是否存在"以及"向用户桶内上传对象"的权限。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | publicSource | 否 | Container | **参数解释：** 公共可访问的源端配置。当源端为公共可访问的资源时，必选。publicSource是sourceEndpoint的父节点，请详见[publicSource参数说明]。 **约束限制：** 不涉及 **默认取值：** 不涉及 | | retryConditions | 否 | Array | **参数解释：** 数组元素的类型为Array Of Strings，是指回源地址切换的条件。 **约束限制：** 4XX和4开头的具体错误码不能同时配置，5XX和5开头的错误码不能同时配置。 **取值范围：** 最大支持同时配置20个错误码，如4XX，5XX以及400\~499，500\~599等具体错误码，具体错误码说明请参见[错误码](https://support.huaweicloud.com/api-obs/obs_errorcode_0001.html)。 **默认取值：** 不涉及 | | passQueryString | 是 | Boolean | **参数解释：** 是否携带请求字符串。 **约束限制：** 如果取值为true，但query参数里有签名信息，则将签名信息去掉，再传递剩余参数。 **取值范围：** - false：不会将OBS请求中的queryString传递到源站。 - true：会将OBS请求中的queryString传递到源站。 **默认取值：** false | | mirrorFollowRedirect | 是 | Boolean | **参数解释：** 是否跟随源站3xx重定向请求获取到资源。 **约束限制：** 不涉及 **取值范围：** - false：OBS会透传3XX响应，不获取资源。 - true：跟随源站3XX重定向请求获取到资源。 **默认取值：** false | | mirrorHttpHeader | 否 | Container | **参数解释：** HTTP header传递规则。mirrorHttpHeader是passAll、pass、remove、set的父节点，请详见[mirrorHttpHeader参数说明]。 **约束限制：** 不涉及 **默认取值：** 不涉及 | | replaceKeyWith | 否 | String | **参数解释：** 回源时替换对象名的规则，可使用${key}占位符、prefix前缀和suffix后缀。 **约束限制：** 如果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 | | mirrorAllowHttpMethod | 否 | Array | **参数解释：** 支持透传的请求方法。可选值为：GET（请求获取桶内对象）、HEAD（请求获取桶内对象的元数据信息）。 **约束限制：** 不涉及 **默认取值：** 不涉及 | 表6publicSource参数说明 | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | sourceEndpoint | 否 | Container | **参数解释：** 公共可访问的源端地址。sourceEndpoint是master、slave的父节点，请详见[sourceEndpoint参数说明]。 **约束限制：** 不涉及 **默认取值：** 不涉及 | 表7sourceEndpoint参数说明 | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | master | 否 | Array | **参数解释：** 主源端地址。如果源端为HTTP公共可访问的桶，则此地址为桶域名地址。如果源端为其他云厂商的私有桶，则此地址为区域域名地址。单个源站地址的格式为https://xxx.yyy.zzz或http://xxx.yyy.zzz，长度为10\~255的字符串。数组元素的类型为Array Of Strings。 **约束限制：** 回源时会优先使用主源站地址，如果同时配置1\~5个主地址，会轮询访问所有主地址。如果配置2个及以上主地址，第一次请求主地址失败，并且满足重试条件时，会选用另一个主地址重试一次。 **默认取值：** 不涉及 | | slave | 否 | Array | **参数解释：** 备源端地址。如果源端为HTTP公共可访问的桶，则此地址为桶域名地址。如果源端为其他云厂商的私有桶，则此地址为区域域名地址。单个源站地址的格式为https://xxx.yyy.zzz或http://xxx.yyy.zzz，长度为10\~255的字符串。数组元素的类型为Array Of Strings。 **约束限制：** 主地址回源失败时，会选用一个备地址进行重试。最多同时配置5个备地址。 **默认取值：** 不涉及 | 表8mirrorHttpHeader参数说明 | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | passAll | 否 | Boolean | **参数解释：** 是否透传全部HTTP header到源端。 **约束限制：** - passAll与pass互斥。 - 以下HTTP header类型不支持透传： 1. 以下前缀开头的header： 1. x-obs- 2. x-amz- 2. 所有标准HTTP header，例如： 1. Content-Length 2. Authorization 3. Date **取值范围：** - false：不透传全部HTTP header到源端 - true：透传全部HTTP header到源端 **默认取值：** false | | pass | 否 | Array | **参数解释：** 指定透传的HTTP header列表。最多展示10个HTTP header，每个HTTP header的长度范围是\[1, 63\]。数组元素的类型为Array Of Strings。 **约束限制：** 取值仅支持由大小写字母、数字、中划线、下划线组成。 **默认取值：** 不涉及 | | remove | 否 | Array | **参数解释：** 不允许透传的HTTP header列表，数组元素的类型为Array Of Strings。最多展示10个HTTP header，每个HTTP header的长度范围是\[1, 63\]。 **约束限制：** - remove优先级高于pass和passAll。 - 取值仅支持由大小写字母、数字、中划线、下划线组成。 **默认取值：** 不涉及 | | set | 否 | Array | **参数解释：** 设置透传的HTTP header值列表，数组元素的类型为Array Of Strings。Set最多展示10个HTTP header，每个HTTP header包含一个key和一个value。Key和Value的具体介绍请参见[Set参数说明]。 **约束限制：** - set优先级高于remove，pass和passAll。 - 如果自定义头域中包含了Referer头域，必须将redirectWithoutReferer设置为true，否则会被覆盖。 **默认取值：** 不涉及 | 表9Set参数说明 | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 否 | String | **参数解释：** 设置需要透传HTTP header的关键字。 **约束限制：** - 多条key之间不允许重复。 - 取值仅支持由大小写字母、数字、中划线、下划线组成。 **取值范围：** 长度为1\~63的字符串。 **默认取值：** 不涉及 | | value | 否 | String | **参数解释：** 设置需要透传HTTP header的值。 **约束限制：** 不涉及 **取值范围：** 长度为1\~2048的字符串。 **默认取值：** 不涉及 | #### 响应消息样式 ``` HTTP/1.1 status Server: OBS Date: date Content-Length: length ``` #### 响应头 (Response Headers) 该请求的响应消息使用公共响应头，具体请参考[表1](https://support.huaweicloud.com/api-obs/obs_04_0013.html#ZH-CN_TOPIC_0173612084__d0e686)。 #### 响应体 (Response Body) 该请求的响应消息中不带消息元素。 #### 错误响应消息 无特殊错误，所有错误已包含在[错误码概述](https://support.huaweicloud.com/api-obs/obs_04_0115.html)和[OEF错误码](https://support.huaweicloud.com/api-obs/obs_04_0115.html#ZH-CN_TOPIC_0000002510799800__table1490164511612)中。 #### 请求示例 ``` 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", "vpcEndpointURN": "001" } }] } ``` #### 响应示例 ``` HTTP/1.1 201 Created Server: OBS Date: Tue, 07 Jul 2020 07:29:13 GMT Content-Length: 0 ``` #### 相关文档 - 了解更多镜像回源相关信息，请参见[使用镜像回源获取源站数据](https://support.huaweicloud.com/usermanual-obs/obs_03_0006.html)。 - API操作涉及的计费项参见[计费项](https://support.huaweicloud.com/price-obs/obs_42_0002.html)。