金山云-文档中心-列举文件

对象存储(KS3)

查看更多结果

未找到含当前关键字的文档标题

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

SDK

Java

管理文件（Java）

列举文件（Java）

最近更新时间：2025-03-06 10:34:56

1. 通过GET Bucket（ListObjects）列举文件

/**
 *  列出一个bucket下的object，最多返回1000条
 */

public ObjectListing listObjectsSimple() {
       // yourEndpoint填写Bucket所在地域对应的Endpoint。以中国（北京）为例，Endpoint填写为ks3-cn-beijing.ksyuncs.com。如果使用自定义域名，设置endpoint为自定义域名，同时设置domainMode为true
       String endpoint = "yourEndpoint";
       // 金山云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用子账号账号进行 API 访问或日常运维，请登录 https://uc.console.ksyun.com/pro/iam/#/user/list 创建子账号。
       String accessKeyId = "yourAccessKeyId";
       String accessKeySecret = "yourAccessKeySecret";
       // 创建Ks3ClientConfig 实例。
       Ks3ClientConfig config = new Ks3ClientConfig();
       // 设置域名
       config.setEndpoint(endpoint);
       /**
        * false: （推荐）使用三级域名：{bucketName}.{endpoint}/{objectKey}的形式访问
        * true:  使用二级域名：{endpoint}/{bucketName}/{objectKey}的形式访问
        * 如果domainMode设置为true，则pathStyleAccess可忽略设置
        */
       config.setPathStyleAccess(false);

       // 创建Ks3Client实例
       Ks3 client = new Ks3Client(accessKeyId, accessKeySecret, config);
       // 获取桶下面的文件列表，最多返回1000条
       ObjectListing list = client.listObjects("<您的bucket名称>");
       // 遍历文件列表
       for (Ks3ObjectSummary objectSummary : list.getObjectSummaries()) {
            // 获取文件的名字
            objectSummary.getKey();
            // 获取文件的存储类型
            objectSummary.getStorageClass();
            // 获取文件的其他信息
            // objectSummary.
       }
       // 返回文件列表
       return list;
} 


/**
 * 将列出bucket下满足object key前缀为指定字符串的object，最多返回1000条
 */
public ObjectListing listObjectsWithPrefix(){
       // yourEndpoint填写Bucket所在地域对应的Endpoint。以中国（北京）为例，Endpoint填写为ks3-cn-beijing.ksyuncs.com。如果使用自定义域名，设置endpoint为自定义域名，同时设置domainMode为true
       String endpoint = "yourEndpoint";
       // 金山云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用子账号账号进行 API 访问或日常运维，请登录 https://uc.console.ksyun.com/pro/iam/#/user/list 创建子账号。
       String accessKeyId = "yourAccessKeyId";
       String accessKeySecret = "yourAccessKeySecret";
       // 创建Ks3ClientConfig 实例。
       Ks3ClientConfig config = new Ks3ClientConfig();
       // 设置域名
       config.setEndpoint(endpoint);
       /**
        * false: （推荐）使用三级域名：{bucketName}.{endpoint}/{objectKey}的形式访问
        * true:  使用二级域名：{endpoint}/{bucketName}/{objectKey}的形式访问
        * 如果domainMode设置为true，则pathStyleAccess可忽略设置
        */
       config.setPathStyleAccess(false);

       // 创建Ks3Client实例
       Ks3 client = new Ks3Client(accessKeyId, accessKeySecret, config);
       // 根据前缀去获取桶的文件列表
       ObjectListing list = client.listObjects("<您的bucket名称>","<object key前缀>");
       // 遍历文件列表
       for (Ks3ObjectSummary objectSummary : list.getObjectSummaries()) {
            // 获取文件的名字
            objectSummary.getKey();
            // 获取文件的存储类型
            objectSummary.getStorageClass();
            // 获取文件的其他信息
            // objectSummary.
       }
       // 返回文件列表
       return list;
}

/**
 * 自己调节列出object的参数，
 */

