如果您细心对比过 JSON Java SDK 和 XML Java SDK 的文档,您会发现并不是一个简单的增量更新。XML Java SDK 在架构、可用性和安全性上有了非常大的提升,而且在易用性、健壮性和性能上也做了非常大的改进。如果您想要升级到 XML Java SDK,请参考下面的指引,完成 Java SDK 的升级工作。
功能对比
功能 | XML Java SDK | JSON Java SDK |
文件上传 | 支持本地文件、字节流、输入流上传 默认覆盖上传 智能判断上传模式:简单上传最大支持5GB 分块上传最大支持48.82TB(50,000GB) | 只支持本地文件上传 可选择是否覆盖 需要手动选择是简单还是分块上传 简单上传最大支持20MB 分块上传最大支持64GB |
文件删除 | 支持批量删除 | 只支持单文件删除 |
存储桶基本操作 | 创建存储桶 获取存储桶 删除存储桶 | 不支持 |
存储桶 ACL操作 | 设置存储桶 ACL 获取设置存储桶 ACL 删除设置存储桶 ACL | 不支持 |
存储桶生命周期 | 创建存储桶生命周期 获取存储桶生命周期 删除存储桶生命周期 | 不支持 |
目录操作 | 不单独提供接口 | 创建目录 查询目录 删除目录 |
升级步骤
请按照以下步骤升级 Java SDK。
1. 更新 Java SDK
在 maven 项目的 pom.xml 文件中添加如下依赖:
<!-- https://mvnrepository.com/artifact/com.qcloud/cos_api --><dependency><groupId>com.qcloud</groupId><artifactId>cos_api</artifactId><version>5.x.x</version></dependency>
2. 更改存储桶名称和可用区域简称
XML Java SDK 的存储桶名称和可用区域简称与 JSON Java SDK 的不同,需要您进行相应的更改。
存储桶 Bucket
XML SDK 存储桶名称由两部分组成:用户自定义字符串和 APPID,两者以中划线“-”相连。
例如
examplebucket-1250000000
,其中 examplebucket
为用户自定义字符串,1250000000
为 APPID。说明:
设置 Bucket,请参考以下示例代码:
// 存储桶名称,格式为:BucketName-APPIDString bucketName = "examplebucket-1250000000";// 以下是向这个存储桶上传一个文件的示例String key = "exampleobject";// 本地文件路径String localFilePath = "/path/to/localFile";File localFile = new File(localFilePath);PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);// 设置存储类型:标准存储(Standard), 低频存储(Standard_IA)和归档存储(ARCHIVE)。默认是标准存储(Standard)putObjectRequest.setStorageClass(StorageClass.Standard_IA);PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);// putobjectResult 会返回文件的 etagString etag = putObjectResult.getETag();
存储桶可用区域简称 Region
XML SDK 的存储桶可用区域简称发生了变化,不同区域在 JSON SDK 和 XML SDK 中的对应关系请查看下表:
地域 | XML SDK 地域简称 | JSON SDK 地域简称 |
北京一区(华北) | ap-beijing-1 | tj |
北京 | ap-beijing | bj |
上海(华东) | ap-shanghai | sh |
广州(华南) | ap-guangzhou | gz |
成都(西南) | ap-chengdu | cd |
重庆 | ap-chongqing | 无 |
中国香港 | ap-hongkong | hk |
新加坡 | ap-singapore | sgp |
法兰克福 | eu-frankfurt | ger |
首尔 | ap-seoul | 无 |
硅谷 | na-siliconvalley | 无 |
弗吉尼亚 | na-ashburn | 无 |
曼谷 | ap-bangkok | 无 |
在初始化
COSClient
的时候,将存储桶所在区域的简称设置到 ClientConfig
中:ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing-1"));COSClient cosClient = new COSClient(cred, clientConfig);
3. 更改 API
API 主要有以下变化:
(1)没有单独的目录接口
在 XML SDK 中,不再提供单独的目录接口。对象存储中本身是没有文件夹或目录的概念的,对象存储不会因为上传对象
project/text.txt
而创建一个 project 文件夹。为了满足用户使用习惯,对象存储在控制台、COS browser 等图形化工具中,通过调用 GETBucket 接口,并指定 prefix 和 delimiter,模拟文件夹或目录的展示方式。例如:您上传了四个对象
project/folder1/picture.jpg
、project/folder2/text.txt
、project/folder2/music.mp3
、project/video.mp4
。
在 Java SDK 中,您可以调用 listObjects 方法,指定 prefix 为 project/
和 delimiter 为/
,调用返回对象的 getCommonPrefixes 方法, 获取到具有相同前缀的目录:String bucketName = "examplebucket-1250000000";cosClient.putObject(bucketName, "project/folder1/picture.jpg", "content");cosClient.putObject(bucketName, "project/folder2/text.txt", "content");cosClient.putObject(bucketName, "project/folder2/music.mp3", "content");cosClient.putObject(bucketName, "project/video.mp4", "content");ListObjectsRequest listObjectsRequest = new ListObjectsRequest();listObjectsRequest.setBucketName(bucketName);listObjectsRequest.setPrefix("project/");listObjectsRequest.setDelimiter("/");// 实际使用,您可以将 maxKeys 设为最大值 1000,以减少请求次数listObjectsRequest.setMaxKeys(2);String nextMarker = "";for (; ; ) {listObjectsRequest.setMarker(nextMarker);ObjectListing objectListing = cosClient.listObjects(listObjectsRequest);// getCommonPrefixes + getObjectSummaries 返回条目数 <= maxKeys// 两次循环会输出 project/folder1/ 和 project/folder2/for (String prefix : objectListing.getCommonPrefixes()) {System.out.println(prefix);}// 两次循环会输出 project/video.mp4for (COSObjectSummary object : objectListing.getObjectSummaries()) {System.out.println(object.getKey());}// 判断是否还有条目if (!objectListing.isTruncated()) {break;}// 一次未获取完毕,以 nextMarker 作为下一次 listObjects 请求的 markernextMarker = objectListing.getNextMarker();}
(2)TransferManager
在 XML Java SDK 中,我们封装了上传、下载和复制操作,命名为
TransferManager
,优化了 API 设计和传输性能,建议您直接使用。TransferManager
的主要特性有:支持上传下载过程的暂停和恢复。
支持根据文件大小智能选择简单上传还是分块上传,您可以设置该判断临界。
支持任务状态的监听。
使用
TransferManager
上传的示例代码:String key = "exampleobject";File localFile = new File(localFilePath);String bucketName = "examplebucket-1250000000";PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);// 返回一个异步结果 Upload, 可同步的调用 waitForUploadResult 等待 upload 结束, 成功返回 UploadResult, 失败抛出异常.Upload upload = transferManager.upload(putObjectRequest);Thread.sleep(1000);// 暂停任务,获取 PersistableUploadPersistableUpload persistableUpload = upload.pause();//也可通过如下方式,获取 PersistableUpload// while(persistableUpload == null) {// persistableUpload = upload.getResumeableMultipartUploadId();// System.out.println(System.currentTimeMillis());// Thread.sleep(100);// }// 恢复上传upload = transferManager.resumeUpload(persistableUpload);// 等待上传任务完成UploadResult uploadResult = upload.waitForUploadResult();System.out.println(uploadResult.getETag());
(3)签名算法不同
通常您不需要手动计算签名,但如果您将 SDK 的签名返回给前端使用,请注意我们的签名算法发生了改变。签名不再区分单次和多次签名,而是通过设置签名的有效期来保证安全性。具体的算法请参见 XML 请求签名 文档。
(4)新增 API
XML Java SDK 新增 API,您可根据需求进行调用。包括:
存储桶的操作,如 createBucket、GetBucket(List Objects)、ListBuckets 等。
存储桶 ACL 的操作,如 getBucketAcl、setBucketAcl 等。
存储桶生命周期的操作,如 setBucketLifecycleConfiguration、getBucketLifecycleConfiguration、 deleteBucketLifecycleConfiguration 等。