本文介绍如何列举指定存储空间下(Bucket)的所有文件(Object)、指定个数的文件、指定前缀的文件等。

背景信息

您可以调用GetBucket (ListObjects)或GetBucketV2 (ListObjectsV2)接口,一次性列举某个Bucket下最多1000个Object。您可以通过指定参数实现多种列举功能,例如通过指定参数列举指定起始位置后的所有文件、列举指定目录下的文件和子目录、以及列举结果分页。这两个接口的主要区别如下:

  • 使用GetBucket (ListObjects)接口列举文件时,默认返回owner信息。
  • 使用GetBucketV2 (ListObjectsV2)接口列举文件时,需通过fetchOwner指定是否在返回结果中包含owner信息。
    说明 对于开启版本控制的Bucket,建议使用GetBucketV2 (ListObjectsV2)接口列举文件。

以下分别介绍通过GetBucket (ListObjects)以及GetBucketV2 (ListObjectsV2)方法列举文件时涉及的参数说明。

  • 通过GetBucket (ListObjects)方法列举文件

    GetBucket (ListObjects)有以下三类参数格式:

    • ObjectListing listObjects(String bucketName):列举存储空间下的文件。单次请求默认最多列举100个文件。
    • ObjectListing listObjects(String bucketName, String prefix): 列举存储空间下指定前缀的文件。单次请求默认最多列举100个文件。
    • ObjectListing listObjects(ListObjectsRequest listObjectsRequest):提供多种过滤功能,实现灵活的查询功能。

    GetBucket (ListObjects)涉及参数说明如下:

    参数 描述 方法
    objectSummaries 限定返回的文件元信息。 List<OSSObjectSummary> getObjectSummaries()
    prefix 本次查询结果的前缀。 String getPrefix()
    delimiter 对文件名称进行分组的字符。 String getDelimiter()
    marker 标明本次列举文件的起点。 String getMarker()
    maxKeys 列举文件的最大个数。 int getMaxKeys()
    nextMarker 下一次列举文件的起点。 String getNextMarker()
    isTruncated 指明列举文件是否被截断。
    • 列举完没有截断,返回值为false。
    • 没列举完就有截断,返回值为true。
    boolean isTruncated()
    commonPrefixes 以delimiter结尾,且有共同前缀的文件集合。 List<String> getCommonPrefixes()
    encodingType 指明返回结果中编码使用的类型。 String getEncodingType()
  • 通过GetBucketV2 (ListObjectsV2)方法列举文件

    GetBucketV2 (ListObjectsV2)有以下三类参数格式:

    • ListObjectsV2Result listObjectsV2(String bucketName):列举存储空间下的文件。单次请求默认最多列举100个文件。
    • ListObjectsV2Result listObjectsV2(String bucketName, String prefix): 列举存储空间下指定前缀的文件。单次请求默认最多列举100个文件。
    • ListObjectsV2Result listObjectsV2(ListObjectsRequest listObjectsRequest):提供多种过滤功能,实现灵活的查询功能。

    GetBucketV2 (ListObjectsV2)涉及参数说明如下:

    参数 描述 方法
    objectSummaries 限定返回的文件元信息。 List<OSSObjectSummary> getObjectSummaries()
    prefix 本次查询结果的前缀。 String getPrefix()
    delimiter 对文件名称进行分组的字符。 String getDelimiter()
    startAfter 此次列举文件的起点。 String getStartAfter()
    maxKeys 列举文件的最大个数。 int getMaxKeys()
    continuationToken 此次列举文件操作使用的continuationToken。 String getContinuationToken()
    nextContinuationToken 下次列举文件的continuationToken。 String getNextContinuationToken()
    isTruncated 指明列举文件是否被截断。
    • 列举完没有截断,返回值为false。
    • 没列举完就有截断,返回值为true。
    boolean isTruncated()
    commonPrefixes 以delimiter结尾,且有共同前缀的文件集合。 List<String> getCommonPrefixes()
    encodingType 指明返回结果中编码使用的类型。 String getEncodingType()
    fetchOwner 指定是否在返回结果中包含owner信息。
    • true:表示返回结果中包含owner信息。
    • false:表示返回结果中不包含owner信息。
    String getFetchOwner()