public ObjectListing listObjectsUseRequest(){
       // yourEndpoint填写Bucket所在地域对应的Endpoint。以中国（北京）为例，Endpoint填写为ks3-cn-beijing.ksyuncs.com。如果使用自定义域名，设置endpoint为自定义域名，同时设置domainMode为true
       String endpoint = "yourEndpoint";
       // 金山云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用子账号账号进行 API 访问或日常运维，请登录 https://uc.console.ksyun.com/pro/iam/#/user/list 创建子账号。
       String accessKeyId = "yourAccessKeyId";
       String accessKeySecret = "yourAccessKeySecret";
       // 创建Ks3ClientConfig 实例。
       Ks3ClientConfig config = new Ks3ClientConfig();
       // 设置域名
       config.setEndpoint(endpoint);
       /**
        * false: （推荐）使用三级域名：{bucketName}.{endpoint}/{objectKey}的形式访问
        * true:  使用二级域名：{endpoint}/{bucketName}/{objectKey}的形式访问
        * 如果domainMode设置为true，则pathStyleAccess可忽略设置
        */
       config.setPathStyleAccess(false);

       // 创建Ks3Client实例
       Ks3 client = new Ks3Client(accessKeyId, accessKeySecret, config);
       //新建一个ListObjectsRequest
       ListObjectsRequest request = new ListObjectsRequest("<您的bucket名称>");
       //设置参数
       request.setMaxKeys("<max keys>");//指定最多返回条数
       request.setPrefix("<object key前缀>");//返回以指定前缀开头的object
       request.setDelimiter("<delimiter>");//设置文件分隔符，系统将根据该分隔符组织文件夹结构，默认是"/"
       //执行操作
       ObjectListing list = client.listObjects(request);
       for (Ks3ObjectSummary objectSummary : list.getObjectSummaries()) {
            // 获取文件的名字
            objectSummary.getKey();
            // 获取文件的存储类型
            objectSummary.getStorageClass();
       }
       // 返回文件列表
       return list;
}


/**
 * 使用循环列出所有object
 */
public void listAllObjects(){
       // yourEndpoint填写Bucket所在地域对应的Endpoint。以中国（北京）为例，Endpoint填写为ks3-cn-beijing.ksyuncs.com。如果使用自定义域名，设置endpoint为自定义域名，同时设置domainMode为true
       String endpoint = "yourEndpoint";
       // 金山云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用子账号账号进行 API 访问或日常运维，请登录 https://uc.console.ksyun.com/pro/iam/#/user/list 创建子账号。
       String accessKeyId = "yourAccessKeyId";
       String accessKeySecret = "yourAccessKeySecret";
       // 创建Ks3ClientConfig 实例。
       Ks3ClientConfig config = new Ks3ClientConfig();
       // 设置域名
       config.setEndpoint(endpoint);
       /**
        * false: （推荐）使用三级域名：{bucketName}.{endpoint}/{objectKey}的形式访问
        * true:  使用二级域名：{endpoint}/{bucketName}/{objectKey}的形式访问
        * 如果domainMode设置为true，则pathStyleAccess可忽略设置
        */
       config.setPathStyleAccess(false);

       // 创建Ks3Client实例
       Ks3 client = new Ks3Client(accessKeyId, accessKeySecret, config);
       ObjectListing list = null;
       //初始化一个请求
       ListObjectsRequest request = new ListObjectsRequest("<您的bucket名称>");
       do {
              //isTruncated为true时表示之后还有object，所以应该继续循环
              if (list!=null&&list.isTruncated()) {
                     // 在ObjectListing中将返回下次请求的marker
                     // 如果请求的时候没有设置delimiter，则不会返回nextMarker,需要使用上一次list的最后一个key做为nextMarker
                     request.setMarker(list.getObjectSummaries().get(list.getObjectSummaries().size() - 1).getKey());
              }
              list = client.listObjects(request);
              for (Ks3ObjectSummary objectSummary : list.getObjectSummaries()) {
                     // 获取文件的名字
                     objectSummary.getKey();
                     // 获取文件的存储类型
                     objectSummary.getStorageClass();
              }
       } while (list.isTruncated());
}

