文档首页/ 对象存储服务 OBS/ SDK参考/ Harmony（公测）/ 桶相关接口(HarmonyOS SDK)/ 镜像回源/ 设置镜像回源规则(HarmonyOS SDK)
更新时间：2026-08-28 GMT+08:00
查看PDF
分享

设置镜像回源规则(HarmonyOS SDK)

功能说明

镜像回源是OBS提供的一种数据自动获取功能。调用设置桶镜像回源规则接口，您可为指定桶配置镜像回源规则，当客户端访问桶中不存在的对象时，OBS会自动从源站获取数据并返回给客户端，同时将数据存储到桶中。

接口约束

  • 您必须是桶拥有者或拥有设置桶镜像回源规则的权限，才能设置桶镜像回源规则。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:bucket:PutBucketMirrorBackToSource权限，如果使用桶策略则需授予PutBucketMirrorBackToSource权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、自定义创建桶策略。
  • OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。
  • 每个桶最多配置10条镜像回源规则。
  • 规则ID在桶内必须唯一。

方法定义

1
 
setBucketMirrorBackToSource(input: SetBucketMirrorBackToSourceInput): Response<BaseResponseOutput>

请求参数

表1 请求参数列表

参数名称

参数类型

是否必选

描述

input

SetBucketMirrorBackToSourceInput

必选

参数解释：

设置桶镜像回源规则接口入参，详见SetBucketMirrorBackToSourceInput。
表2 SetBucketMirrorBackToSourceInput

参数名称

参数类型

是否可选

描述

Bucket

string

必选

桶名。

约束限制：

  • 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。
  • 桶命名规则如下：
    • 3～63个字符，数字或字母开头，支持小写字母、数字、“-”、“.”。
    • 禁止使用IP地址。
    • 禁止以“-”或“.”开头及结尾。
    • 禁止两个“.”相邻（如：“my..bucket”）。
    • 禁止“.”和“-”相邻（如：“my-.bucket”和“my.-bucket”）。
  • 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。

取值范围：

长度为3～63个字符。

Rules

string

必选

参数解释：

策略规则数组。

约束限制：

同一个桶下的不同策略前缀不能重复和起始包含，委托建议使用同一个。

默认取值：

因为每个桶最多创建10条镜像数据回源规则，所以数组长度的取值范围是[1,10]。

默认取值：

不涉及

返回结果

表3 返回结果

参数类型

描述

Response

说明：

该接口返回一个Promise类型，需要使用Promise、async/await语法处理。

参数解释：

接口返回信息，详见Response。
表4 Response

参数名称

参数类型

描述

CommonMsg

ICommonMsg

参数解释：

接口调用完成后的公共信息，包含HTTP状态码，操作失败的错误码等，详见ICommonMsg。

InterfaceResult

BaseResponseOutput

参数解释：

操作成功后的结果数据，详见BaseResponseOutput。

约束限制：

当Status大于300时为空。
表5 ICommonMsg

参数名称

参数类型

描述

Status

number

参数解释：

OBS服务端返回的HTTP状态码。

取值范围：

状态码是一组从2xx（成功）到4xx或5xx（错误）的数字代码，状态码表示了请求响应的状态。完整的状态码列表请参见状态码。

Code

string

参数解释：

OBS服务端返回的错误码。

Message

string

参数解释：

OBS服务端返回的错误描述。

HostId

string

参数解释：

OBS服务端返回的请求服务端ID。

RequestId

string

参数解释：

OBS服务端返回的请求ID。

Id2

string

参数解释：

OBS服务端返回的请求ID2。

Indicator

string

参数解释：

OBS服务端返回的详细错误码。
表6 BaseResponseOutput

参数名称

参数类型

描述

RequestId

string

参数解释：

OBS服务端返回的请求ID。

Id2

string

参数解释：

OBS服务端返回的请求ID2。

代码示例

本示例用于设置 examplebucket 桶的镜像回源规则，对 image/ 前缀对象回源到镜像源。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
// 引入依赖包
import ObsClient, { SetBucketMirrorBackToSourceInput } from '@obs/esdk-obs-harmony';
import { process } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const processManager = new process.ProcessManager();

// 定义镜像回源规则结构
interface MirrorBackCondition {
  keyPrefixEquals: string;
}
interface MirrorBackRedirect {
  mirrorURL: string;
}
interface MirrorBackRule {
  condition: MirrorBackCondition;
  redirect: MirrorBackRedirect;
}
interface MirrorBackConfig {
  rules: MirrorBackRule[];
}

// 创建ObsClient实例
const obsClient = new ObsClient({
  // 推荐通过环境变量获取AKSK，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险
  AccessKeyId: processManager.getEnvironmentVar("ACCESS_KEY_ID"),
  SecretAccessKey: processManager.getEnvironmentVar("SECRET_ACCESS_KEY"),
  // Server填写桶所在区域的endpoint
  Server: "https://your-endpoint"
});

async function setBucketMirrorBackToSource() {
  try {
    const config: MirrorBackConfig = {
      rules: [
        {
          condition: { keyPrefixEquals: "image/" },
          redirect: { mirrorURL: "http://mirror.example.com" }
        }
      ]
    };
    const rules = JSON.stringify(config);
    const params: SetBucketMirrorBackToSourceInput = {
      Bucket: "examplebucket",
      Rules: rules,
    };
    const result = await obsClient.setBucketMirrorBackToSource(params);
    if (result.CommonMsg.Status < 300) {
      hilog.info(0x0001, 'OBS-Harmony', "Set bucket mirror back to source(%s) successful!", params.Bucket);
      hilog.info(0x0001, 'OBS-Harmony', "RequestId: %s", result.CommonMsg.RequestId);
      return;
    }
    hilog.error(0x0001, 'OBS-Harmony', 'An ObsError was found, which means your request sent to OBS was rejected with an error response.');
    hilog.error(0x0001, 'OBS-Harmony', "Status: %d", result.CommonMsg.Status);
    hilog.error(0x0001, 'OBS-Harmony', "Code: %s", result.CommonMsg.Code);
    hilog.error(0x0001, 'OBS-Harmony', "Message: %s", result.CommonMsg.Message);
  } catch (error) {
    const err = error as BusinessError;
    hilog.error(0x0001, 'OBS-Harmony', 'An Exception occurred: code=%d, message: %s', err.code, err.message);
  }
}

setBucketMirrorBackToSource();

相关链接

  • 关于设置桶镜像回源规则的API说明，请参见设置桶镜像回源规则。
  • 设置桶镜像回源规则过程中返回的错误码含义、问题原因及处理措施可参考OBS错误码。
父主题： 镜像回源

相关文档