简单列举文件

您可以通过GetBucket (ListObjects)方法列举或GetBucketV2 (ListObjectsV2)方法列举指定存储空间下的文件。

  • 通过GetBucket (ListObjects)方法

    以下代码用于通过GetBucket (ListObjects)方法列举指定存储空间下的文件,默认列举100个文件。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    String KeyPrefix = "<yourKeyPrefix>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 列举文件。如果不设置KeyPrefix,则列举存储空间下的所有文件。如果设置KeyPrefix,则列举包含指定前缀的文件。
    ObjectListing objectListing = ossClient.listObjects(bucketName, KeyPrefix);
    List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
    for (OSSObjectSummary s : sums) {
        System.out.println("\t" + s.getKey());
    }
    
    // 关闭OSSClient。
    ossClient.shutdown();
                        
  • 通过GetBucketV2 (ListObjectsV2)方法

    以下代码用于通过GetBucketV2 (ListObjectsV2)方法列举指定存储空间下的文件,默认列举100个文件。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 列举文件。如果不设置KeyPrefix,则列举存储空间下的所有文件。如果设置KeyPrefix,则列举包含指定前缀的文件。
    ListObjectsV2Result result = ossClient.listObjectsV2(bucketName);
    List<OSSObjectSummary> ossObjectSummaries = result.getObjectSummaries();
    
    for (OSSObjectSummary obj : ossObjectSummaries) {
        System.out.println("\t" + s.getKey());
    }
    
    // 关闭OSSClient。
    ossClient.shutdown();

通过ListObjectsRequest列举文件

通过设置ListObjectsRequest的参数实现各种灵活的查询功能。ListObjectsRequest的参数如下:

