如果您细心对比过 JSON Java SDK 和 XML Java SDK 的文档,您会发现并不是一个简单的增量更新。XML Java SDK 在架构、可用性和安全性上有了非常大的提升,而且在易用性、健壮性和性能上也做了非常大的改进。如果您想要升级到 XML Java SDK,请参考下面的指引,完成 Java SDK 的升级工作。
功能 | XML Java SDK V5 | JSON Java SDK V4 |
---|---|---|
文件上传 | 支持本地文件、字节流、输入流上传默认覆盖上传智能判断上传模式:简单上传最大支持5GB分块上传最大支持48.82TB(50,000GB) | 只支持本地文件上传可选择是否覆盖需要手动选择是简单还是分块上传简单上传最大支持20MB分块上传最大支持64GB |
文件删除 | 支持批量删除 | 只支持单文件删除 |
存储桶基本操作 | 创建存储桶获取存储桶删除存储桶 | 不支持 |
存储桶 ACL操作 | 设置存储桶 ACL获取设置存储桶 ACL删除设置存储桶 ACL | 不支持 |
存储桶生命周期 | 创建存储桶生命周期获取存储桶生命周期删除存储桶生命周期 | 不支持 |
目录操作 | 不单独提供接口 | 创建目录查询目录删除目录 |
用户在maven项目pom.xml 文件中查找:cos_api
<groupId>com.qcloud</groupId>
<artifactId>cos_api</artifactId>
<version>5.x.x</version>
<groupId>com.qcloud</groupId>
<artifactId>cos_api</artifactId>
<version>4.x</version>
新建bucket默认开启XML控制台权限,即V5版本,且V4控制台权限不开启,因此通过腾讯云控制台访问会看到如下:https://console.cloud.tencent.com/cos5/bucketxxx,域名信息只能看到V5版本域名格式。
格式: <BucketName-APPID>.cos.region.myqcloud.com (region=地域简称)
格式: <BucketName-APPID>.cosregion.myqcloud.com (region=地域简称)
XML SDK V5 的存储桶可用区域简称发生了变化,不同区域在 JSON SDK V4 和 XML SDK V5 中的对应关系请表:(注意V4地域“无”表示V4无法使用该地域,无法使用JSON SDK V4访问该地域的bucket)
地域 | XML SDK V5地域简称 | JSON SDK V4地域简称 |
---|---|---|
北京一区(华北) | ap-beijing-1 | tj |
北京 | ap-beijing | bj |
上海(华东) | ap-shanghai | sh |
广州(华南) | ap-guangzhou | gz |
成都(西南) | ap-chengdu | cd |
重庆 | ap-chongqing | 无 |
香港 | ap-hongkong | hk |
新加坡 | ap-singapore | sgp |
多伦多 | na-toronto | ca |
法兰克福 | eu-frankfurt | ger |
深圳金融 | ap-shenzhen-fsi | 无 |
上海金融 | ap-shenzhen-fsi | 无 |
北京金融 | ap-shenzhen-fsi | 无 |
南京 | ap-nanjing | 无 |
东京 | ap-tokyo | 无 |
孟买 | ap-mumbai | 无 |
首尔 | ap-seoul | 无 |
硅谷 | na-siliconvalley | 无 |
弗吉尼亚 | na-ashburn | 无 |
曼谷 | ap-bangkok | 无 |
莫斯科 | eu-moscow | 无 |
V4 SDK对应V4版本域名和地域简称;V5 SDK对应V5版本域名和地域简称,不支持交叉访问;COS V5 SDK版本和V4 SDK版本,官网提供了具体文档,详情可参照如下:
参照:/document/product/436/31355
XML Java SDK 发布在 maven 中央仓库,推荐您使用 maven 自动管理依赖方式引入。
在 maven 项目的 pom.xml 文件中添加如下依赖:
<dependency>
<groupId>com.qcloud</groupId>
<artifactId>cos_api</artifactId>
<version>5.x.x</version>
</dependency>
当然您也可以在 maven 中央仓库中直接下载对应版本的 jar 包,手动加入到您的项目当中。
XML Java SDK 的存储桶名称和可用区域简称与 JSON Java SDK 的不同,需要您进行相应的更改。
V5存储桶名称,格式为:BucketName-APPID Eg:examplebucket-1250000000
V4存储桶名称,格式为:BucketName Eg:examplebucket
设置 Bucket,请参考以下示例代码:
// 存储桶名称,格式为:BucketName-APPID
String bucketName = "examplebucket-1250000000";
// 以下是向这个存储桶上传一个文件的示例
String key = "exampleobject";
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 会返回文件的 etag
String etag = putObjectResult.getETag();
XML SDK 的存储桶可用区域和简称发生了变化,不同区域在 JSON SDK 和 XML SDK 中的对应关系请参照“支持地域和简称变化对比”:
在初始化COSClient的时候,将存储桶所在区域的简称设置到ClientConfig中:
ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing-1"));
COSClient cosClient = new COSClient(cred, clientConfig);
升级到 XML SDK 之后,一些操作的 API 发生了变化,请您根据实际需求进行相应的更改。同时我们做了封装让 SDK 更加易用,具体请参见我们的示例和 快速入门 文档。
API 主要有以下变化:
在 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.mp4
for (COSObjectSummary object : objectListing.getObjectSummaries()) {
System.out.println(object.getKey());
}
// 判断是否还有条目
if (!objectListing.isTruncated()) {
break;
}
// 一次未获取完毕,以 nextMarker 作为下一次 listObjects 请求的 marker
nextMarker = objectListing.getNextMarker();
}
在 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);
// 暂停任务,获取 PersistableUpload
PersistableUpload 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());
通常您不需要手动计算签名,但如果您将 SDK 的签名返回给前端使用,请注意我们的签名算法发生了改变。签名不再区分单次和多次签名,而是通过设置签名的有效期来保证安全性。具体的算法请参见 XML 请求签名 文档
XML Java SDK 新增 API,您可根据需求进行调用。包括:
了解更多请参见 Java SDK 快速入门 文档。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。