1. 单次List，最多只可能返回1000个文件。如果需要返回更多，请通过marker参数设置游标。

2. 具体输入输出参数说明请参见文档：GET Bucket(list Object)。

2. 通过List Objects V2列举文件

/**
     * 列出一个bucket下的object，最多返回1000条
     * 创建ks3 client实例参见"初始化"文档
     */
    public ObjectListingV2 listObjectsV2Simple(Ks3 client) {

        // 获取桶下面的文件列表，最多返回1000条
        ObjectListingV2 list = client.listObjectsV2("<您的bucket名称>");
        // 遍历文件列表
        for (Ks3ObjectSummary objectSummary : list.getObjectSummaries()) {
            // 获取文件的名字
            objectSummary.getKey();
            // 获取文件的存储类型
            objectSummary.getStorageClass();
            // 获取文件的其他信息
            // objectSummary.
        }
        // 返回文件列表
        return list;
    }

    /**
     * 将列出bucket下满足object key前缀为指定字符串的object，最多返回1000条
     * 创建ks3 client实例参见"初始化"文档
     */
    public ObjectListingV2 listObjectsV2WithPrefix(Ks3 client) {
        // 根据前缀去获取桶的文件列表
        ObjectListingV2 list = client.listObjectsV2("<您的bucket名称>", "<object key前缀>");
        // 遍历文件列表
        for (Ks3ObjectSummary objectSummary : list.getObjectSummaries()) {
            // 获取文件的名字
            objectSummary.getKey();
            // 获取文件的存储类型
            objectSummary.getStorageClass();
            // 获取文件的其他信息
            // objectSummary.
        }
        // 返回文件列表
        return list;
    }

    /**
     * 自己调节列出object的参数，
     * 创建ks3 client实例参见"初始化"文档
     */
    public ObjectListingV2 listObjectsV2UseRequest(Ks3 client) {
        //新建一个ListObjectsV2Request
        ListObjectsV2Request request = new ListObjectsV2Request("<您的bucket名称>");
        //设置参数
        request.setMaxKeys(<max keys>);//指定最多返回条数
        request.setPrefix("<object key前缀>");//返回以指定前缀开头的object
        request.setDelimiter("<delimiter>");//设置文件分隔符，系统将根据该分隔符组织文件夹结构，默认是"/"
        //执行操作
        ObjectListingV2 list = client.listObjectsV2(request);
        for (Ks3ObjectSummary objectSummary : list.getObjectSummaries()) {
            // 获取文件的名字
            objectSummary.getKey();
            // 获取文件的存储类型
            objectSummary.getStorageClass();
        }
        // 返回文件列表
        return list;
    }


    /**
     * 使用循环列出所有object
     * 创建ks3 client实例参见"初始化"文档
     */
    public void listAllObjectsV2(Ks3 client) {
        ObjectListingV2 list = null;
        //初始化一个请求
        ListObjectsV2Request request = new ListObjectsV2Request("<您的bucket名称>");
        do {
            // isTruncated为true时表示之后还有object，所以应该继续循环
            if (list != null && list.isTruncated()) {
                // 当 isTruncated 是true时，会返回NextContinuationToken，需要将NextContinuationToken指定为下一次ListObjectsV2操作的ContinuationToken，以继续获取结果。
                request.setContinuationToken(list.getNextContinuationToken());
            }
            list = client.listObjectsV2(request);
            for (Ks3ObjectSummary objectSummary : list.getObjectSummaries()) {
                // 获取文件的名字
                objectSummary.getKey();
                // 获取文件的存储类型
                objectSummary.getStorageClass();
            }
        } while (list.isTruncated());
    }

1. 单次List，最多只可能返回1000个文件。如果需要返回更多，请通过start-after参数设置游标。

2. 具体输入输出参数说明详见List Objects V2。

3. 通过 Ks3ObjectListIterator 列举文件