参数 描述 方法
prefix 限定返回的文件必须以prefix作为前缀。 setPrefix(String prefix)
delimiter 对文件名称进行分组的一个字符。所有名称包含指定的前缀且第一次出现delimiter字符之间的文件作为一组元素(commonPrefixes)。 setDelimiter(String delimiter)
marker 列举指定marker之后的文件。 setMarker(String marker)
maxKeys 限定此次列举文件的最大个数。默认值为100,最大值为1000。 setMaxKeys(Integer maxKeys)
encodingType 请求响应体中文件名称采用的编码方式,目前仅支持URL。 setEncodingType(String encodingType)
  • 列举指定个数的文件

    以下代码用于列举指定个数的文件。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 设置最大个数。
    final int maxKeys = 200;
    // 列举文件。
    ObjectListing objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).withMaxKeys(maxKeys));
    List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
    for (OSSObjectSummary s : sums) {
        System.out.println("\t" + s.getKey());
    }
    
    // 关闭OSSClient。
    ossClient.shutdown();
                        
  • 列举指定前缀的文件

    以下代码用于列举包含指定前缀(prefix)的文件。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 指定前缀。
    final String keyPrefix = "<yourkeyPrefix>";
    
    // 列举包含指定前缀的文件。默认列举100个文件。
    ObjectListing objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).withPrefix(keyPrefix));
    List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
    for (OSSObjectSummary s : sums) {
        System.out.println("\t" + s.getKey());
    }
    
    // 关闭OSSClient。
    ossClient.shutdown();
                        
  • 列举指定marker之后的文件

    参数marker代表文件名称。以下代码用于列举指定marker之后的文件。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    final String marker = "<yourMarker>";
    
    // 列举指定marker之后的文件。默认列举100个文件。
    ObjectListing objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).withMarker(marker));
    List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
    for (OSSObjectSummary s : sums) {
        System.out.println("\t" + s.getKey());
    }
    
    // 关闭OSSClient。
    ossClient.shutdown();
                        
  • 分页列举所有文件

    以下代码用于分页列举指定存储空间下的所有文件。每页列举的文件个数通过maxKeys指定。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    final int maxKeys = 200;
    String nextMarker = null;
    ObjectListing objectListing;
    
    do {
        objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).withMarker(nextMarker).withMaxKeys(maxKeys));
    
        List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
        for (OSSObjectSummary s : sums) {
            System.out.println("\t" + s.getKey());
        }
    
        nextMarker = objectListing.getNextMarker();
    
    } while (objectListing.isTruncated());
    
    // 关闭OSSClient。
    ossClient.shutdown();
                        
  • 分页列举指定前缀的文件

    以下代码用于分页列举包含指定前缀的文件。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 指定每页200个文件。
    final int maxKeys = 200;
    final String keyPrefix = "<yourkeyPrefix>";
    String nextMarker = "<yourNextMarker>";
    ObjectListing objectListing;
    
    do {
        objectListing = ossClient.listObjects(new ListObjectsRequest(bucketName).
                withPrefix(keyPrefix).withMarker(nextMarker).withMaxKeys(maxKeys));
    
        List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
        for (OSSObjectSummary s : sums) {
            System.out.println("\t" + s.getKey());
        }
    
        nextMarker = objectListing.getNextMarker();
    
    } while (objectListing.isTruncated());
    
    // 关闭OSSClient。
    ossClient.shutdown();
                        
  • 指定文件名称编码

    如果文件名称含有以下特殊字符,需要进行编码传输。OSS目前仅支持URL编码。

    • 单引号(' ')
    • 双引号(" ")
    • and符号(&)
    • 尖括号(< >)
    • 顿号(、)
    • 中文

    以下代码用于指定文件名称编码。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    final int maxKeys = 200;
    final String keyPrefix = "<yourkeyPrefix>";
    String nextMarker = "<yourNextMarker>";
    ObjectListing objectListing;
    
    do {
        ListObjectsRequest listObjectsRequest = new ListObjectsRequest(bucketName);
        listObjectsRequest.setPrefix(keyPrefix);
        listObjectsRequest.setMaxKeys(maxKeys);
        listObjectsRequest.setMarker(nextMarker);
    
        // 指定文件名称编码。
        listObjectsRequest.setEncodingType("url");
    
        objectListing = ossClient.listObjects(listObjectsRequest);
    
        // 文件解码。
        for (OSSObjectSummary objectSummary: objectListing.getObjectSummaries()) {
            System.out.println("Key:" + URLDecoder.decode(objectSummary.getKey(), "UTF-8"));
        }
    
        // commonPrefixes解码。
        for (String commonPrefixes: objectListing.getCommonPrefixes()) {
            System.out.println("CommonPrefixes:" + URLDecoder.decode(commonPrefixes, "UTF-8"));
        }
    
        // nextMarker解码。
        if (objectListing.getNextMarker() != null) {
            nextMarker = URLDecoder.decode(objectListing.getNextMarker(), "UTF-8");
        }
    } while (objectListing.isTruncated());
    
    // 关闭OSSClient。
    ossClient.shutdown();
                        

通过ListObjectsV2Request列举文件

通过设置ListObjectsV2Request参数实现灵活的列举文件功能,例如列举指定个数的文件、指定前缀(prefix)的文件、分页列举所有文件等。

ListObjectsV2Request参数说明如下:

