开发者指南

API 文档

SDK 文档

快速入门

最近更新时间:2020-08-06 10:54:40

下载与安装

相关资源

环境依赖

说明:

  • 关于文章中出现的 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.24</version>
    </dependency>
  • 源码安装
    从 Github XML Java SDK快速下载地址 下载源码,通过 maven 导入。例如 eclipse,依次选择 【File】>【Import】>【maven】>【Existing Maven Projects】。

卸载 SDK

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

开始使用

下面为您介绍如何使用 COS Java SDK 完成一个基础操作,例如初始化客户端、创建存储桶、查询存储桶列表、上传对象、查询对象列表、下载对象和删除对象。对于示例中出现的类,在 IDE 中,您可以单击该类,查看该类的所有字段和函数定义,类中有较为详细的注释。

导入类名

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

初始化客户端

在执行任何和 COS 服务相关请求之前,都需要先生成 COSClient 类的对象, COSClient 是调用 COS API 接口的对象。

注意:

COSClient 是线程安全的类,允许多线程访问同一实例。因为实例内部维持了一个连接池,创建多个实例可能导致程序资源耗尽,请确保程序生命周期内实例只有一个,并在不再需要使用时,调用 shutdown 方法将其关闭。如果需要新建实例,请先将之前的实例关闭。

若您使用永久密钥初始化 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("COS_REGION");
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("COS_REGION");
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 方法 请求签名的有效时间,单位:秒,默认为3600s int
connectionTimeout set 方法 连接 COS 服务的超时时间,单位:毫秒,默认为30000ms int
socketTimeout set 方法 客户端读取数据的超时时间,单位:毫秒,默认为30000ms int
httpProxyIp set 方法 代理服务器的 IP String
httpProxyPort set 方法 代理服务器的端口 int

创建存储桶

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

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

查询存储桶列表

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

List<Bucket> buckets = cosClient.listBuckets();
for (Bucket bucketElement : buckets) {
    String bucketName = bucketElement.getName();
    String bucketLocation = bucketElement.getLocation();
}

上传对象

将本地文件或者已知长度的输入流内容上传到 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的文件,参考示例如下:

// 指定要上传的文件
File localFile = new File(localFilePath);
// 指定要上传到的存储桶
String bucketName = "examplebucket-1250000000";
// 指定要上传到 COS 上对象键
String key = "exampleobject";
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);

查询对象列表

查询存储桶中对象列表,参考示例如下:

// Bucket的命名格式为 BucketName-APPID ,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
ListObjectsRequest listObjectsRequest = new ListObjectsRequest();
// 设置bucket名称
listObjectsRequest.setBucketName(bucketName);
// prefix表示列出的object的key以prefix开始
listObjectsRequest.setPrefix("images/");
// deliter表示分隔符, 设置为/表示列出当前目录下的object, 设置为空表示列出所有的object
listObjectsRequest.setDelimiter("/");
// 设置最大遍历出多少个对象, 一次listobject最大支持1000
listObjectsRequest.setMaxKeys(1000);
ObjectListing objectListing = null;
do {
    try {
        objectListing = cosClient.listObjects(listObjectsRequest);
    } catch (CosServiceException e) {
        e.printStackTrace();
        return;
    } catch (CosClientException e) {
        e.printStackTrace();
        return;
    }
    // common prefix表示表示被delimiter截断的路径, 如delimter设置为/, common prefix则表示所有子目录的路径
    List<String> commonPrefixs = objectListing.getCommonPrefixes();

    // object summary表示所有列出的object列表
    List<COSObjectSummary> 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());

下载对象

上传对象后,您可以用同样的 key,调用 GetObject 接口将对象下载到本地,也可以生成预签名链接(下载请指定 method 为 GET,详情请参见 预签名 URL),分享到其他终端来进行下载。但如果您的文件设置了私有读权限,那么请注意预签名链接的有效期。
将文件下载到本地指定路径,参考示例如下:

// Bucket的命名格式为 BucketName-APPID ,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
// 方法1 获取下载输入流
GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
COSObject cosObject = cosClient.getObject(getObjectRequest);
COSObjectInputStream cosObjectInput = cosObject.getObjectContent();
// 处理完毕后,关闭输入流
cosObjectInput.close();
// 方法2 下载文件到本地
String outputFilePath = "exampleobject";
File downFile = new File(outputFilePath);
getObjectRequest = new GetObjectRequest(bucketName, key);
ObjectMetadata downObjectMeta = cosClient.getObject(getObjectRequest, downFile);

删除对象

删除 COS 上指定路径的对象,代码如下:

// Bucket的命名格式为 BucketName-APPID ,此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
cosClient.deleteObject(bucketName, key);

关闭客户端

关闭 cosClient,并释放 HTTP 连接的后台管理线程,代码如下。

// 关闭客户端(关闭后台线程)
cosClient.shutdown();
目录