public void listObjectsByIterator() {
    // 初始化 Ks3Client，参见“初始化”文档
    Ks3Client ks3Client = initKs3Client();

    try {
        // 初始化 ListObjectsV2Request 请求实例，更多参数用法参见“通过List Object V2列举文件”
        ListObjectsV2Request request = new ListObjectsV2Request("bucketName", "prefix");
        // 创建 ks3ObjectListIterator 实例
        Ks3ObjectListIterator ks3ObjectListIterator = ks3Client.newObjectListIterator(request);
        // 遍历 ks3 对象
        while (ks3ObjectListIterator.hasNext()) {
            ObjectListingV2 objectListing = ks3ObjectListIterator.next();
            System.out.println("truncated: " + objectListing.isTruncated());
            System.out.println("next continuation token: " + objectListing.getNextContinuationToken());
            for (String commonPrefix : objectListing.getCommonPrefixes()) {
                System.out.println("CommonPrefix: " + commonPrefix);
            }
            for (Ks3ObjectSummary objectSummary : objectListing.getObjectSummaries()) {
                System.out.println("Key: " + objectSummary.getKey());
                System.out.println("  Size: " + objectSummary.getSize());
                System.out.println("  LastModified: " + objectSummary.getLastModified());
                System.out.println("  ETag: " + objectSummary.getETag());
                System.out.println("  StorageClass: " + objectSummary.getStorageClass());
            }
        }
    } catch (Ks3ServiceException e) {
        System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
        System.out.println("Error Message: " + e.getErrorMessage());
        System.out.println("Error Code: " + e.getErrorCode());
        System.out.println("Request ID: " + e.getRequestId());
    } catch (Ks3ClientException e) {
        System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
        System.out.println("Error Message: " + e.getMessage());
    } finally {
        // 不再使用时，关闭 Ks3Client
        ks3Client.shutdown();
    }
}

4. 通过 scanObjects 列举文件

1. 仅支持递归列举指定前缀或桶内的全部文件，不支持仅列举当前目录下的文件。
2. 适用于指定桶或目录下有较多子目录，且子目录下文件数量多且均衡的情况。
3. delimiter仅用于并行扫描时分割object key作为扫描层级。

public void listObjectsByScanner() {
    // 初始化 Ks3Client，参见“初始化”文档
    Ks3Client ks3Client = initKs3Client();

    // 初始化 ScanObjectsRequest 请求实例
    ScanObjectsRequest request = new ScanObjectsRequest("bucketName", "prefix");
    // 设置并发数
    request.setParallel(3);
    // 设置并发扫描的最大深度
    request.setMaxDepthOfParallelism(1);
    // 初始化 ObjectSummaryHandler 实例，用于处理列举出的 ks3 对象
    ObjectSummaryHandler handler = new ObjectSummaryHandler() {
        @Override
        public void handle(Ks3ObjectSummary objectSummary) {
            System.out.println("Key: " + objectSummary.getKey());
            System.out.println("  Size: " + objectSummary.getSize());
            System.out.println("  LastModified: " + objectSummary.getLastModified());
            System.out.println("  ETag: " + objectSummary.getETag());
            System.out.println("  StorageClass: " + objectSummary.getStorageClass());
        }

        @Override
        public void onError(Exception err) {
            if (err instanceof Ks3ServiceException) {
                Ks3ServiceException e = (Ks3ServiceException) err;
                System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
                System.out.println("Error Message: " + e.getErrorMessage());
                System.out.println("Error Code: " + e.getErrorCode());
                System.out.println("Request ID: " + e.getRequestId());
            } else if (err instanceof Ks3ClientException) {
                Ks3ClientException e = (Ks3ClientException) err;
                System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
                System.out.println("Error Message: " + e.getMessage());
            } else {
                System.out.println("Error occurred: " + err.getMessage());
            }
        }
    };

    // 遍历 ks3 对象
    ks3Client.scanObjects(request, handler);
    // 不再使用时，关闭 Ks3Client
    ks3Client.shutdown();
}