# 设置镜像回源规则(Java SDK) #### 功能介绍 OBS提供数据回源功能，可以在被请求的数据不存在时，通过回源规则从源站获取对应数据。 #### 接口约束 表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权限。 | | **其他限制** | - 镜像回源暂时不收费。 - 如果一个请求同时满足镜像回源规则和重定向回源规则，OBS先执行镜像回源流程，如果源站没有该对象，则再执行重定向回源流程。 - 不允许多条镜像回源规则配置的文件名前缀存在相互包含或重叠的关系，即对同一个对象的请求不能同时匹配两条镜像回源规则。 - 针对镜像回源配置未遵循[RFC Range Requests标准](https://www.rfc-editor.org/rfc/rfc7233)的源站，客户在使用分段（Range）回源时，HTTP请求需携带Range头域并检查Range头域取值的有效性。 Range头域指定回源获取的内容范围，取值不能超过文件大小。例如，对大小为1024字节的对象做分段回源，可以指定回源前512字节（Range值为0\~511），Range值有效。指定回源2048个字节（Range值为0\~2047），超过对象大小，Range值无效，回源失败。 | #### 方法定义 obsClient.setBucketMirrorBackToSource(SetBucketMirrorBackToSourceRequest request) #### 请求参数说明 表2请求参数列表 | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | request | [表3 SetBucketMirrorBackToSourceRequest] | 必选 | **参数解释** **：** 设置镜像回源规则请求参数，详见[表3 SetBucketMirrorBackToSourceRequest]。 | 表3SetBucketMirrorBackToSourceRequest | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | bucketName | String | 必选 | **参数解释** **：** 桶名。 **约束限制：** - 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。 - 桶命名规则如下： - 3～63个字符，数字或字母开头，支持小写字母、数字、"-"、"."。 - 禁止使用IP地址。 - 禁止以"-"或"."开头及结尾。 - 禁止两个"."相邻（如："my..bucket"）。 - 禁止"."和"-"相邻（如："my-.bucket"和"my.-bucket"）。 - 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。 **默认取值：** 无 | | mirrorBackToSourceConfiguration | [表4 MirrorBackToSourceConfiguration] | 必选 | **参数解释：** 镜像回源配置，详见[表4 MirrorBackToSourceConfiguration] | 表4MirrorBackToSourceConfiguration | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | rules | List\<[表5 MirrorBackToSourceRule]\> | 必选 | **参数解释：** 镜像回源规则列表。 **约束限制：** 同一个桶下的不同规则前缀不能重复和起始包含，委托建议使用同一个。 **取值范围：** 因为每个桶最多创建10条镜像数据回源规则，所以数组长度的取值范围是\[1,10\]。具体请详见[表5 MirrorBackToSourceRule]。 **默认取值：** 不涉及 | 表5MirrorBackToSourceRule | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | id | String | 必选 | **参数解释：** 规则ID。当前桶上配置的镜像回源规则的唯一标识。 **约束限制：** 必须由以下字符组成"a-z"、"A-Z"、"0-9"、"-"、"_" **取值范围：** 长度最长为256的字符串。 **默认取值：** 无 | | condition | [表6 MirrorBackCondition] | 必选 | **参数解释：** 触发回源功能的条件。 **约束限制：** 不涉及 **取值范围：** 请详见[表6 MirrorBackCondition]。 **默认取值：** 不涉及 | | redirect | [表7 MirrorBackRedirect] | 必选 | **参数解释：** 实现回源功能的相关参数。 **约束限制：** 不涉及 **取值范围：** 请详见[表7 MirrorBackRedirect]。 **默认取值：** 不涉及 | 表6MirrorBackCondition | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | httpErrorCodeReturnedEquals | String | 必选 | **参数解释：** 触发回源功能的错误码。当下载请求返回此错误码时，会触发回源功能。 **约束限制：** 不涉及 **取值范围：** 404：指对象在OBS桶中不存在。 **默认取值：** 404 | | objectKeyPrefixEquals | String | 可选 | **参数解释：** 触发回源功能的对象名前缀。当触发回源的请求里对象名满足此前缀，才会继续执行回源功能。 **约束限制：** - 当前缀配置为空时，默认所有对象都匹配。 - 同一个桶上多条规则的前缀之间不允许重复和起始包含。 **取值范围：** 长度为0\~1023的字符串，值允许为任意字符。 **默认取值：** 不涉及 | 表7MirrorBackRedirect | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | agency | String | 必选 | **参数解释：** 委托名。客户通过委托赋予OBS服务"查询用户桶内指定对象是否存在"以及"向用户桶内上传对象"的权限。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | publicSource | [表8 MirrorBackPublicSource] | 可选 | **参数解释：** 公共可访问的源端配置。当源端为公共可访问的资源时，必选。publicSource是sourceEndpoint的父节点。 **约束限制：** 不涉及 **取值范围：** 请详见[表8 MirrorBackPublicSource]。 **默认取值：** 不涉及 | | vpcEndpointURN | String | 可选 | **参数解释：** 终端节点服务的URN。 **约束限制：** 不涉及 **取值范围：** 长度为0\~127的字符串。 **默认取值：** 不涉及 | | retryConditions | List\ | 可选 | **参数解释：** 回源地址切换的条件。 **约束限制：** 4XX和4开头的具体错误码不能同时配置，5XX和5开头的错误码不能同时配置。 **取值范围：** 最大支持同时配置20个错误码，如4XX，5XX以及400\~499，500\~599等具体错误码。 **默认取值：** 不涉及 | | passQueryString | Boolean | 必选 | **参数解释：** 是否携带请求字符串。 **约束限制：** 如果取值为true，但query参数里有签名信息，则将签名信息去掉，再传递剩余参数。 **取值范围：** - false：不会将OBS请求中的queryString传递到源站。 - true：会将OBS请求中的queryString传递到源站。 **默认取值：** false | | mirrorFollowRedirect | Boolean | 必选 | **参数解释：** 是否跟随源站3xx重定向请求获取到资源。 **约束限制：** 不涉及 **取值范围：** - false：OBS会透传3XX响应，不获取资源。 - true：跟随源站3XX重定向请求获取到资源。 **默认取值：** false | | mirrorHttpHeader | [表10 MirrorBackHttpHeader] | 可选 | **参数解释：** HTTP header传递规则。 **约束限制：** 不涉及 **取值范围：** 请详见[表10 MirrorBackHttpHeader]。 **默认取值：** 不涉及 | | replaceKeyWith | String | 可选 | **参数解释：** 去源端下载对象的时候是否添加前后缀。 **约束限制：** 如果replaceKeyWith和replaceKeyPrefixWith同时为空，则replaceKeyPrefixWith生效。同时非空为非法请求。 **取值范围：** - prefix${key}suffix：需要添加前缀或后缀。 - ${key}：不需要增加前缀或后缀。 ${key}为关键字，prefix为要添加的前缀，suffix为要添加的后缀。同时prefix和suffix的总长度为\[0, 1023\]。 **默认取值：** 不涉及 | | replaceKeyPrefixWith | String | 可选 | **参数解释：** 替换前缀objectKeyPrefixEquals的字符串。如果去源端下载对象时，需要替换当前的对象名前缀，则修改此项配置。 **约束限制：** 如果replaceKeyWith和replaceKeyPrefixWith同时为空，则replaceKeyPrefixWith生效。同时非空为非法请求。 **取值范围：** 长度为0\~1023的字符串。 **默认取值：** 不涉及 | | redirectWithoutReferer | Boolean | 可选 | **参数解释：** 是否将原host作为referer头域携带到重定向的目的地址去。 **约束限制：** 不涉及 **取值范围：** false：将原host作为referer头域携带到重定向的目的地址去。 true：不会将原host作为referer头域携带到重定向的目的地址去。 **默认取值：** false | | mirrorAllowHttpMethod | List\ | 可选 | **参数解释：** 支持透传的请求方法。 **约束限制：** 不涉及 **取值范围：** - GET：请求获取桶内对象。 - HEAD：请求获取桶内对象的元数据信息。 **默认取值：** 不涉及 | 表8MirrorBackPublicSource | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | sourceEndpoint | [表9 MirrorBackSourceEndpoint] | 可选 | **参数解释：** 公共可访问的源端地址。 **约束限制：** 不涉及 **取值范围：** 请详见[表9 MirrorBackSourceEndpoint]。 **默认取值：** 不涉及 | 表9MirrorBackSourceEndpoint | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | master | List\ | 可选 | **参数解释：** 主源端地址。如果源端为HTTP公共可访问的桶，则此地址为桶域名地址。如果源端为其他云厂商的私有桶，则此地址为区域域名地址。 **约束限制：** 回源时会优先使用主源站地址，如果同时配置1\~5个主地址，会轮询访问所有主地址。如果配置2个及以上主地址，第一次请求主地址失败，并且满足重试条件时，会选用另一个主地址重试一次。 **取值范围：** 单个源站地址的格式为https://xxx.yyy.zzz或http://xxx.yyy.zzz，长度为10\~255的字符串。 **默认取值：** 不涉及 | | slave | List\ | 可选 | **参数解释：** 备源端地址。如果源端为HTTP公共可访问的桶，则此地址为桶域名地址。如果源端为其他云厂商的私有桶，则此地址为区域域名地址。 **约束限制：** 主地址回源失败时，会选用一个备地址进行重试。最多同时配置5个备地址。 **取值范围：** 单个源站地址的格式为https://xxx.yyy.zzz或http://xxx.yyy.zzz，长度为10\~255的字符串。 **默认取值：** 不涉及 | 表10MirrorBackHttpHeader | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | 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 | List\ | 可选 | **参数解释：** 指定透传的HTTP header列表。 **约束限制：** 取值仅支持由大小写字母、数字、中划线、下划线组成。 **取值范围：** 最多展示10个HTTP header，每个HTTP header的长度范围是\[1, 63\]。 **默认取值：** 不涉及 | | remove | List\ | 可选 | **参数解释：** 不允许透传的HTTP header列表。 **约束限制：** - remove优先级高于pass和passAll。 - 取值仅支持由大小写字母、数字、中划线、下划线组成。 **取值范围：** 最多展示10个HTTP header，每个HTTP header的长度范围是\[1, 63\]。 **默认取值：** 不涉及 | | set | List\<[表11 MirrorBackHttpHeaderSet]\> | 可选 | **参数解释：** 设置透传的HTTP header值列表。 **约束限制：** - set优先级高于remove，pass和passAll。 - 如果自定义头域中包含了Referer头域，必须将redirectWithoutReferer设置为true，否则会被覆盖。 **取值范围：** set最多展示10个HTTP header，每个HTTP header包含一个key和一个value。key和value的具体介绍请参见[表11 MirrorBackHttpHeaderSet]。 **默认取值：** 不涉及 | 表11MirrorBackHttpHeaderSet | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | key | String | 可选 | **参数解释：** 设置需要透传HTTP header的关键字。 **约束限制：** - 多条key之间不允许重复。 - 取值仅支持由大小写字母、数字、中划线、下划线组成。 **取值范围：** 长度为1\~63的字符串。 **默认取值：** 不涉及 | | value | String | 可选 | **参数解释：** 设置需要透传HTTP header的值。 **约束限制：** 不涉及 **取值范围：** 长度为1\~2048的字符串。 **默认取值：** 不涉及 | #### 返回结果说明 表12返回结果HeaderResponse(SDK公共响应结果)各项属性说明 | **参数名称** | **参数类型** | **描述** | |:---|:---|:---| | statusCode | int | **参数解释：** HTTP状态码。 **取值范围：** 状态码是一组从2xx（成功）到4xx或5xx（错误）的数字代码，状态码表示了请求响应的状态。 完整的状态码列表请参见[状态码](https://support.huaweicloud.com/api-obs/obs_04_0114.html)。 **默认取值：** 无 | | responseHeaders | Map\ | **参数解释：** HTTP响应消息头列表，由多个元组构成。元组中String代表响应消息头的名称，Object代表响应消息头的值。 **默认取值：** 无 | #### 代码示例 本示例用于设置examplebucket桶的镜像回源配置。 ``` import com.obs.services.ObsClient; import com.obs.services.exception.ObsException; import com.obs.services.model.mirrorback.MirrorBackCondition; import com.obs.services.model.mirrorback.MirrorBackHttpHeader; import com.obs.services.model.mirrorback.MirrorBackHttpHeaderSet; import com.obs.services.model.mirrorback.MirrorBackPublicSource; import com.obs.services.model.mirrorback.MirrorBackRedirect; import com.obs.services.model.mirrorback.MirrorBackSourceEndpoint; import com.obs.services.model.mirrorback.MirrorBackToSourceConfiguration; import com.obs.services.model.mirrorback.MirrorBackToSourceRule; import com.obs.services.model.mirrorback.SetBucketMirrorBackToSourceRequest; import java.util.Arrays; import java.util.Collections; public class SetBucketMirrorBackToSource { public static void main(String[] args) { // 您可以通过环境变量获取访问密钥AK/SK，也可以使用其他外部引入方式传入。如果使用硬编码可能会存在泄露风险。 // 您可以登录访问管理控制台获取访问密钥AK/SK String ak = System.getenv("ACCESS_KEY_ID"); String sk = System.getenv("SECRET_ACCESS_KEY_ID"); // 【可选】如果使用临时AK/SK和SecurityToken访问OBS，同样建议您尽量避免使用硬编码，以降低信息泄露风险。 // 您可以通过环境变量获取访问密钥AK/SK/SecurityToken，也可以使用其他外部引入方式传入。 String securityToken = System.getenv("SECURITY_TOKEN"); // endpoint填写桶所在的endpoint, 此处以华北-北京四为例，其他地区请按实际情况填写。 // 您可以通过环境变量获取endPoint，也可以使用其他外部引入方式传入。 String endPoint = System.getenv("ENDPOINT"); ObsConfiguration obsConfiguration = new ObsConfiguration(); obsConfiguration.setEndPoint(endPoint); ObsClient obsClient = new ObsClient(ak, sk, securityToken, obsConfiguration); try { String exampleBucket = "examplebucket"; // Step 1: 指定触发回源功能的条件 MirrorBackCondition condition = new MirrorBackCondition(); // 触发回源功能的错误码，当下载请求返回此错误码时，会触发回源功能 condition.setHttpErrorCodeReturnedEquals("404"); // 触发回源功能的对象名前缀，当触发回源的请求里对象名满足此前缀，才会继续执行回源功能 condition.setObjectKeyPrefixEquals("images/"); // Step 2【可选】: 指定公共可访问的源端地址 MirrorBackSourceEndpoint endpoint = new MirrorBackSourceEndpoint(); // 主源端地址。如果源端为HTTP公共可访问的桶，则此地址为桶域名地址。如果源端为其他云厂商的私有桶，则此地址为区域域名地址 endpoint.setMaster(Collections.singletonList("https://source-bucket.obs.example.com")); // 备源端地址。如果源端为HTTP公共可访问的桶，则此地址为桶域名地址。如果源端为其他云厂商的私有桶，则此地址为区域域名地址 endpoint.setSlave(Collections.singletonList("https://backup-bucket.obs.example.com")); MirrorBackPublicSource publicSource = new MirrorBackPublicSource(); publicSource.setSourceEndpoint(endpoint); // Step 3: 指定HTTP header传递规则 MirrorBackHttpHeader httpHeader = new MirrorBackHttpHeader(); // 是否透传全部HTTP header到源端 httpHeader.setPassAll(false); // 指定透传的HTTP header列表 httpHeader.setPass(Arrays.asList("content-type", "cache-control")); // 不允许透传的HTTP header列表 httpHeader.setRemove(Collections.singletonList("authorization")); // 设置透传的HTTP header值列表, set优先级高于remove，pass和passAll httpHeader.setSet(Collections.singletonList( new MirrorBackHttpHeaderSet("x-custom-header", "custom-value"))); // Step 4: 指定实现回源功能的相关参数 MirrorBackRedirect redirect = new MirrorBackRedirect(); // 委托名。客户通过委托赋予OBS服务“查询用户桶内指定对象是否存在”以及“向用户桶内上传对象”的权限 redirect.setAgency("your-agency"); // 公共可访问的源端配置。当源端为公共可访问的资源时，必选。publicSource是sourceEndpoint的父节点 redirect.setPublicSource(publicSource); // 是否携带请求字符串 redirect.setPassQueryString(true); // 是否跟随源站3xx重定向请求获取到资源 redirect.setMirrorFollowRedirect(false); // 指定HTTP header传递规则，即Step 3 redirect.setMirrorHttpHeader(httpHeader); // 替换前缀objectKeyPrefixEquals的字符串。如果去源端下载对象时，需要替换当前的对象名前缀，则修改此项配置 redirect.setReplaceKeyPrefixWith("backup/"); // 支持透传的请求方法 redirect.setMirrorAllowHttpMethod(Arrays.asList("GET", "HEAD")); // Step 5: 指定单条回源规则 MirrorBackToSourceRule rule = new MirrorBackToSourceRule(); rule.setId("mirror-rule-001"); // 指定触发回源功能的条件,即Step 1 rule.setCondition(condition); // 实现回源功能的相关参数，即Step 4 rule.setRedirect(redirect); // Step 6: 指定镜像回源规则列表 MirrorBackToSourceConfiguration policyConfig = new MirrorBackToSourceConfiguration(); policyConfig.setRules(Collections.singletonList(rule)); // Step 7: 发送请求 SetBucketMirrorBackToSourceRequest request = new SetBucketMirrorBackToSourceRequest(exampleBucket, policyConfig); obsClient.setBucketMirrorBackToSource(request); System.out.println("SetBucketMirrorBackToSource successfully"); } catch (ObsException e) { System.out.println("SetBucketMirrorBackToSource failed"); // 请求失败,打印http状态码 System.out.println("HTTP Code:" + e.getResponseCode()); // 请求失败,打印服务端错误码 System.out.println("Error Code:" + e.getErrorCode()); // 请求失败,打印详细错误信息 System.out.println("Error Message:" + e.getErrorMessage()); // 请求失败,打印请求id System.out.println("Request ID:" + e.getErrorRequestId()); System.out.println("Host ID:" + e.getErrorHostId()); e.printStackTrace(); } catch (Exception e) { System.out.println("SetBucketMirrorBackToSource failed"); // 其他异常信息打印 e.printStackTrace(); } } } ``` #### 相关链接 - 更多示例代码，请参见[Github示例](https://github.com/huaweicloud/huaweicloud-sdk-java-obs/blob/master/app/src/test/java/samples_java/PFSBucketAndObjectOperationSample.java)。 - 设置镜像回源规则过程中返回的错误码含义、问题原因及处理措施可参考[OBS错误码](https://support.huaweicloud.com/api-obs/obs_04_0115.html#section1)。