租户端 存储 对象存储（COS） SDK文档

快速入门

最近更新时间: 2024-06-12 15:06:00

快速入门

下载与安装

相关资源

环境依赖

  • 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 完成一个基础操作，如初始化客户端、创建存储桶、查询存储桶列表、上传对象、查询对象列表、下载对象和删除对象。

术语解释

名称 描述
APPID 开发者访问 COS 服务时拥有的用户维度唯一资源标识，用以标识资源
SecretId 开发者拥有的项目身份识别 ID，用以身份认证
SecretKey 开发者拥有的项目身份密钥
Bucket COS 中用于存储数据的容器
Object COS 中存储的具体文件，是存储的基本实体
Region 域名中的地域信息
Endpoint Endpoint 由 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 方法 存储桶所在的区域，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

创建存储桶

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

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