简介
本文档提供关于列出对象操作相关的 API 概览以及 SDK 示例代码。
API | 操作名 | 操作描述 |
GET Bucket(List Objects) | 查询对象列表 | 查询存储桶下的部分或者全部对象 |
GET Bucket Object Versions | 查询对象及其历史版本列表 | 查询存储桶下的部分或者全部对象及其历史版本信息 |
简单操作
简单操作由 COSClient 类型发起请求,使用简单操作之前必须先创建一个 COSClient 实例。COSClient 实例是并发安全的,这里推荐一个进程只创建一个 COSClient 实例,当不会再通过这个实例发起请求的时候,再选择关闭这个实例。
创建 COSClient
调用 COS 的接口之前,必须先创建一个 COSClient 的实例。
// 创建 COSClient 实例,这个实例用来后续调用请求COSClient createCOSClient() { // 设置用户身份信息。 // SECRETID 和 SECRETKEY 请登录访问管理控制台 https://console.cloud.tencent.com/cam/capi 进行查看和管理 String secretId = System.getenv("secretId");//用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140 String secretKey = System.getenv("secretKey");//用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140 COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
// ClientConfig 中包含了后续请求 COS 的客户端设置: ClientConfig clientConfig = new ClientConfig();
// 设置 bucket 的地域 // COS_REGION 请参见 https://cloud.tencent.com/document/product/436/6224 clientConfig.setRegion(new Region("COS_REGION"));
// 设置请求协议, http 或者 https // 5.6.53 及更低的版本,建议设置使用 https 协议 // 5.6.54 及更高版本,默认使用了 https clientConfig.setHttpProtocol(HttpProtocol.https);
// 以下的设置,是可选的:
// 设置 socket 读取超时,默认 30s clientConfig.setSocketTimeout(30*1000); // 设置建立连接超时,默认 30s clientConfig.setConnectionTimeout(30*1000);
// 如果需要的话,设置 http 代理,ip 以及 port clientConfig.setHttpProxyIp("httpProxyIp"); clientConfig.setHttpProxyPort(80);
// 生成 cos 客户端。 return new COSClient(cred, clientConfig);}
使用临时密钥创建 COSClient
如果要使用临时密钥请求 COS,则需要用临时密钥创建 COSClient。
本 SDK 并不能生成临时密钥,而需要使用额外的操作来生成,详情请参见 临时密钥生成。
// 创建 COSClient 实例,这个实例用来后续调用请求COSClient createCOSClient() { // 这里需要已经获取到临时密钥的结果。 // 临时密钥的生成参见 https://cloud.tencent.com/document/product/436/14048#cos-sts-sdk String tmpSecretId = "TMPSECRETID"; String tmpSecretKey = "TMPSECRETKEY"; String sessionToken = "SESSIONTOKEN";
COSCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);
// ClientConfig 中包含了后续请求 COS 的客户端设置: ClientConfig clientConfig = new ClientConfig();
// 设置 bucket 的地域 // COS_REGION 请参照 https://cloud.tencent.com/document/product/436/6224 clientConfig.setRegion(new Region("COS_REGION"));
// 设置请求协议, http 或者 https // 5.6.53 及更低的版本,建议设置使用 https 协议 // 5.6.54 及更高版本,默认使用了 https clientConfig.setHttpProtocol(HttpProtocol.https);
// 以下的设置,是可选的:
// 设置 socket 读取超时,默认 30s clientConfig.setSocketTimeout(30*1000); // 设置建立连接超时,默认 30s clientConfig.setConnectionTimeout(30*1000);
// 如果需要的话,设置 http 代理,ip 以及 port clientConfig.setHttpProxyIp("httpProxyIp"); clientConfig.setHttpProxyPort(80);
// 生成 cos 客户端。 return new COSClient(cred, clientConfig);}
列出第一页对象
列出存储桶下的部分对象。
方法原型
public ObjectListing listObjects(ListObjectsRequest listObjectsRequest) throws CosClientException, CosServiceException;
请求示例
// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建// 详细代码参见本页:简单操作 -> 创建 COSClientCOSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式String bucketName = "examplebucket-1250000000";
ListObjectsRequest listObjectsRequest = new ListObjectsRequest();// 设置 bucket 名称listObjectsRequest.setBucketName(bucketName);// 设置列出的对象名以 prefix 为前缀listObjectsRequest.setPrefix("");// 设置最大列出多少个对象, 一次 listobject 最大支持1000listObjectsRequest.setMaxKeys(1000);
// 保存列出的结果ObjectListing objectListing = null;
try { objectListing = cosClient.listObjects(listObjectsRequest);} catch (CosServiceException e) { e.printStackTrace();} catch (CosClientException e) { e.printStackTrace();}
// object summary 表示此次列出的对象列表List cosObjectSummaries = objectListing.getObjectSummaries();for (COSObjectSummary cosObjectSummary : cosObjectSummaries) { // 对象的 key String key = cosObjectSummary.getKey(); // 对象的 etag String etag = cosObjectSummary.getETag(); // 对象的长度 long fileSize = cosObjectSummary.getSize(); // 对象的存储类型 String storageClasses = cosObjectSummary.getStorageClass();}
if (objectListing.isTruncated()) { // 表示还没有列完,被截断了
// 下一次开始的位置 String nextMarker = objectListing.getNextMarker();}
// 确认本进程不再使用 cosClient 实例之后,关闭即可cosClient.shutdown();
参数说明
参数名称 | 描述 | 类型 |
listObjectsRequest | 获取文件列表请求 | ListObjectsRequest |
Request 成员说明 :
Request 成员 | 设置方法 | 描述 | 类型 |
bucketName | 构造函数或 set 方法 | Bucket 的命名格式为 BucketName-APPID ,详情请参见 命名规范 | String |
prefix | 构造函数或 set 方法 | 限制返回的结果对象,以 prefix 为前缀。默认不进行限制,即 Bucket 下所有的成员。默认值为"" ,表示空 |
String |
marker | 构造函数或 set 方法 | 标记 list 的起点位置,第一次可设置为空,后续请求需设置为上一次 listObjects 返回值中的 nextMarker | String |
delimiter | 构造函数或 set 方法 | 分隔符,限制返回的是以 prefix 开头,并以 delimiter 第一次出现的结束的路径 | String |
maxKeys | 构造函数或 set 方法 | 最大返回的成员个数(不得超过1000)。默认值: 1000 | Integer |
返回结果说明
成功:返回 ObjectListing 类型, 包含所有的成员, 以及 nextMarker。 失败:抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。
列出第二页对象
列出被截断的剩下的部分对象。
方法原型
public ObjectListing listObjects(ListObjectsRequest listObjectsRequest) throws CosClientException, CosServiceException;
请求示例
// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建// 详细代码参见本页:简单操作 -> 创建 COSClientCOSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式String bucketName = "examplebucket-1250000000";// 下一次开始的位置// 通过被截断的列对象请求获取,参考上面的 列出第一页对象String nextMarker = "nextMarker";
ListObjectsRequest listObjectsRequest = new ListObjectsRequest();// 设置 bucket 名称listObjectsRequest.setBucketName(bucketName);// 设置列出的对象名以 prefix 为前缀listObjectsRequest.setPrefix("");// 设置最大列出多少个对象, 一次 listobject 最大支持1000listObjectsRequest.setMaxKeys(1000);// 设置被截断开始的位置listObjectsRequest.setMarker(nextMarker);
// 保存列出的结果ObjectListing objectListing = null;
try { objectListing = cosClient.listObjects(listObjectsRequest);} catch (CosServiceException e) { e.printStackTrace();} catch (CosClientException e) { e.printStackTrace();}
// object summary 表示此次列出的对象列表List cosObjectSummaries = objectListing.getObjectSummaries();for (COSObjectSummary cosObjectSummary : cosObjectSummaries) { // 对象的 key String key = cosObjectSummary.getKey(); // 对象的etag String etag = cosObjectSummary.getETag(); // 对象的长度 long fileSize = cosObjectSummary.getSize(); // 对象的存储类型 String storageClasses = cosObjectSummary.getStorageClass();}
if (objectListing.isTruncated()) { // 表示还没有列完,被截断了
// 下一次开始的位置 String nextMarker = objectListing.getNextMarker();}
// 确认本进程不再使用 cosClient 实例之后,关闭即可cosClient.shutdown();
参数说明
参数名称 | 描述 | 类型 |
listObjectsRequest | 获取文件列表请求 | ListObjectsRequest |
Request 成员说明 :
Request 成员 | 设置方法 | 描述 | 类型 |
bucketName | 构造函数或 set 方法 | Bucket 的命名格式为 BucketName-APPID ,详情请参见 命名规范 | String |
prefix | 构造函数或 set 方法 | 限制返回的结果对象,以 prefix 为前缀。默认不进行限制,即 Bucket 下所有的成员。默认值为"" ,表示空 |
String |
marker | 构造函数或 set 方法 | 标记 list 的起点位置,第一次可设置为空,后续请求需设置为上一次 listObjects 返回值中的 nextMarker | String |
delimiter | 构造函数或 set 方法 | 分隔符,限制返回的是以 prefix 开头,并以 delimiter 第一次出现的结束的路径 | String |
maxKeys | 构造函数或 set 方法 | 最大返回的成员个数(不得超过1000)。默认值: 1000 | Integer |
返回结果说明
成功:返回 ObjectListing 类型, 包含所有的成员, 以及 nextMarker。 失败:抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。
列出目录下的对象和子目录
方法原型
public ObjectListing listObjects(ListObjectsRequest listObjectsRequest) throws CosClientException, CosServiceException;
请求示例
// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建// 详细代码参见本页:简单操作 -> 创建 COSClientCOSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式String bucketName = "examplebucket-1250000000";
ListObjectsRequest listObjectsRequest = new ListObjectsRequest();// 设置 bucket 名称listObjectsRequest.setBucketName(bucketName);// prefix 表示列出的对象名以 prefix 为前缀// 这里填要列出的目录的相对 bucket 的路径listObjectsRequest.setPrefix("/dir/");// delimiter 表示目录的截断符, 例如:设置为 / 则表示对象名遇到 / 就当做一级目录)listObjectsRequest.setDelimiter("/");// 设置最大遍历出多少个对象, 一次 listobject 最大支持1000listObjectsRequest.setMaxKeys(1000);
// 保存每次列出的结果ObjectListing objectListing = null;
do { try { objectListing = cosClient.listObjects(listObjectsRequest); } catch (CosServiceException e) { e.printStackTrace(); return; } catch (CosClientException e) { e.printStackTrace(); return; }
// 这里保存列出来的子目录 List commonPrefixes = objectListing.getCommonPrefixes(); for (String commonPrefix : commonPrefixes) { System.out.println(commonPrefix); }
// 这里保存列出的对象列表 List cosObjectSummaries = objectListing.getObjectSummaries(); for (COSObjectSummary cosObjectSummary : cosObjectSummaries) { // 对象的 key String key = cosObjectSummary.getKey(); // 对象的etag String etag = cosObjectSummary.getETag(); // 对象的长度 long fileSize = cosObjectSummary.getSize(); // 对象的存储类型 String storageClasses = cosObjectSummary.getStorageClass(); }
// 标记下一次开始的位置 String nextMarker = objectListing.getNextMarker(); listObjectsRequest.setMarker(nextMarker);} while (objectListing.isTruncated());
// 确认本进程不再使用 cosClient 实例之后,关闭即可cosClient.shutdown();
参数说明
参数名称 | 描述 | 类型 |
listObjectsRequest | 获取文件列表请求 | ListObjectsRequest |
Request 成员说明 :
Request 成员 | 设置方法 | 描述 | 类型 |
bucketName | 构造函数或 set 方法 | Bucket 的命名格式为 BucketName-APPID ,详情请参见 命名规范 | String |
prefix | 构造函数或 set 方法 | 限制返回的结果对象,以 prefix 为前缀。默认不进行限制,即 Bucket 下所有的成员。默认值为"" ,表示空 |
String |
marker | 构造函数或 set 方法 | 标记 list 的起点位置,第一次可设置为空,后续请求需设置为上一次 listObjects 返回值中的 nextMarker | String |
delimiter | 构造函数或 set 方法 | 分隔符,限制返回的是以 prefix 开头,并以 delimiter 第一次出现的结束的路径 | String |
maxKeys | 构造函数或 set 方法 | 最大返回的成员个数(不得超过1000)。默认值: 1000 | Integer |
返回结果说明
成功:返回 ObjectListing 类型, 包含所有的成员, 以及 nextMarker。 失败:抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。
列出对象历史版本
列出对象的每一个历史版本。说明 需要存储桶开启版本控制。
方法原型
public VersionListing listVersions(ListVersionsRequest listVersionsRequest) throws CosClientException, CosServiceException;
请求示例
// 调用 COS 接口之前必须保证本进程存在一个 COSClient 实例,如果没有则创建// 详细代码参见本页:简单操作 -> 创建 COSClientCOSClient cosClient = createCOSClient();
// 存储桶的命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式String bucketName = "examplebucket-1250000000";
ListVersionsRequest listVersionsRequest = new ListVersionsRequest();// 设置 bucket 名称listVersionsRequest.setBucketName(bucketName);// prefix 表示列出的对象名以 prefix 为前缀// 这里填要列出的目录的相对 bucket 的路径listVersionsRequest.setPrefix("");// delimiter 表示目录的截断符, 例如:设置为 / 则表示对象名遇到 / 就当做一级目录)listVersionsRequest.setDelimiter("/");// 设置最大遍历出多少个对象, 一次 listobject 最大支持1000listVersionsRequest.setMaxResults(1000);
VersionListing versionListing = null;
do { try { versionListing = cosClient.listVersions(listVersionsRequest); } catch (CosServiceException e) { e.printStackTrace(); return; } catch (CosClientException e) { e.printStackTrace(); return; }
List cosVersionSummaries = versionListing.getVersionSummaries(); for (COSVersionSummary cosVersionSummary : cosVersionSummaries) { System.out.println(cosVersionSummary.getKey() + ":" + cosVersionSummary.getVersionId()); }
// 下一次开始的位置有 2 个标志,一个是对象名,一个是对象版本 String keyMarker = versionListing.getNextKeyMarker(); String versionIdMarker = versionListing.getNextVersionIdMarker();
listVersionsRequest.setKeyMarker(keyMarker); listVersionsRequest.setVersionIdMarker(versionIdMarker);
} while (versionListing.isTruncated());
// 确认本进程不再使用 cosClient 实例之后,关闭即可cosClient.shutdown();
参数说明
参数名称 | 描述 | 类型 |
listVersionsRequest | 获取对象版本信息请求 | ListVersionsRequest |
Request 成员说明 :
Request 成员 | 设置方法 | 描述 | 类型 |
bucketName | 构造函数或 set 方法 | Bucket 的命名格式为 BucketName-APPID ,详情请参见 命名规范 | String |
prefix | 构造函数或 set 方法 | 限制返回的结果对象,以 prefix 为前缀。默认不进行限制,即 Bucket 下所有的成员。<默认值为"" ,表示空 |
String |
keyMarker | 构造函数或 set 方法 | 标记 list 的起点位置,第一次可设置为空,后续请求需设置为上一次 listObjects 返回值中的 nextKeyMarker | String |
versionIdMarker | 构造函数或 set 方法 | 标记 list 的起点位置,第一次可设置为空,后续请求需设置为上一次 listObjects 返回值中的 nextVersionIdMarker | String |
delimiter | 构造函数或 set 方法 | 分隔符,限制返回的是以 prefix 开头,并以 delimiter 第一次出现的结束的路径 | String |
maxResults | 构造函数或 set 方法 | 最大返回的成员个数(不得超过1000)。默认值: 1000 | Integer |
返回结果说明
成功:返回 ObjectListing 类型, 包含所有的成员, 以及 nextKeyMarker 和 nextVersionIdMarker。失败:抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。
对象存储官网1折活动,限时活动,即将结束,速速收藏
同尘科技为腾讯云授权服务中心。
购买腾讯云产品享受折上折,更有现金返利。同意关联立享优惠
转转请注明出处:http://www.yunxiaoer.com/145752.html