You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /对象存储/SDK 参考/Java/对象接口/列举对象/列举多版本对象（Java SDK）
列举多版本对象（Java SDK）
最近更新时间：2024.02.04 18:30:54首次发布时间：2021.11.27 17:58:44
我的收藏

TOS Java SDK 的 listObjectVersions 接口用于列举桶中的多版本对象。本文介绍如何通过 listObjectVersions 接口简单列举指定桶中的多版本对象、列举所有多版本对象、列举包含指定前缀的多版本对象、列举指定目录下的多版本对象和子目录等。

注意事项

要列举多版本对象，您的账号必须具备 tos:ListBucketVersions 权限，具体操作请参见 IAM 策略概述。

参数说明

listObjectVersions 接口支持的参数如下。

参数

描述

prefix

本次查询结果的前缀。

delimiter

对对象名称进行分组的字符。

keyMarker

此次列举对象的起点。初始为 null，后续可取值为上次请求返回的 nextKeyMarker。

versionIDMarker

与 keyMarker 配合使用。初始为 null，后续可取值为上次请求返回的 nextVersionIDMarker。

maxKeys

返回列举对象的最大数。一次最多返回 1000 条结果，若不设置则默认返回 1000 条。

encodingType

对返回的内容进行编码并指定编码的类型。

示例代码

简单列举

以下代码展示如何列举桶 bucket-example 中最多 10 个多版本对象。

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.object.*;

