快速入门

最近更新时间:2019-08-06 11:11:04

下载与安装

相关资源

环境依赖

说明:

  • 关于文章中出现的 SecretId、SecretKey、Bucket 等名称的含义和获取方式请参见 COS 术语信息
  • 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 文件中添加相关依赖,内容如下:

    <dependency>
        <groupId>com.qcloud</groupId>
        <artifactId>cos_api</artifactId>
        <version>5.6.3</version>
    </dependency>
  • 源码安装
    XML Java SDK 下载源码,通过 maven 导入。比如 eclipse,依次选择 【File】>【Import】>【maven】>【Existing Maven Projects】。

卸载 SDK

通过删除 pom 依赖或源码即可卸载 SDK。

开始使用

下面为您介绍如何使用 COS Java SDK 完成一个基础操作,如初始化客户端、创建存储桶、查询存储桶列表、上传对象、查询对象列表、下载对象和删除对象。

导入类名

COS Java SDK 的包名为com.qcloud.cos.*,您可以通过 Eclipse 或者 Intellij 等 IDE 工具,导入程序运行所需要的类。

初始化客户端

在执行任何和 COS 服务相关请求之前,都需要先生成 COSClient 类的对象, COSClient 是调用 COS API 接口的对象。在生成一个 COSClient 实例后可反复使用,且线程安全。最后程序或服务退出时,需要关闭客户端。

若您使用永久密钥初始化 COSClient,可以先在访问管理控制台中的 API 密钥管理 页面获取 SecretId、SecretKey,使用永久密钥适用于大部分的应用场景,参考示例如下:

// 1 初始化用户身份信息(secretId, secretKey)。
String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
// 2 设置 bucket 的区域, COS 地域的简称请参照 https://cloud.tencent.com/document/product/436/6224
// clientConfig 中包含了设置 region, https(默认 http), 超时, 代理等 set 方法, 使用可参见源码或者常见问题 Java SDK 部分。
Region region = new Region("ap-guangzhou");
ClientConfig clientConfig = new ClientConfig(region);
// 3 生成 cos 客户端。
COSClient cosClient = new COSClient(cred, clientConfig);

您也可以使用临时密钥初始化 COSClient,临时密钥生成和使用可参见 临时密钥生成及使用指引,参考示例如下:

// 1 传入获取到的临时密钥 (tmpSecretId, tmpSecretKey, sessionToken)
String tmpSecretId = "COS_SECRETID";
String tmpSecretKey = "COS_SECRETKEY";
String sessionToken = "COS_TOKEN";
BasicSessionCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);
// 2 设置 bucket 的区域, COS 地域的简称请参阅 https://cloud.tencent.com/document/product/436/6224
// clientConfig 中包含了设置 region, https(默认 http), 超时, 代理等 set 方法, 使用可参阅源码或者常见问题 Java SDK 部分
Region region = new Region("ap-guangzhou");
ClientConfig clientConfig = new ClientConfig(region);
// 3 生成 cos 客户端
COSClient cosClient = new COSClient(cred, clientConfig);

ClientConfig 类为配置信息类,主要的成员如下:

成员名 设置方法 描述 类型
region 构造函数或 set 方法 存储桶所在的区域,COS 地域的简称请参见 地域和访问域名 文档 Region
httpProtocol set 方法 请求所使用的协议,默认使用 HTTP 协议与 COS 交互 HttpProtocol
signExpired set 方法 请求签名的有效时间,默认为1小时 int
connectionTimeout set 方法 连接 COS 服务的超时时间,默认为30s int
socketTimeout set 方法 客户端读取数据的超时时间,默认为30s int
httpProxyIp set 方法 代理服务器的 IP String
httpProxyPort set 方法 代理服务器的端口 int

创建存储桶

用户确定地域和存储桶名称后,参考如下示例创建存储桶:

Region region = new Region("ap-guangzhou");
ClientConfig clientConfig = new ClientConfig(region);
COSClient cosClient = new COSClient(cred, clientConfig);
String bucket = "examplebucket-1250000000"; //存储桶名称,格式:BucketName-APPID
CreateBucketRequest createBucketRequest = new CreateBucketRequest(bucket);
// 设置 bucket 的权限为 PublicRead(公有读私有写), 其他可选有私有读写, 公有读写
 createBucketRequest.setCannedAcl(CannedAccessControlList.PublicRead);
try{
    Bucket bucketResult = cosClient.createBucket(createBucketRequest);
} catch (CosServiceException serverException) {
    serverException.printStackTrace();
} catch (CosClientException clientException) {
    clientException.printStackTrace();
}

查询存储桶列表

查询用户的存储桶列表,参考示例如下:

try {
    List<Bucket> buckets = cosClient.listBuckets();
    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();