列出对象键

适用场景

云平台 COS 支持按照前缀顺序列出对象键，您也可以在对象键中使用 / 字符来实现类似传统文件系统的层级结构，COS 也支持按照分隔符来做层级结构的选择和浏览。

您可以列出单个存储桶中的所有对象键，根据前缀的 UTF-8 二进制顺序列出，或选择指定前缀过滤对象键的列表。例如加入参数 t 将列出 tapd 的对象，而跳过以 a 或其他字符为前缀的对象。

加入 / 分隔符可将根据此分隔符重新组织对象键，您可以结合前缀和分隔符来实现类似文件夹检索的功能。例如加入前缀参数 t 并加入分隔符 / 将会直接列出类似 tapd/file 的对象键。

云平台 COS 在单个存储桶中支持无限数量的对象，因此对象键列表可能非常大。为了管理方便，单个列出对象接口将最多返回 1000 个键值的结果内容，同时会返回指示器来告知是否存在截断。您可以根据指示器和分隔符来发送一系列的列出对象键请求，实现列出所有键值，或寻找您所需要的内容。

使用方法

使用 REST API

您可以直接使用 REST API 发起一个获取对象请求，可参考 Get Bucket 文档说明。

使用 Java SDK

对象存储 COS 的 Java SDK 中提供了此方法，可参考 Java SDK 接口文档 Get Bucket (List Objects) 部分。

步骤说明

1. 初始化客户端 cosclient。

2. 使用 listObjects 列出 object，每次最多列出 1000 个 object，如果需要列出所有的或者超过 1000 个, 则需要循环调用 listObjects。

代码示例

1. ListObjectsRequest包含了列出 Object 的请求, 可设置列出的 Object 的前缀, 分隔符, 示例代码如下:

   // 1 初始化用户身份信息(secretId, secretKey)  
   COSCredentials cred = new BasicCOSCredentials("AKIDXXXXXXXX", "1A2Z3YYYYYYYYYY");
   // 2 设置bucket的区域, COS地域的简称请参照 /document/product/436/6224  
   ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing-1"));
   // 3 生成cos客户端  
   COSClient cosclient = new COSClient(cred, clientConfig);
   // bucket名需包含appid
   String bucketName = "mybucket-1251668577";
   
   ListObjectsRequest listObjectsRequest = new ListObjectsRequest();
   // 设置bucket名称  
   listObjectsRequest.setBucketName(bucketName);
   // prefix表示列出的object的key以prefix开始
   listObjectsRequest.setPrefix("aaa/bbb");
   // deliter表示分隔符, 设置为/表示列出当前目录下的object, 设置为空表示列出所有的object  
   listObjectsRequest.setDelimiter("");
   // 如果object的路径中含有特殊字符, 建议使用url编码方式, 得到object的key后, 需要进行url decode  
   listObjectsRequest.setEncodingType("url");
   // 设置最大遍历出多少个对象, 一次listobject最大支持1000
   listObjectsRequest.setMaxKeys(1000);
   ObjectListing objectListing = null;
   try {
       objectListing = cosclient.listObjects(listObjectsRequest);
   } catch (CosServiceException e) {
       e.printStackTrace();
   } catch (CosClientException e) {
       e.printStackTrace();
   }
   // common prefix表示表示被delimiter截断的路径, 如delimter设置为/, common prefix则表示所有子目录的路径
   List<String> commonPrefixs = objectListing.getCommonPrefixes();
   
   // object summary表示所有列出的object列表
   List<COSObjectSummary> cosObjectSummaries = objectListing.getObjectSummaries();
   for (COSObjectSummary cosObjectSummary : cosObjectSummaries) {
       // 文件的路径key
       String key = cosObjectSummary.getKey();
       // 如果使用的encodingtype是url, 则进行url decode
       try {                                                               
           key = URLDecoder.decode(key, "utf-8"); 
       } catch (UnsupportedEncodingException e) {                          
           continue;                                                       
       }
       // 文件的etag
       String etag = cosObjectSummary.getETag();
       // 文件的长度
       long fileSize = cosObjectSummary.getSize();
       // 文件的存储类型
       String storageClasses = cosObjectSummary.getStorageClass();
   }
   
   cosclient.shutdown();

2. 如果要获取超过 maxkey 数量的 Object 或者获取所有的 Object, 则需要循环调用 listobject, 用上一次返回的 next marker 作为下一次调用的 marker, 直到返回的 truncated 为 false。

   // 1 初始化用户身份信息(secretId, secretKey)
   COSCredentials cred = new BasicCOSCredentials("AKIDXXXXXXXX", "1A2Z3YYYYYYYYYY");
   // 2 设置bucket的区域, COS地域的简称请参照 /document/product/436/6224
   ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing-1"));
   // 3 生成cos客户端
   COSClient cosclient = new COSClient(cred, clientConfig);
   // bucket名需包含appid
   String bucketName = "mybucket-1251668577";
   
   ListObjectsRequest listObjectsRequest = new ListObjectsRequest();
   // 设置bucket名称
   listObjectsRequest.setBucketName(bucketName);
   // prefix表示列出的object的key以prefix开始
   listObjectsRequest.setPrefix("aaa/bbb");
   // deliter表示分隔符, 设置为/表示列出当前目录下的object, 设置为空表示列出所有的object
   listObjectsRequest.setDelimiter("");
   // 如果object的路径中含有特殊字符, 建议使用url编码方式, 得到object的key后, 需要进行url decode
   listObjectsRequest.setEncodingType("url");
   // 设置最大遍历出多少个对象, 一次listobject最大支持1000
   listObjectsRequest.setMaxKeys(1000);
   ObjectListing objectListing = null;
   do {
   
       try {
           objectListing = cosclient.listObjects(listObjectsRequest);
       } catch (CosServiceException e) {
           e.printStackTrace();
           return;
       } catch (CosClientException e) {
           e.printStackTrace();
           return;
       }
       // common prefix表示表示被delimiter截断的路径, 如delimter设置为/, common prefix则表示所有子目录的路径
       List<String> commonPrefixs = objectListing.getCommonPrefixes();
   
       // object summary表示所有列出的object列表
       List<COSObjectSummary> cosObjectSummaries = objectListing.getObjectSummaries();
       for (COSObjectSummary cosObjectSummary : cosObjectSummaries) {
           // 文件的路径key
           String key = cosObjectSummary.getKey();
           // 如果使用的encodingtype是url, 则进行url decode
           try {
               key = URLDecoder.decode(key, "utf-8");
           } catch (UnsupportedEncodingException e) {
               continue;
           }
           // 文件的etag
           String etag = cosObjectSummary.getETag();
           // 文件的长度
           long fileSize = cosObjectSummary.getSize();
           // 文件的存储类型
           String storageClasses = cosObjectSummary.getStorageClass();
       }
   
       // 获取下一次请求的next marker
       String nextMarker = "";
       try {
           nextMarker = URLDecoder.decode(objectListing.getNextMarker(), "utf-8");
       } catch (UnsupportedEncodingException e) {
           e.printStackTrace();
           return;
       }
       listObjectsRequest.setMarker(nextMarker);
   } while (objectListing.isTruncated());
   
   cosclient.shutdown();