快速入门

下载与安装

相关资源

• 对象存储服务的 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 文件中添加相关依赖，内容如下：

<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 实例后可反复使用，且线程安全。最后程序或服务退出时，需要关闭客户端。

在初始化客户端，首先需要通过实现 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 类为配置信息类，主要的成员如下：

创建存储桶

用户确定存储桶名称后，参考如下示例创建存储桶：

//存储桶名称，格式：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<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();