下载与安装
相关资源
对象存储服务的 XML Java SDK 资源下载地址：XML Java SDK。
示例 Demo 下载地址： COS XML Java SDK 示例。
环境依赖
SDK 支持 JDK 1.7、1.8及以上版本。
JDK 安装方式请参见 Java 安装与配置。
COS Java SDK 中的常见类所在包分别为：
客户端配置相关类在包 com.qcloud.cos.* 下。
权限相关类在 com.qcloud.cos.auth.* 子包下。
异常相关类在 com.qcloud.cos.exception.* 子包下。
请求相关类在 com.qcloud.cos.model.* 子包下。
地域相关类在 com.qcloud.cos.region.* 子包下。
高级 API 接口在 com.qcloud.cos.transfer.* 子包下。
安装 SDK
用户可以通过 maven 和源码两种方式安装 Java SDK：
maven 安装
在 maven 工程的 pom.xml 文件中添加相关依赖，内容如下：
源码安装
从 XML Java SDK 下载源码，通过 maven 导入。比如 eclipse，依次选择 【File】>【Import】>【maven】>【Existing Maven Projects】。
卸载 SDK
通过删除 pom 依赖或源码即可卸载 SDK。
开始使用
下面为您介绍如何使用 COS Java SDK 完成一个基础操作，如初始化客户端、创建存储桶、查询存储桶列表、上传对象、查询对象列表、下载对象和删除对象。
术语解释
名称描述APPID开发者访问 COS 服务时拥有的用户维度唯一资源标识，用以标识资源SecretId开发者拥有的项目身份识别 ID，用以身份认证SecretKey开发者拥有的项目身份密钥BucketCOS 中用于存储数据的容器ObjectCOS 中存储的具体文件，是存储的基本实体Region域名中的地域信息EndpointEndpoint 由 Region 和域名组成，具体格式为： "."，其中 Domain 为自定义的域名。在控制台创建 Bucket 时，可以看到对应的访问地址为："."，Bucket 后面的部分即为 Endpoint。ACL访问控制列表（Access Control List），是指特定 Bucket 或 Object 的访问控制信息列表CORS跨域资源共享（Cross-Origin Resource Sharing）， 指发起请求的资源所在域不同于该请求所指向资源所在的域的 HTTP 请求Multipart Uploads分块上传，COS 服务为上传文件提供的一种分块上传模式
导入类名
COS Java SDK 的包名为com.qcloud.cos.*，您可以通过 Eclipse 或者 Intellij 等 IDE 工具，导入程序运行所需要的类。
初始化客户端
在执行任何和 COS 服务相关请求之前，都需要先生成 COSClient 类的对象， COSClient 是调用 COS API 接口的对象。在生成一个 COSClient 实例后可反复使用，且线程安全。最后程序或服务退出时，需要关闭客户端。
在初始化客户端，首先需要通过实现 SelfDefinedEndpointBuilder 类，以便于构造出接下来的请求中所需要的服务器信息，包括 Endpoint、GetServiceEndpoint 等。
// 实现 EndpointBuilder 接口中的两个函数
class SelfDefinedEndpointBuilder implements EndpointBuilder {
private String region;
private String domain;
public SelfDefinedEndpointBuilder(String region, String domain) {
super();
// 格式化 Region
this.region = Region.formatRegion(new Region(region));
this.domain = domain;
}
@Override
public String buildGeneralApiEndpoint(String bucketName) {
// 构造 Endpoint
String endpoint = String.format("%s.%s", this.region, this.domain);
// 构造 Bucket 访问域名
return String.format("%s.%s", bucketName, endpoint);
}
@Override
public String buildGetServiceApiEndpoint() {
return String.format("%s.%s", this.region, this.domain);
}
}
若您使用永久密钥初始化 COSClient，可以先在访问管理控制台中的 API 密钥管理页面获取 SecretId、SecretKey，使用永久密钥适用于大部分的应用场景，参考示例如下：
// 步骤1: 初始化用户身份信息
String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
// 步骤2: 通过 Region, Domain 以及上一步中实现的类, 来初始化客户端配置
String region = "REGION";
String domain = "DOMAIN.COM";
// 上文中实现的 SelfDefinedEndpointBuilder 类, 填入 region 以及 domain
SelfDefinedEndpointBuilder selfDefinedEndpointBuilder = new SelfDefinedEndpointBuilder(region, domain);
ClientConfig clientConfig = new ClientConfig(new Region(region));
clientConfig.setEndpointBuilder(selfDefinedEndpointBuilder);
// 步骤3: 生成 COS 客户端
COSClient cosClient = new COSClient(cred, clientConfig);
您也可以使用临时密钥初始化 COSClient，临时密钥生成和使用可参见 临时密钥生成及使用指引，参考示例如下：
// 步骤1: 初始化用户身份信息
String tmpSecretId = "COS_SECRETID";
String tmpSecretKey = "COS_SECRETKEY";
String sessionToken = "COS_TOKEN";
BasicSessionCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);
// 步骤2: 通过 Region, Domain 以及步骤1中实现的类, 来初始化客户端配置
String region = "REGION";
String domain = "DOMAIN.COM";
// 上文中实现的 SelfDefinedEndpointBuilder 类
SelfDefinedEndpointBuilder selfDefinedEndpointBuilder = new SelfDefinedEndpointBuilder();
ClientConfig clientConfig = new ClientConfig(new Region(region));
clientConfig.setEndpointBuilder(selfDefinedEndpointBuilder);
// 步骤3: 生成 COS 客户端
COSClient cosClient = new COSClient(cred, clientConfig);
ClientConfig 类为配置信息类，主要的成员如下：
成员名设置方法描述类型region构造函数或 set 方法存储桶所在的区域RegionhttpProtocolset 方法请求所使用的协议，默认使用 HTTP 协议与 COS 交互HttpProtocolsignExpiredset 方法请求签名的有效时间，默认为1小时intconnectionTimeoutset 方法连接 COS 服务的超时时间，默认为30sintsocketTimeoutset 方法客户端读取数据的超时时间，默认为30sinthttpProxyIpset 方法代理服务器的 IPStringhttpProxyPortset 方法代理服务器的端口int
创建存储桶
用户确定存储桶名称后，参考如下示例创建存储桶：
//存储桶名称，格式：BucketName-APPID
String bucket = "examplebucket-1250000000";
CreateBucketRequest createBucketRequest = new CreateBucketRequest(bucket);
// 设置 bucket 的权限为 PublicRead(公有读私有写), 其他可选有私有读写, 公有读写
createBucketRequest.setCannedAcl(CannedAccessControlList.PublicRead);
try{
// 通过上一步骤中生成的 COS 客户端发出 createBucket 请求
Bucket bucketResult = cosClient.createBucket(createBucketRequest);
} catch (CosServiceException serverException) {
serverException.printStackTrace();
} catch (CosClientException clientException) {
clientException.printStackTrace();
}
查询存储桶列表
查询用户的存储桶列表，参考示例如下：
try {
List
System.out.println(buckets);
} catch (CosServiceException serverException) {
serverException.printStackTrace();
} catch (CosClientException clientException) {
clientException.printStackTrace();
}
上传对象
将本地文件或者已知长度的输入流内容上传到 COS，适用于20M以下图片类小文件上传，最大支持上传不超过5GB文件。5GB以上的文件必须使用分块上传或高级 API 接口上传。
若本地文件大部分在 20M 以上，建议您参考使用高级 API 接口进行上传。
若 COS 上已存在同样 Key 的对象，上传时则会覆盖旧的对象。
若要创建目录对象，请参见 SDK 如何创建目录。
对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/images/picture.jpg 中，对象键为 images/picture.jpg，详情请参见 对象键 的说明。
上传不超过5GB的文件，参考示例如下：
try {
// 指定要上传的文件
File localFile = new File("exampleobject");
// 指定要上传到的存储桶
String bucketName = "examplebucket-1250000000";
// 指定要上传到 COS 上对象键
String key = "exampleobject";
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);
} catch (CosServiceException serverException) {
serverException.printStackTrace();
} catch (CosClientException clientException) {
clientException.printStackTrace();
}
查询对象列表
查询存储桶中对象列表，参考示例如下：
try {
String bucket = "examplebucket-1250000000";
ListObjectsRequest listObjectsRequest = new ListObjectsRequest();
// 设置 bucket 名称
listObjectsRequest.setBucketName(bucket);
// prefix 表示列出的 object 的 key 以 prefix 开始
listObjectsRequest.setPrefix("");
// 设置最大遍历出多少个对象, 一次 listobject 最大支持1000
listObjectsRequest.setMaxKeys(1000);
listObjectsRequest.setDelimiter("/");
ObjectListing objectListing = cosClient.listObjects(listObjectsRequest);
for (COSObjectSummary cosObjectSummary : objectListing.getObjectSummaries()) {
// 对象的路径 key
String key = cosObjectSummary.getKey();
// 对象的 etag
String etag = cosObjectSummary.getETag();
// 对象的长度
long fileSize = cosObjectSummary.getSize();
// 对象的存储类型
String storageClass = cosObjectSummary.getStorageClass();
System.out.println("key:" + key + "; etag:" + etag + "; fileSize:" + fileSize + "; storageClass:" + storageClass);
}
} catch (CosServiceException serverException) {
serverException.printStackTrace();
} catch (CosClientException clientException) {
clientException.printStackTrace();
}
下载对象
上传对象后，您可以用同样的 key，调用 GetObject 接口将对象下载到本地，也可以生成预签名链接（下载请指定 method 为 GET，详情请参见 预签名 URL），分享到其他终端来进行下载。但如果您的文件设置了私有读权限，那么请注意预签名链接的有效期。
将文件下载到本地指定路径，参考示例如下：
try{
// 指定对象所在的存储桶
String bucketName = "examplebucket-1250000000";
// 指定对象在 COS 上的对象键
String key = "exampleobject";
// 指定要下载到的本地路径
File downFile = new File("exampleobject");
GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
ObjectMetadata downObjectMeta = cosClient.getObject(getObjectRequest, downFile);
} catch (CosServiceException serverException) {
serverException.printStackTrace();
} catch (CosClientException clientException) {
clientException.printStackTrace();
}
删除对象
删除 COS 上指定路径的对象，代码如下:
try {
// 指定对象所在的存储桶
String bucketName = "examplebucket-1250000000";
// 指定对象在 COS 上的对象键
String key = "exampleobject";
cosClient.deleteObject(bucketName, key);
} catch (CosServiceException serverException) {
serverException.printStackTrace();
} catch (CosClientException clientException) {
clientException.printStackTrace();
}
关闭客户端
关闭 cosClient，并释放 HTTP 连接的后台管理线程，代码如下。
// 关闭客户端(关闭后台线程)
cosClient.shutdown();