public class ListObjectVersionsBasicExample {
    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 = "bucket-example";
        int maxKeys = 10;

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);
        try{
            ListObjectVersionsV2Input input = new ListObjectVersionsV2Input().setBucket(bucketName)
                    .setMaxKeys(maxKeys);
            ListObjectVersionsV2Output output = tos.listObjectVersions(input);
            System.out.printf("listObjectVersions succeed, is truncated? %b, next key marker is %s, " + 
                            "next version id marker is %s.\n", output.isTruncated(), 
                    output.getNextKeyMarker(), output.getNextVersionIDMarker());
            if (output.getVersions() != null) {
                for (int i = 0; i < output.getVersions().size(); i++) {
                    ListedObjectVersion object = output.getVersions().get(i);
                    System.out.printf("Listed object version, key is %s, size is %d, versionId is %s, " + 
                                        "storageClass is %s, ETag is %s, last modified is %s, isLatest? %b.\n", 
                                object.getKey(), object.getSize(), object.getVersionID(), object.getStorageClass(), 
                                object.getEtag(), object.getLastModified(), object.isLatest());
                }
            }
            if (output.getCommonPrefixes() != null) {
                for (int i = 0; i < output.getCommonPrefixes().size(); i++) {
                    ListedCommonPrefix commonPrefix = output.getCommonPrefixes().get(i);
                    System.out.println("Listed commonPrefix is " + commonPrefix.getPrefix());
                }
            }
            if (output.getDeleteMarkers() != null) {
                for (int i = 0; i < output.getDeleteMarkers().size(); i++) {
                    ListedDeleteMarkerEntry deleteMarker = output.getDeleteMarkers().get(i);
                    System.out.printf("Listed deleteMarker is %s\n", deleteMarker);
                }
            }
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("listObjectVersions failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("listObjectVersions 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("listObjectVersions failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

分页列举

以下代码展示如何分页列举桶 bucket-example 中的多版本对象。

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.object.*;

public class ListObjectVersionsByPageExample {
    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 = "bucket-example";
        int maxKeys = 10;

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);
        try{
            ListObjectVersionsV2Input input = new ListObjectVersionsV2Input().setBucket(bucketName)
                    .setMaxKeys(maxKeys);
            ListObjectVersionsV2Output output = tos.listObjectVersions(input);
            System.out.printf("listObjectVersions succeed, is truncated? %b, next key marker is %s, " +
                            "next version id marker is %s.\n", output.isTruncated(),
                    output.getNextKeyMarker(), output.getNextVersionIDMarker());
            if (output.getVersions() != null) {
                for (int i = 0; i < output.getVersions().size(); i++) {
                    ListedObjectVersion object = output.getVersions().get(i);
                    System.out.printf("Listed object version, key is %s, size is %d, versionId is %s, " + 
                                        "storageClass is %s, ETag is %s, last modified is %s, isLatest? %b.\n", 
                                object.getKey(), object.getSize(), object.getVersionID(), object.getStorageClass(), 
                                object.getEtag(), object.getLastModified(), object.isLatest());
                }
            }
            if (output.getCommonPrefixes() != null) {
                for (int i = 0; i < output.getCommonPrefixes().size(); i++) {
                    ListedCommonPrefix commonPrefix = output.getCommonPrefixes().get(i);
                    System.out.println("Listed commonPrefix is " + commonPrefix.getPrefix());
                }
            }
            if (output.getDeleteMarkers() != null) {
                for (int i = 0; i < output.getDeleteMarkers().size(); i++) {
                    ListedDeleteMarkerEntry deleteMarker = output.getDeleteMarkers().get(i);
                    System.out.printf("Listed deleteMarker is %s\n", deleteMarker);
                }
            }
            if (output.isTruncated()) {
                // isTruncated 为 true 说明接下来还有数据，可以继续列举
                // 下一页的列举需要设置上一次列举返回的 keyMarker 和 versionIdMarker，需要同时设置
                input.setKeyMarker(output.getNextKeyMarker()).setVersionIDMarker(output.getNextVersionIDMarker());
                output = tos.listObjectVersions(input);
                System.out.printf("listObjectVersions succeed, is truncated? %b, next key marker is %s, " +
                                "next version id marker is %s.\n", output.isTruncated(),
                        output.getNextKeyMarker(), output.getNextVersionIDMarker());
                if (output.getVersions() != null) {
                    for (int i = 0; i < output.getVersions().size(); i++) {
                        ListedObjectVersion object = output.getVersions().get(i);
                        System.out.printf("Listed object version, key is %s, size is %d, versionId is %s, " + 
                                        "storageClass is %s, ETag is %s, last modified is %s, isLatest? %b.\n", 
                                object.getKey(), object.getSize(), object.getVersionID(), object.getStorageClass(), 
                                object.getEtag(), object.getLastModified(), object.isLatest());
                    }
                }
                if (output.getCommonPrefixes() != null) {
                    for (int i = 0; i < output.getCommonPrefixes().size(); i++) {
                        ListedCommonPrefix commonPrefix = output.getCommonPrefixes().get(i);
                        System.out.println("Listed commonPrefix is " + commonPrefix.getPrefix());
                    }
                }
                if (output.getDeleteMarkers() != null) {
                    for (int i = 0; i < output.getDeleteMarkers().size(); i++) {
                        ListedDeleteMarkerEntry deleteMarker = output.getDeleteMarkers().get(i);
                        System.out.printf("Listed deleteMarker is %s\n", deleteMarker);
                    }
                }
            }
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("listObjectVersions failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("listObjectVersions 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("listObjectVersions failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

列举指定前缀的所有多版本对象

以下代码展示如何列举桶 bucket-example 中指定前缀的所有多版本对象。

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.object.*;

public class ListObjectVersionsByPrefixExample {
    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 = "bucket-example";
        int maxKeys = 10;
        String prefix = "example_dir/";

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);
        try{
            boolean isTruncated = true;
            String keyMarker = null;
            String versionIdMarker = null;
            while (isTruncated) {
                ListObjectVersionsV2Input input = new ListObjectVersionsV2Input().setBucket(bucketName)
                        .setMaxKeys(maxKeys).setPrefix(prefix).setKeyMarker(keyMarker).setVersionIDMarker(versionIdMarker);
                ListObjectVersionsV2Output output = tos.listObjectVersions(input);
                System.out.printf("listObjectVersions succeed, is truncated? %b, next key marker is %s, " +
                                "next version id marker is %s.\n", output.isTruncated(),
                        output.getNextKeyMarker(), output.getNextVersionIDMarker());
                if (output.getVersions() != null) {
                    for (int i = 0; i < output.getVersions().size(); i++) {
                        ListedObjectVersion object = output.getVersions().get(i);
                        System.out.printf("Listed object version, key is %s, size is %d, versionId is %s, " +
                                        "storageClass is %s, ETag is %s, last modified is %s, isLatest? %b.\n",
                                object.getKey(), object.getSize(), object.getVersionID(), object.getStorageClass(),
                                object.getEtag(), object.getLastModified(), object.isLatest());
                    }
                }
                if (output.getCommonPrefixes() != null) {
                    for (int i = 0; i < output.getCommonPrefixes().size(); i++) {
                        ListedCommonPrefix commonPrefix = output.getCommonPrefixes().get(i);
                        System.out.println("Listed commonPrefix is " + commonPrefix.getPrefix());
                    }
                }
                if (output.getDeleteMarkers() != null) {
                    for (int i = 0; i < output.getDeleteMarkers().size(); i++) {
                        ListedDeleteMarkerEntry deleteMarker = output.getDeleteMarkers().get(i);
                        System.out.printf("Listed deleteMarker is %s\n", deleteMarker);
                    }
                }
                isTruncated = output.isTruncated();
                keyMarker = output.getNextKeyMarker();
                versionIdMarker = output.getNextVersionIDMarker();
            }
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("listObjectVersions failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("listObjectVersions 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("listObjectVersions failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

列举桶内所有多版本对象

以下代码展示如何列举桶 bucket-example 中所有多版本对象。

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.object.*;

public class ListObjectVersionsAllObjectExample {
    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 = "bucket-example";
        int maxKeys = 10;

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);
        try{
            boolean isTruncated = true;
            String keyMarker = null;
            String versionIdMarker = null;
            while (isTruncated) {
                ListObjectVersionsV2Input input = new ListObjectVersionsV2Input().setBucket(bucketName)
                        .setMaxKeys(maxKeys).setKeyMarker(keyMarker).setVersionIDMarker(versionIdMarker);
                ListObjectVersionsV2Output output = tos.listObjectVersions(input);
                System.out.printf("listObjectVersions succeed, is truncated? %b, next key marker is %s, " +
                                "next version id marker is %s.\n", output.isTruncated(),
                        output.getNextKeyMarker(), output.getNextVersionIDMarker());
                if (output.getVersions() != null) {
                    for (int i = 0; i < output.getVersions().size(); i++) {
                        ListedObjectVersion object = output.getVersions().get(i);
                        System.out.printf("Listed object version, key is %s, size is %d, versionId is %s, " + 
                                        "storageClass is %s, ETag is %s, last modified is %s, isLatest? %b.\n", 
                                object.getKey(), object.getSize(), object.getVersionID(), object.getStorageClass(), 
                                object.getEtag(), object.getLastModified(), object.isLatest());
                    }
                }
                if (output.getCommonPrefixes() != null) {
                    for (int i = 0; i < output.getCommonPrefixes().size(); i++) {
                        ListedCommonPrefix commonPrefix = output.getCommonPrefixes().get(i);
                        System.out.println("Listed commonPrefix is " + commonPrefix.getPrefix());
                    }
                }
                if (output.getDeleteMarkers() != null) {
                    for (int i = 0; i < output.getDeleteMarkers().size(); i++) {
                        ListedDeleteMarkerEntry deleteMarker = output.getDeleteMarkers().get(i);
                        System.out.printf("Listed deleteMarker is %s\n", deleteMarker);
                    }
                }
                isTruncated = output.isTruncated();
                keyMarker = output.getNextKeyMarker();
                versionIdMarker = output.getNextVersionIDMarker();
            }
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("listObjectVersions failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("listObjectVersions 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("listObjectVersions failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

列举指定目录下的多版本对象和子目录

TOS 只有对象的概念, 可通过创建一个大小为 0 并且以斜线 / 结尾的对象, 模拟目录的功能。
通过 Delimiter 和 Prefix 两个参数可以模拟目录的功能:

  • 首先设置 Delimiter 为 / 同时设置 Prefix 为空, 可返回根目录下的对象和子目录信息。
  • 在设置 Delimiter 为 / 同时设置 Prefix 为子目录(commonPrefixes), 可返回子目录的对象和次级目录。

以下代码展示如何列举桶 bucket-example 根目录下的多版本对象和子目录。

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.object.*;

public class ListObjectVersionsByDelimiterExample {
    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 = "bucket-example";
        int maxKeys = 10;
        String delimiter = "/";

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);
        try{
            boolean isTruncated = true;
            String keyMarker = null;
            String versionIdMarker = null;
            while (isTruncated) {
                ListObjectVersionsV2Input input = new ListObjectVersionsV2Input().setBucket(bucketName)
                        .setMaxKeys(maxKeys).setDelimiter(delimiter).setKeyMarker(keyMarker).setVersionIDMarker(versionIdMarker);
                ListObjectVersionsV2Output output = tos.listObjectVersions(input);
                System.out.printf("listObjectVersions succeed, is truncated? %b, next key marker is %s, " +
                                "next version id marker is %s.\n", output.isTruncated(),
                        output.getNextKeyMarker(), output.getNextVersionIDMarker());
                if (output.getVersions() != null) {
                    for (int i = 0; i < output.getVersions().size(); i++) {
                        ListedObjectVersion object = output.getVersions().get(i);
                        System.out.printf("Listed object version, key is %s, size is %d, versionId is %s, " +
                                        "storageClass is %s, ETag is %s, last modified is %s, isLatest? %b.\n",
                                object.getKey(), object.getSize(), object.getVersionID(), object.getStorageClass(),
                                object.getEtag(), object.getLastModified(), object.isLatest());
                    }
                }
                if (output.getCommonPrefixes() != null) {
                    for (int i = 0; i < output.getCommonPrefixes().size(); i++) {
                        ListedCommonPrefix commonPrefix = output.getCommonPrefixes().get(i);
                        System.out.println("Listed commonPrefix is " + commonPrefix.getPrefix());
                        // commonPrefix 为子目录，可用其作为 prefix 参数继续往下列举
                        listCommonPrefix(bucketName, maxKeys, delimiter, commonPrefix.getPrefix(), tos);
                    }
                }
                if (output.getDeleteMarkers() != null) {
                    for (int i = 0; i < output.getDeleteMarkers().size(); i++) {
                        ListedDeleteMarkerEntry deleteMarker = output.getDeleteMarkers().get(i);
                        System.out.printf("Listed deleteMarker is %s\n", deleteMarker);
                    }
                }
                isTruncated = output.isTruncated();
                keyMarker = output.getNextKeyMarker();
                versionIdMarker = output.getNextVersionIDMarker();
            }
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("listObjectVersions failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("listObjectVersions 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("listObjectVersions failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }

    private static void listCommonPrefix(String bucketName, int maxKeys, String delimiter, String prefix, TOSV2 tos) {
        boolean isTruncated = true;
        String keyMarker = null;
        String versionIdMarker = null;
        while (isTruncated) {
            ListObjectVersionsV2Input input = new ListObjectVersionsV2Input().setBucket(bucketName).setMaxKeys(maxKeys)
                    .setDelimiter(delimiter).setKeyMarker(keyMarker).setVersionIDMarker(versionIdMarker).setPrefix(prefix);
            ListObjectVersionsV2Output output = tos.listObjectVersions(input);
            System.out.printf("listObjectVersions succeed, is truncated? %b, next key marker is %s, " +
                            "next version id marker is %s.\n", output.isTruncated(),
                    output.getNextKeyMarker(), output.getNextVersionIDMarker());
            if (output.getVersions() != null) {
                for (int i = 0; i < output.getVersions().size(); i++) {
                    ListedObjectVersion object = output.getVersions().get(i);
                    System.out.printf("Listed object version, key is %s, size is %d, versionId is %s, " +
                                    "storageClass is %s, ETag is %s, last modified is %s, isLatest? %b.\n",
                            object.getKey(), object.getSize(), object.getVersionID(), object.getStorageClass(),
                            object.getEtag(), object.getLastModified(), object.isLatest());
                }
            }
            if (output.getCommonPrefixes() != null) {
                for (int i = 0; i < output.getCommonPrefixes().size(); i++) {
                    ListedCommonPrefix commonPrefix = output.getCommonPrefixes().get(i);
                    System.out.println("Listed commonPrefix is " + commonPrefix.getPrefix());
                }
            }
            if (output.getDeleteMarkers() != null) {
                for (int i = 0; i < output.getDeleteMarkers().size(); i++) {
                    ListedDeleteMarkerEntry deleteMarker = output.getDeleteMarkers().get(i);
                    System.out.printf("Listed deleteMarker is %s\n", deleteMarker);
                }
            }
            isTruncated = output.isTruncated();
            keyMarker = output.getNextKeyMarker();
            versionIdMarker = output.getNextVersionIDMarker();
        }
    }
}

相关文档

关于列举多版本对象的 API 文档，请参见 ListObjectsVersions。