参数 描述 方法
prefix 限定返回的文件必须以prefix作为前缀。 setPrefix(String prefix)
delimiter 对文件名称进行分组的一个字符。所有名称包含指定的前缀且第一次出现delimiter字符之间的文件作为一组元素(commonPrefixes)。 setDelimiter(String delimiter)
maxKeys 限定此次列举文件的最大个数。默认值为100,最大值为1000。 setMaxKeys(Integer maxKeys)
startAfter 此次列举文件的起点。 setStartAfter(String startAfter)
continuationToken 此次列举文件使用的continuationToken。 setContinuationToken(String continuationToken)
encodingType 请求响应体中文件名称采用的编码方式,目前仅支持URL。 setEncodingType(String encodingType)
fetchOwner 本次列举结果中是否包含文件的owner的信息。 setFetchOwner(boolean fetchOwner )
  • 列举指定个数的文件

    以下代码用于列举指定个数的文件。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 设置最大个数。
    final int maxKeys = 200
    
    // 列举文件,每次请求默认返回100个文件,此次指定设置最多返回文件数为200。
    ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request(bucketName);
    listObjectsV2Request.setMaxKeys(maxKeys);
    ListObjectsV2Result result = ossClient.listObjectsV2(listObjectsV2Request);
    List<OSSObjectSummary> ossObjectSummaries = result.getObjectSummaries();
    
    for (OSSObjectSummary obj : ossObjectSummaries) {
        System.out.println("\t" + s.getKey());
    }
    
    // 关闭OSSClient。
    ossClient.shutdown();
  • 列举指定前缀的文件

    以下代码用于列举包含指定前缀(prefix)的文件。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 设置最大个数。
    final int maxKeys = 200
    String prefix = "<yourKeyPrefix>";
    
    // 列举指定前缀的文件。
    ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request(bucketName);
    listObjectsV2Request.setPrefix(prefix);
    ListObjectsV2Result result = ossClient.listObjectsV2(listObjectsV2Request);
    List<OSSObjectSummary> ossObjectSummaries = result.getObjectSummaries();
    
    for (OSSObjectSummary obj : ossObjectSummaries) {
        System.out.println("\t" + s.getKey());
    }
    
    // 关闭OSSClient。
    ossClient.shutdown();
  • 列举指定startAfter之后的文件

    以下代码用于列举文件名称字典序中排在指定字符串startAfter之后的文件。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 列举指定名称之后的文件,传入的字符串即可以是已存在的文件的名称也可以是其它值。
    // 以传入字符串"test-obj"为例,则返回字典序在"test-obj"之后的文件。即使存储空间中已经存在"test-obj"这个文件,返回结果中依然不会返回"test-obj"这个文件。
    ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request(bucketName);
    listObjectsV2Request.setStartAfter("test-obj");
    ListObjectsV2Result result = ossClient.listObjectsV2(listObjectsV2Request);
    List<OSSObjectSummary> ossObjectSummaries = result.getObjectSummaries();
    
    for (OSSObjectSummary obj : ossObjectSummaries) {
        System.out.println("\t" + s.getKey());
    }
    
    // 关闭OSSClient。
    ossClient.shutdown();
  • 列举结果中返回文件的owner信息

    以下代码用于列举结果中返回文件的owner信息。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 默认列举的文件信息中不包含owner信息。如果需要包含owner信息,将fetchOwner参数设置为true。
    ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request(bucketName);
    listObjectsV2Request.setFetchOwner(true)
    ListObjectsV2Result result = ossClient.listObjectsV2(listObjectsV2Request);
    List<OSSObjectSummary> ossObjectSummaries = result.getObjectSummaries();
    
    for (OSSObjectSummary obj : ossObjectSummaries) {
        System.out.println("\t" + s.getKey());
        if (obj.getOwner() != null) {
            System.out.println("owner id:" + obj.getOwner().getId());
            System.out.println("owner id:" + obj.getOwner().getDisplayName());
        }
    }
    
    // 关闭OSSClient。
    ossClient.shutdown();
  • 分页列举所有文件

    以下代码用于分页列举指定存储空间下的所有文件。每页列举的文件个数通过maxKeys指定。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 设置最大个数。
    final int maxKeys = 200
    String nextContinuationToken = null;
    ListObjectsV2Result result = null;
    
    // 分页列举,每次传入上次返回结果中的nextContinuationToken。
    do {
        ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request(bucketName).withMaxKeys(maxKeys);
        listObjectsV2Request.setContinuationToken(nextContinuationtoken);
        result = ossClient.listObjectsV2(listObjectsV2Request);
    
        List<OSSObjectSummary> sums = result.getObjectSummaries();
        for (OSSObjectSummary s : sums) {
            System.out.println("\t" + s.getKey());
        }
    
        nextContinuationToken = result.getNextContinuationToken();
    
    } while (result1.isTruncated());
    
    // 关闭OSSClient。
    ossClient.shutdown();
  • 分页列举指定前缀的文件

    以下代码用于分页列举包含指定前缀的文件。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    String KeyPrefix = "<yourKeyPrefix>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 设置最大个数。
    final int maxKeys = 200
    String nextContinuationToken = null;
    ListObjectsV2Result result = null;
    final String keyPrefix = "<yourkeyPrefix>";
    
    // 分页列举指定前缀的文件。
    do {
        ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request(bucketName).withMaxKeys(maxKeys);
        listObjectsV2Request.setPrefix(keyPrefix);
        listObjectsV2Request.setContinuationToken(nextContinuationToken);
        result = ossClient.listObjectsV2(listObjectsV2Request);
    
        List<OSSObjectSummary> sums = result.getObjectSummaries();
        for (OSSObjectSummary s : sums) {
            System.out.println("\t" + s.getKey());
        }
    
        nextContinuationToken = result.getNextContinuationToken();
    
    } while (result1.isTruncated());
    
    // 关闭OSSClient。
    ossClient.shutdown();
  • 指定文件名称编码
    说明 有关文件名称包含的特殊字符详情,请参见文件名称特殊字符说明

    以下代码用于指定文件名称编码。

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台 https://ram.console.aliyun.com 创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // 设置最大个数。
    final int maxKeys = 200
    String nextContinuationToken = null;
    ListObjectsV2Result result = null;
    final String keyPrefix = "<yourkeyPrefix>";
    
    // 指定返回结果使用URL编码,则您需要对结果中的prefix、delemiter、startAfter、key和commonPrefix进行URL解码。 
    do {
        ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request(bucketName).withMaxKeys(maxKeys);
        listObjectsV2Request.setPrefix(keyPrefix);
        listObjectsV2Request.setEncodingType("url");
        listObjectsV2Request.setContinuationToken(nextContinuationtoken);
        result = ossClient.listObjectsV2(listObjectsV2Request);
    
        // prefix解码。
        if (result.getPrefix() != null) {
            String prefix = URLDecoder.decode(result.getPrefix(), "UTF-8");
            System.out.println("prefix: " + prefix);
        }
    
        // delimiter解码。
        if (result.getDelimiter() != null) {
            String delimiter = URLDecoder.decode(result.getDelimiter(), "UTF-8");
            System.out.println("delimiter: " + prefix);
        }
    
        // startAfter解码。
        if (result.getStartAfter() != null) {
            String startAfter = URLDecoder.decode(result.getStartAfter(), "UTF-8");
            System.out.println("startAfter: " + prefix);
        }
    
        // 文件名称解码。
        for (OSSObjectSummary s : result.getObjectSummaries()) {
            String decodedKey = URLDecoder.decode(s.getKey(), "UTF-8");
            System.out.println("key: " + decodedKey);
        }
    
        // commonPrefixes解码。
        for (String commonPrefix: result.getCommonPrefixes()) {
            String commonPrefix = URLDecoder.decode(commonPrefix, "UTF-8");
            System.out.println("CommonPrefix: " commonPrefix);
        }
    
        nextContinuationToken = result.getNextContinuationToken();
    
    } while (result1.isTruncated());
    
    // 关闭OSSClient。
    ossClient.shutdown();

