文档中心

管理镜像回源（Java SDK）

最近更新时间：2024.02.04 18:31:02

首次发布时间：2023.01.19 14:37:15

桶（Bucket）是 TOS 的全局唯一的命名空间，相当于数据的容器，用来储存对象（Object）数据。当请求桶中的对象数据不存在时，TOS 默认返回 404 错误。但如果您设置了桶的回源规则，填写了对象数据的正确地址，TOS 将会通过回源规则从源站获取数据。TOS 支持镜像回源和重定向回源两种方式，可以满足您对于数据热迁移、特定请求的重定向等需求。
本文介绍如何通过 TOS Java SDK 管理桶的回源规则。

设置镜像回源规则

您可以通过 TOS Java SDK 的 putBucketMirrorBack 接口设置指定桶的回源规则。

注意

要为桶设置镜像回源规则，默认您必须为桶所有者。
一个存储桶仅支持创建一条回源规则。
镜像回源最大能够支持 5GiB 的对象。如果需要请求超过 5GiB 的对象，请使用 Get Range 的功能。
重定向回源最大能够支持 300GiB。
关于镜像回源的更多信息，请参见设置镜像回源规则。

示例代码

以下代码展示如何设置指定桶的镜像回源规则。

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.comm.common.RedirectType;
import com.volcengine.tos.model.bucket.*;

import java.util.ArrayList;
import java.util.List;

public class PutBucketMirrorBackExample {
    public static void main(String[] args) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");

        String bucketName = "your bucket name";

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);

        try{
            // 设置回源条件，比如在返回 404 后回源
            Condition condition = new Condition().setHttpCode(404);
            // 指定镜像回源携带的header
            List<String> passList = new ArrayList<>();
            passList.add("pass_header1");
            passList.add("pass_header2");
            List<String> removeList = new ArrayList<>();
            removeList.add("remove_header1");
            removeList.add("remove_header2");
            MirrorHeader mirrorHeader = new MirrorHeader().setPassAll(true)
                    .setPass(passList).setRemove(removeList);

            // 配置公共可访问的源端配置
            List<String> primary = new ArrayList<>();
            primary.add("http://www.volcengine.com/obj/tostest/1");
            List<String> follower = new ArrayList<>();
            follower.add("http://www.volcengine.com/obj/tostest/2");
            SourceEndpoint sourceEndpoint = new SourceEndpoint().setPrimary(primary).setFollower(follower);
            PublicSource publicSource = new PublicSource().setSourceEndpoint(sourceEndpoint);
            // 设置重定向后执行的动作
            Redirect redirect = new Redirect()
                    .setRedirectType(RedirectType.REDIRECT_MIRROR)
                    // 表明重定向后是否去配置的源站拉取信息
                    .setFetchSourceOnRedirect(true)
                    // 执行跳转或者镜像回源规则时，是否携带请求参数
                    .setPassQuery(true)
                    // 镜像回源获取的结果为 3xx 时，是否继续跳转到指定的 Location 获取数据
                    .setFollowRedirect(true)
                    .setMirrorHeader(mirrorHeader)
                    .setPublicSource(publicSource);
            MirrorBackRule rule = new MirrorBackRule().setId("1").setCondition(condition).setRedirect(redirect);
            List<MirrorBackRule> rules = new ArrayList<>();
            rules.add(rule);
            PutBucketMirrorBackInput input = new PutBucketMirrorBackInput().setBucket(bucketName).setRules(rules);
            PutBucketMirrorBackOutput output = tos.putBucketMirrorBack(input);
            System.out.println("putBucketMirrorBack succeed");
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("putBucketMirrorBack failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("putBucketMirrorBack failed");
            System.out.println("StatusCode: " + e.getStatusCode());
            System.out.println("Code: " + e.getCode());
            System.out.println("Message: " + e.getMessage());
            System.out.println("RequestID: " + e.getRequestID());
        } catch (Throwable t) {
            // 作为兜底捕获其他异常，一般不会执行到这里
            System.out.println("putBucketMirrorBack failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

获取镜像回源规则

您可以通过 TOS Java SDK 的 getBucketMirrorBack 接口获取指定桶当前配置的回源规则。

注意

要获取桶的镜像回源规则，默认您必须为桶所有者。
关于镜像回源的更多信息，请参见设置镜像回源规则。

示例代码

以下代码展示如何获取指定桶的镜像回源规则。

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.model.bucket.GetBucketMirrorBackInput;
import com.volcengine.tos.model.bucket.GetBucketMirrorBackOutput;
import com.volcengine.tos.model.bucket.MirrorBackRule;

public class GetBucketMirrorBackExample {
    public static void main(String[] args) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");

        String bucketName = "your bucket name";

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);

        try{
            GetBucketMirrorBackInput input = new GetBucketMirrorBackInput().setBucket(bucketName);
            GetBucketMirrorBackOutput output = tos.getBucketMirrorBack(input);
            System.out.println("getBucketMirrorBack succeed");
            if (output.getRules() != null) {
                System.out.println("this bucket has " + output.getRules().size() + " mirror back rules");
                for (int i = 0; i < output.getRules().size(); i++){
                    MirrorBackRule rule = output.getRules().get(i);
                    System.out.println("No." + (i+1) + " rule is " + rule.toString());
                }
            }
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("getBucketMirrorBack failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("getBucketMirrorBack failed");
            System.out.println("StatusCode: " + e.getStatusCode());
            System.out.println("Code: " + e.getCode());
            System.out.println("Message: " + e.getMessage());
            System.out.println("RequestID: " + e.getRequestID());
        } catch (Throwable t) {
            // 作为兜底捕获其他异常，一般不会执行到这里
            System.out.println("getBucketMirrorBack failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

删除桶的镜像回源规则

您可以通过 TOS Java SDK 的 deleteBucketMirrorBack 接口删除指定桶当前配置的回源规则。

注意

要删除桶的镜像回源规则，默认您必须为桶所有者。
关于镜像回源的更多信息，请参见设置镜像回源规则。

示例代码

以下代码展示如何删除指定桶的镜像回源规则。

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.model.bucket.DeleteBucketMirrorBackInput;
import com.volcengine.tos.model.bucket.DeleteBucketMirrorBackOutput;

public class DeleteBucketMirrorBackExample {
    public static void main(String[] args) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");
        String bucketName = "your bucket name";

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);

        try{
            DeleteBucketMirrorBackInput input = new DeleteBucketMirrorBackInput().setBucket(bucketName);
            DeleteBucketMirrorBackOutput output = tos.deleteBucketMirrorBack(input);
            System.out.println("deleteBucketMirrorBack succeed, " + output);
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("deleteBucketMirrorBack failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("deleteBucketMirrorBack failed");
            System.out.println("StatusCode: " + e.getStatusCode());
            System.out.println("Code: " + e.getCode());
            System.out.println("Message: " + e.getMessage());
            System.out.println("RequestID: " + e.getRequestID());
        } catch (Throwable t) {
            // 作为兜底捕获其他异常，一般不会执行到这里
            System.out.println("deleteBucketMirrorBack failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

对象存储

管理镜像回源（Java SDK）

设置镜像回源规则

示例代码

获取镜像回源规则

示例代码

删除桶的镜像回源规则

示例代码

相关文档