本文介绍如何列举文件。

OSS文件按照字母顺序排列。您可以通过ossClient.listObjects列出存储空间下的文件。listObjects有以下三类参数格式:

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

ObjectListing的参数如下:

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

简单列举文件

以下代码用于列举指定存储空间下的文件,默认列举100个文件。

// Endpoint以杭州为例,其它Region请按实际情况填写。
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";
String bucketName = "<yourBucketName>";
String KeyPrefix = "<yourKeyPrefix>";

// 创建OSSClient实例。
OSSClient ossClient = new OSSClient(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();

通过ListObjectsRequest列举文件

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

参数 描述 方法
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访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例
    OSSClient ossClient = new OSSClient(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访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSSClient ossClient = new OSSClient(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访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSSClient ossClient = new OSSClient(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访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSSClient ossClient = new OSSClient(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访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSSClient ossClient = new OSSClient(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访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSSClient ossClient = new OSSClient(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();
    

文件夹功能

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

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

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

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

假设存储空间中有4个文件: oss.jpg、fun/test.jpg、fun/movie/001.avi、fun/movie/007.avi,正斜线(/)作为文件夹的分隔符。下面的示例展示了如何模拟文件夹功能。

  • 列举存储空间下所有文件

    以下代码用于列举指定存储空间下的所有文件:

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSSClient ossClient = new OSSClient(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();
    

    返回结果如下:

    Objects:
    fun/movie/001.avi
    fun/movie/007.avi
    fun/test.jpg
    oss.jpg
    
    CommonPrefixes:
    
  • 列举指定目录下所有文件

    以下代码用于列举指定目录下的所有文件:

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSSClient ossClient = new OSSClient(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();
    

    返回结果如下:

    Objects:
    fun/movie/001.avi
    fun/movie/007.avi
    fun/test.jpg
    
    CommonPrefixes:
    
  • 列举目录下的文件和子目录

    以下代码用于列举指定目录下的文件和子目录:

    // Endpoint以杭州为例,其它Region请按实际情况填写。
    String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
    // 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录 https://ram.console.aliyun.com 创建RAM账号。
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String bucketName = "<yourBucketName>";
    
    // 创建OSSClient实例。
    OSSClient ossClient = new OSSClient(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();
    

    返回结果如下:

    Objects:
    fun/test.jpg
    
    CommonPrefixes:
    fun/movie/