文件夹功能

OSS没有文件夹的概念,所有元素都是以文件来存储。创建文件夹本质上来说是创建了一个大小为0并以正斜线(/)结尾的文件。这个文件可以被上传和下载,控制台会对以正斜线(/)结尾的文件以文件夹的方式展示。

通过delimiter和prefix两个参数可以模拟文件夹功能:

  • 如果设置prefix为某个文件夹名称,则会列举以此prefix开头的文件,即该文件夹下所有的文件和子文件夹(目录)均显示为objects。
  • 如果在设置了prefix的情况下,将delimiter设置为正斜线(/),则只列举该文件夹下的文件和子文件夹(目录),该文件夹下的子文件夹(目录)显示为CommonPrefixes,子文件夹下的文件和文件夹不显示。

文件夹详情请参见文件夹功能。创建文件夹的完整代码请参见GitHub

假设存储空间中包含文件oss.jpgfun/test.jpgfun/movie/001.avifun/movie/007.avi,以正斜线(/)作为文件夹的分隔符。以下示例说明了如何通过模拟文件夹的方式列举文件。

  • 列举存储空间下的所有文件
    • 通过GetBucket (ListObjects)列举存储空间下的所有文件
      // Endpoint以杭州为例,其它Region请按实际情况填写。
      String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
      // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
      String accessKeyId = "<yourAccessKeyId>";
      String accessKeySecret = "<yourAccessKeySecret>";
      String bucketName = "<yourBucketName>";
      
      // 创建OSSClient实例。
      OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
      
      // 构造ListObjectsRequest请求。
      ListObjectsRequest listObjectsRequest = new ListObjectsRequest(bucketName);
      
      // 列举文件。
      ObjectListing listing = ossClient.listObjects(listObjectsRequest);
      
      // 遍历所有文件。
      System.out.println("Objects:");
      for (OSSObjectSummary objectSummary : listing.getObjectSummaries()) {
          System.out.println(objectSummary.getKey());
      }
      
      // 遍历所有commonPrefix。
      System.out.println("CommonPrefixes:");
      for (String commonPrefix : listing.getCommonPrefixes()) {
          System.out.println(commonPrefix);
      }
      
      // 关闭OSSClient。
      ossClient.shutdown();
                                  
    • 通过GetBucketV2 (ListObjectsV2)列举指定存储空间下的所有文件
      // Endpoint以杭州为例,其它Region请按实际情况填写。
      String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
      // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM创建RAM账号。
      String accessKeyId = "<yourAccessKeyId>";
      String accessKeySecret = "<yourAccessKeySecret>";
      String bucketName = "<yourBucketName>";
      
      // 创建OSSClient实例。
      OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
      
      // 列举文件。
      ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request(bucketName);
      ListObjectsV2Result result = ossClient.listObjectsV2(listObjectsV2Request);
      
      // 遍历文件。
      System.out.println("Objects:");
      for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
          System.out.println(objectSummary.getKey());
      }
      
      // 遍历commonPrefix。
      System.out.println("CommonPrefixes:");
      for (String commonPrefix : result.getCommonPrefixes()) {
          System.out.println(commonPrefix);
      }
      
      // 关闭OSSClient。
      ossClient.shutdown();
                                  
    • 返回结果

      通过以上两种方法列举指定存储空间下所有文件的返回结果如下。

      Objects:
      fun/movie/001.avi
      fun/movie/007.avi
      fun/test.jpg
      oss.jpg
      CommonPrefixes:                    
  • 列举指定目录下所有文件
    • 通过GetBucket (ListObjects)方法列举指定目录下的所有文件
      // Endpoint以杭州为例,其它Region请按实际情况填写。
      String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
      // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
      String accessKeyId = "<yourAccessKeyId>";
      String accessKeySecret = "<yourAccessKeySecret>";
      String bucketName = "<yourBucketName>";
      
      // 创建OSSClient实例。
      OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
      
      // 构造ListObjectsRequest请求。
      ListObjectsRequest listObjectsRequest = new ListObjectsRequest(bucketName);
      // 设置prefix参数来获取fun目录下的所有文件。
      listObjectsRequest.setPrefix("fun/");
      
      // 递归列举fun目录下的所有文件。
      ObjectListing listing = ossClient.listObjects(listObjectsRequest);
      
      // 遍历所有文件。
      System.out.println("Objects:");
      for (OSSObjectSummary objectSummary : listing.getObjectSummaries()) {
          System.out.println(objectSummary.getKey());
      }
      
      // 遍历所有commonPrefix。
      System.out.println("\nCommonPrefixes:");
      for (String commonPrefix : listing.getCommonPrefixes()) {
          System.out.println(commonPrefix);
      }
      
      // 关闭OSSClient。
      ossClient.shutdown();
                                  
    • 通过GetBucketV2 (ListObjectsV2)方法列举指定目录下所有文件
      // Endpoint以杭州为例,其它Region请按实际情况填写。
      String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
      // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
      String accessKeyId = "<yourAccessKeyId>";
      String accessKeySecret = "<yourAccessKeySecret>";
      String bucketName = "<yourBucketName>";
      
      // 创建OSSClient实例。
      OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
      
      // 构造ListObjectsV2Request请求。
      ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request(bucketName);
      
      // 设置prefix参数来获取fun目录下的文件。
      listObjectsV2Request.setPrefix("fun/");
      
      // 发起列举请求。
      ListObjectsV2Result result = ossClient.listObjectsV2(listObjectsV2Request);
      
      // 遍历文件。
      System.out.println("Objects:");
      for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
          System.out.println(objectSummary.getKey());
      }
      
      // 遍历commonPrefix。
      System.out.println("\nCommonPrefixes:");
      for (String commonPrefix : result.getCommonPrefixes()) {
          System.out.println(commonPrefix);
      }
      
      // 关闭OSSClient。
      ossClient.shutdown();
    • 通过以上两种方法列举指定目录下所有文件的返回结果如下。
      Objects:
      fun/movie/001.avi
      fun/movie/007.avi
      fun/test.jpg
      CommonPrefixes:                    
  • 列举目录下的文件和子目录
    • 通过GetBucket (ListObjects)方法列举目录下的文件和子目录
      // Endpoint以杭州为例,其它Region请按实际情况填写。
      String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
      // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
      String accessKeyId = "<yourAccessKeyId>";
      String accessKeySecret = "<yourAccessKeySecret>";
      String bucketName = "<yourBucketName>";
      
      // 创建OSSClient实例。
      OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
      
      // 构造ListObjectsRequest请求。
      ListObjectsRequest listObjectsRequest = new ListObjectsRequest(bucketName);
      
      // 设置正斜线(/)为文件夹的分隔符。
      listObjectsRequest.setDelimiter("/");
      
      // 列出fun目录下的所有文件和文件夹。
      listObjectsRequest.setPrefix("fun/");
      
      ObjectListing listing = ossClient.listObjects(listObjectsRequest);
      
      // 遍历所有文件。
      System.out.println("Objects:");
      // objectSummaries的列表中给出的是fun目录下的文件。
      for (OSSObjectSummary objectSummary : listing.getObjectSummaries()) {
          System.out.println(objectSummary.getKey());
      }
      
      // 遍历所有commonPrefix。
      System.out.println("\nCommonPrefixes:");
      // commonPrefixs列表中显示的是fun目录下的所有子文件夹。由于fun/movie/001.avi和fun/movie/007.avi属于fun文件夹下的movie目录,因此这两个文件未在列表中。
      for (String commonPrefix : listing.getCommonPrefixes()) {
          System.out.println(commonPrefix);
      }
      
      // 关闭OSSClient。
      ossClient.shutdown();
                                  
    • 通过GetBucketV2 (ListObjectsV2)方法列举目录下的文件和子目录
      // Endpoint以杭州为例,其它Region请按实际情况填写。
      String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
      // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
      String accessKeyId = "<yourAccessKeyId>";
      String accessKeySecret = "<yourAccessKeySecret>";
      String bucketName = "<yourBucketName>";
      
      // 创建OSSClient实例。
      OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
      
      // 构造ListObjectsV2Request请求。
      ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request(bucketName);
      
      // 设置prefix参数来获取fun目录下的所有文件与文件夹。
      listObjectsV2Request.setPrefix("fun/");
      
      // 设置正斜线(/)为文件夹的分隔符。
      listObjectsV2Request.setDelimiter("/");
      
      // 发起列举请求。
      ListObjectsV2Result result = ossClient.listObjectsV2(listObjectsV2Request);
      
      // 遍历文件。
      System.out.println("Objects:");
      // objectSummaries的列表中给出的是fun目录下的文件。
      for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
          System.out.println(objectSummary.getKey());
      }
      
      // 遍历commonPrefix。
      System.out.println("\nCommonPrefixes:");
      // commonPrefixs列表中显示的是fun目录下的所有子文件夹。由于fun/movie/001.avi和fun/movie/007.avi属于fun文件夹下的movie目录,因此这两个文件未在列表中。
      for (String commonPrefix : result.getCommonPrefixes()) {
          System.out.println(commonPrefix);
      }
      
      // 关闭OSSClient。
      ossClient.shutdown();
    • 通过以上两种方法列举指定目录下的文件和子目录的返回结果如下:
      Objects:
      fun/test.jpg
      
      CommonPrefixes:
      fun/movie/                    
  • 获取指定目录下的文件大小
    • 通过GetBucket (ListObjects)方法获取指定目录下的文件大小
      // 获取某个存储空间下指定目录(文件夹)下的文件大小。
      private static long calculateFolderLength(OSS ossClient, String bucketName, String folder) {
           long size = 0L;
           ObjectListing objectListing = null;
           do {
              // MaxKey默认值为100,最大值为1000。
              ListObjectsRequest request = new ListObjectsRequest(bucketName).withPrefix(folder).withMaxKeys(1000);
              if (objectListing != null) {
                   request.setMarker(objectListing.getNextMarker());
              }
              objectListing = ossClient.listObjects(request);
              List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
              for (OSSObjectSummary s : sums) {
                   size += s.getSize();
              }
          } while (objectListing.isTruncated());
            return size;
      }
      
      public void Calculate() {
            // Endpoint以杭州为例,其它Region请按实际情况填写。
            String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
            // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
            String accessKeyId = "<yourAccessKeyId>";
            String accessKeySecret = "<yourAccessKeySecret>";
            String bucketName = "<yourBucketName>";
            // 创建OSSClient实例。
            OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
            // 指定前缀。若您希望遍历主目录下的文件夹,则将此值置空。
            final String keyPrefix = "<YourPrefix>";
            ObjectListing objectListing = null;
            do {
                // 默认情况下,每次列举100个文件或目录。
                ListObjectsRequest request = new ListObjectsRequest(bucketName).withDelimiter("/").withPrefix(keyPrefix);
                if (objectListing != null) {
                     request.setMarker(objectListing.getNextMarker());
                }
                objectListing = ossClient.listObjects(request);
                List<String> folders = objectListing.getCommonPrefixes();
                for (String folder : folders) {
                    System.out.println(folder + " : " + (calculateFolderLength(ossClient, bucketName, folder) / 1024) + "KB");
                }
                List<OSSObjectSummary> sums = objectListing.getObjectSummaries();
                for (OSSObjectSummary s : sums) {
                    System.out.println(s.getKey() + " : " + (s.getSize() / 1024) + "KB");
                }
             } while (objectListing.isTruncated());
             ossClient.shutdown();
      }
    • 通过GetBucketV2 (ListObjectsV2)方法获取指定目录下的文件大小
      // 获取某个存储空间下指定目录(文件夹)下的文件大小。
      private satic long calculateFolderLength(OSS ossClient, String bucketName, String folder) {
          long size = 0L;
          ListObjectsV2Result result = null;
          do {
              // MaxKey默认值为100,最大值为1000。
              ListObjectsV2Request request = new ListObjectsV2Request(bucketName).withPrefix(folder).withMaxKeys(1000);
              if (result != null) {
                  request.setContinuationToken(result.getNextContinuationToken());
              }
              result = ossClient.listObjectsV2(request);
              List<OSSObjectSummary> sums = result.getObjectSummaries();
              for (OSSObjectSummary s : sums) {
                  size += s.getSize();
              }
          } while (result.isTruncated());
          return size;
      }
      
      public void Calculate() {
          // Endpoint以杭州为例,其它Region请按实际情况填写。
          String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
          // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
          String accessKeyId = "<yourAccessKeyId>";
          String accessKeySecret = "<yourAccessKeySecret>";
          String bucketName = "<yourBucketName>";
          // 创建OSSClient实例。
          OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
          // 指定前缀。若您希望遍历主目录文件夹,将该值置空。
          final String keyPrefix = "<YourPrefix>";
          ListObjectsV2Result result = null;
          do {
              // 默认情况下,每次列举100个文件或目录。
              ListObjectsV2Request request = new ListObjectsV2Request(bucketName).withDelimiter("/").withPrefix(keyPrefix);
              if (result != null) {
                  request.setContinuationToken(result.getNextContinuationToken());
              }
              result = ossClient.listObjectsV2(request);
              List<String> folders = result.getCommonPrefixes();
              for (String folder : folders) {
                  System.out.println(folder + " : " + (calculateFolderLength(ossClient, bucketName, folder) / 1024) + "KB");
              }
              List<OSSObjectSummary> sums = result.getObjectSummaries();
              for (OSSObjectSummary s : sums) {
                  System.out.println(s.getKey() + " : " + (s.getSize() / 1024) + "KB");
              }
          } while (result.isTruncated());
          ossClient.shutdown();
      }