存储桶操作

简介

本文档提供关于存储桶的基本操作和访问控制列表（ACL）的相关 API 概览以及 SDK 示例代码。

基本操作

访问控制列表

基本操作

查询存储桶列表

功能说明

查询当前地域下所有的存储桶列表。

方法原型

public List<Bucket> listBuckets() throws CosClientException, CosServiceException;

参数说明

无

返回结果说明

• 成功：返回一个 所有 Bucket 类的列表，Bucket 类包含了 bucket 成员，location 等信息。

• 失败：发生错误（如 Bucket 不存在），抛出异常 CosClientException 或者 CosServiceException。

请求示例

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

创建存储桶

功能说明

在指定账号下创建一个存储桶。同一用户账号下，可以创建多个存储桶，数量上限是200个（不区分地域），存储桶中的对象数量没有限制。创建存储桶是低频操作，一般建议在控制台创建 Bucket，在 SDK 进行 Object 的操作。

方法原型

public Bucket createBucket(String  bucketName) throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功： Bucket 类，包含有关 Bucket 的描述（Bucket 的名称，owner 和创建日期）。

• 失败： 发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// bucket的命名规则为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
Bucket bucket = cosClient.createBucket(bucketName);

检索存储桶及其权限

功能说明

检索存储桶是否存在且是否有权限访问。

方法原型

public boolean doesBucketExist(String bucketName) 
  throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：存在返回 true，否则 false。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// bucket的命名规则为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
boolean bucketExistFlag = cosClient.doesBucketExist(bucketName);

删除存储桶

功能说明

删除指定账号下的空存储桶。

方法原型

public void deleteBucket(String bucketName) throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：无返回值。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// bucket的命名规则为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
cosClient.deleteBucket(bucketName);

访问控制列表

设置存储桶 ACL

功能说明

设置指定存储桶的访问权限控制列表（PUT Bucket acl）。该操作是覆盖操作，会覆盖已有的权限设置。ACL 包括预定义权限策略（CannedAccessControlList）或者自定义的权限控制（AccessControlList）。两类权限当同时设置时将忽略预定义策略，以自定义策略为主。

方法原型

// 方法 1 (设置自定义策略)
public void setBucketAcl(String bucketName, AccessControlList acl)
  throws CosClientException, CosServiceException;
// 方法 2 (设置预定义策略)
public void setBucketAcl(String bucketName, CannedAccessControlList acl) throws CosClientException, CosServiceException;
// 方法 3 (以上两种方法的封装, 包含两种策略设置，如果同时设置以自定定义策略为主)
public void setBucketAcl(SetBucketAclRequest setBucketAclRequest) 
  throws CosClientException, CosServiceException;

参数说明

方法3参数同时包含1和2，因此以方法3为例进行介绍。

Request 成员说明：

Grant 类成员说明：

Owner 类成员说明：

CannedAccessControlList 表示预设的策略，针对的是所有人。是一个枚举类，枚举值如下所示：

返回结果说明

• 成功：无返回值。

• 失败：发生错误（如身份认证失败）， 抛出异常 CosClientException 或者 CosServiceException。

请求示例

// bucket的命名规则为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 设置自定义 ACL
AccessControlList acl = new AccessControlList();
Owner owner = new Owner();
owner.setId("qcs::cam::uin/2779643970:uin/2779643970");
acl.setOwner(owner);
String id = "qcs::cam::uin/2779643970:uin/734505014";
UinGrantee uinGrantee = new UinGrantee("qcs::cam::uin/2779643970:uin/734505014");
uinGrantee.setIdentifier(id);
acl.grantPermission(uinGrantee, Permission.FullControl);
cosClient.setBucketAcl(bucketName, acl);

// 设置预定义 ACL
// 设置私有读写（默认新建的 bucket 都是私有读写）
cosClient.setBucketAcl(bucketName, CannedAccessControlList.Private);
// 设置公有读私有写
cosClient.setBucketAcl(bucketName, CannedAccessControlList.PublicRead);
// 设置公有读写
cosClient.setBucketAcl(bucketName, CannedAccessControlList.PublicReadWrite);

查询存储桶 ACL

功能说明

查询指定存储桶的访问权限控制列表。

方法原型

public AccessControlList getBucketAcl(String bucketName)
       throws CosClientException, CosServiceException

参数说明

返回结果说明

• 成功：返回一个 Bucket 的 ACL。

• 失败：发生错误（如身份认证失败）， 抛出异常 CosClientException 或者 CosServiceException。

请求示例

// bucket的命名规则为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
AccessControlList acl = cosClient.getBucketAcl(bucketName);

对象操作

简介

本文档提供关于对象的简单操作、分块操作等其他操作相关的 API 概览以及 SDK 示例代码。

简单操作

分块操作

其他操作

简单操作

查询对象列表

功能说明

查询存储桶下的部分或者全部对象。

方法原型

public ObjectListing listObjects(ListObjectsRequest listObjectsRequest) throws CosClientException, CosServiceException;

参数说明

Request 成员说明 ：

返回结果说明

• 成功：返回 ObjectListing 类型， 包含所有的成员， 以及 nextMarker。

• 失败：抛出异常 CosClientException 或者 CosServiceException。

请求示例

// 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());

简单上传对象

功能说明

上传对象到指定的存储桶中（Put Object）。将本地文件或者已知长度的输入流内容上传到 COS。适用于图片类小文件上传（20MB以下），最大支持5GB（含），5GB以上请使用分块上传或高级 API 上传。

• 上传过程中默认会对文件长度与 MD5 进行校验（关闭 MD5 校验参见示例代码）。

• 若 COS 上已存在同样 Key 的对象，上传时则会进行覆盖。

• 当前访问策略条目限制为1000条，如果您不需要进行对象 ACL 控制，上传时请不要设置，默认继承 Bucket 权限。

• 上传之后，您可以用同样的 key，调用 GetObject 接口将文件下载到本地，也可以生成预签名链接（下载请指定 method 为 GET，具体接口说明见下文），发送到其他端来进行下载。

方法原型

// 方法1  将本地文件上传到 COS
public PutObjectResult putObject(String bucketName, String key, File file)
            throws CosClientException, CosServiceException;
// 方法2  输入流上传到 COS
public PutObjectResult putObject(String bucketName, String key, InputStream input, ObjectMetadata metadata)
            throws CosClientException, CosServiceException;
// 方法3  对以上两个方法的包装, 支持更细粒度的参数控制, 如 content-type,  content-disposition 等
public PutObjectResult putObject(PutObjectRequest putObjectRequest)
            throws CosClientException, CosServiceException;

参数说明

Request 成员说明：

ObjectMetadata 类用于记录对象的元信息，其主要成员说明如下：

返回结果说明

• 成功：PutObjectResult，包含文件的 ETag 等信息。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// Bucket的命名格式为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
// 方法1 本地文件上传
File localFile = new File("exampleobject");
String key = "exampleobject";
PutObjectResult putObjectResult = cosClient.putObject(bucketName, key, localFile);
String etag = putObjectResult.getETag();  // 获取文件的 etag

// 方法2 从输入流上传(需提前告知输入流的长度, 否则可能导致 oom)
FileInputStream fileInputStream = new FileInputStream(localFile);
ObjectMetadata objectMetadata = new ObjectMetadata();
// 设置输入流长度为500
objectMetadata.setContentLength(500);  
// 设置 Content type, 默认是 application/octet-stream
objectMetadata.setContentType("application/pdf");
PutObjectResult putObjectResult = cosClient.putObject(bucketName, key, fileInputStream, objectMetadata);
String etag = putObjectResult.getETag();
// 关闭输入流...

// 方法3 提供更多细粒度的控制, 常用的设置如下
// 1 content-type, 对于本地文件上传, 默认根据本地文件的后缀进行映射，如 jpg 文件映射 为image/jpeg
//   对于流式上传 默认是 application/octet-stream
// 2 上传的同时指定权限(也可通过调用 API set object acl 来设置)
// 3 若要全局关闭上传MD5校验, 则设置系统环境变量，此设置会对所有的会影响所有的上传校验。 默认是进行校验的。
// 关闭MD5校验：  System.setProperty(SkipMd5CheckStrategy.DISABLE_PUT_OBJECT_MD5_VALIDATION_PROPERTY, "true");
// 再次打开校验  System.setProperty(SkipMd5CheckStrategy.DISABLE_PUT_OBJECT_MD5_VALIDATION_PROPERTY, null);
File localFile = new File("picture.jpg");
String key = "picture.jpg";
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
// 设置自定义属性(如 content-type, content-disposition 等)
ObjectMetadata objectMetadata = new ObjectMetadata();
// 设置 Content type, 默认是 application/octet-stream
objectMetadata.setContentType("image/jpeg");
putObjectRequest.setMetadata(objectMetadata);
PutObjectResult putObjectResult = cosClient.putObject(putObjectRequest);
String etag = putObjectResult.getETag();  // 获取文件的 etag

查询对象元数据

功能说明

查询存储桶中是否存在指定的对象。

方法原型

public ObjectMetadata getObjectMetadata(String bucketName, String key)
            throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：无返回值。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

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

下载对象

功能说明

下载对象到本地（Get Object）。

方法原型

// 方法1 下载文件，并获取输入流
public COSObject getObject(GetObjectRequest getObjectRequest)
            throws CosClientException, CosServiceException;
// 方法2 下载文件到本地.
public ObjectMetadata getObject(GetObjectRequest getObjectRequest, File destinationFile)
            throws CosClientException, CosServiceException;

参数说明

Request 成员说明：

返回结果说明

• 方法1 （获取下载输入流）

• 成功：返回 COSObject 类，包含输入流以及对象属性。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

• 方法2 （下载文件到本地）

• 成功：返回文件的属性 ObjectMetadata，包含文件的自定义头和 content-type 等属性。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// 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();

// 方法2 下载文件到本地
File downFile = new File("output/exampleobject");
GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
ObjectMetadata downObjectMeta = cosClient.getObject(getObjectRequest, downFile);

设置对象复制

功能说明

将一个对象复制到另一个对象（Put Object Copy）。支持跨地域跨账号跨 Bucket 拷贝，需要拥有对源文件的读取权限以及目的文件的写入权限。最大支持5G文件 copy，5G以上文件请使用高级 API copy。

方法原型

public CopyObjectResult copyObject(CopyObjectRequest copyObjectRequest)
            throws CosClientException, CosServiceException

参数说明

Request 成员说明：

返回结果说明

• 成功：返回 CopyObjectResult，包含新文件的 Etag 等信息。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// 同地域同账号拷贝
// 源 Bucket, Bucket的命名格式为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String srcBucketName = "srcBucket-1250000000";
// 要拷贝的源文件
String srcKey = "srcobject";
// 目标存储桶, Bucket的命名格式为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String destBucketName = "examplebucket-1250000000";
// 要拷贝的目的文件
String destKey = "exampleobject";
CopyObjectRequest copyObjectRequest = new CopyObjectRequest(srcBucketName, srcKey, destBucketName, destKey);
CopyObjectResult copyObjectResult = cosClient.copyObject(copyObjectRequest);

// 跨账号跨地域拷贝（需要拥有对源文件的读取权限以及目的文件的写入权限）
String srcBucketNameOfDiffAppid = "srcBucket-125100000";
Region srcBucketRegion = new Region("ap-shanghai");
copyObjectRequest = new CopyObjectRequest(srcBucketRegion, srcBucketNameOfDiffAppid, srcKey, destBucketName, destKey);
copyObjectResult = cosClient.copyObject(copyObjectRequest);

删除单个对象

功能说明

删除指定的对象（Delete Object）。

方法原型

public void deleteObject(String bucketName, String key)
            throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：无返回值。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

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

删除多个对象

功能说明

删除多个指定的对象（DELETE Multiple Objects）。

方法原型

public DeleteObjectsResult deleteObjects(DeleteObjectsRequest deleteObjectsRequest)
    throws MultiObjectDeleteException, CosClientException, CosServiceException;

参数说明

Request 成员说明：

KeyVersion 成员说明：

返回结果说明

• 成功：无返回值。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException，

请求示例

// Bucket的命名格式为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";

DeleteObjectsRequest deleteObjectsRequest = new DeleteObjectsRequest(bucketName);
// 设置要删除的key列表, 最多一次删除1000个
ArrayList<KeyVersion> keyList = new ArrayList<>();
// 传入要删除的文件名
keyList.add(new KeyVersion("project/folder1/picture.jpg"));
keyList.add(new KeyVersion("project/folder2/text.txt"));
keyList.add(new KeyVersion("project/folder2/music.mp3"));
deleteObjectsRequest.setKeys(keyList);

// 批量删除文件
try {
    DeleteObjectsResult deleteObjectsResult = cosclient.deleteObjects(deleteObjectsRequest);
    List<DeletedObject> deleteObjectResultArray = deleteObjectsResult.getDeletedObjects();
} catch (MultiObjectDeleteException mde) { // 如果部分删除成功部分失败, 返回MultiObjectDeleteException
    List<DeletedObject> deleteObjects = mde.getDeletedObjects();
    List<DeleteError> deleteErrors = mde.getErrors();
} catch (CosServiceException e) { // 如果是其他错误，例如参数错误， 身份验证不过等会抛出 CosServiceException
    e.printStackTrace();
} catch (CosClientException e) { // 如果是客户端错误，例如连接不上COS
    e.printStackTrace();
}

分块操作

查询分块上传

功能说明

查询指定存储桶中正在进行的分块上传（List Multipart Uploads）。

方法原型

public MultipartUploadListing listMultipartUploads(
            ListMultipartUploadsRequest listMultipartUploadsRequest)
            throws CosClientException, CosServiceException

参数说明

Request 成员说明：

返回结果说明

• 成功：返回 MultipartUploadListing，包含正在进行分块上传的信息。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// Bucket的命名格式为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
listMultipartUploadsRequest.setDelimiter("/");
listMultipartUploadsRequest.setMaxUploads(100);
listMultipartUploadsRequest.setPrefix("");
listMultipartUploadsRequest.setEncodingType("url");
MultipartUploadListing multipartUploadListing = cosClient.listMultipartUploads(listMultipartUploadsRequest);

分块上传对象

分块上传对象可包括的操作：

• 分块上传对象：初始化分块上传，上传分块，完成分块上传。

• 分块续传：查询已上传块，上传分块，完成分块上传。

• 终止分块上传。

初始化分块上传

功能说明

初始化分块上传任务（Initiate Multipart Upload）。

方法原型

public InitiateMultipartUploadResult initiateMultipartUpload(
    InitiateMultipartUploadRequest request) throws CosClientException, CosServiceException;

参数说明

Request 成员说明：

返回结果说明

• 成功：返回 InitiateMultipartUploadResult ，包含标志本次分块上传的 uploadId。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// Bucket的命名格式为 BucketName-APPID
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
InitiateMultipartUploadRequest initRequest = new InitiateMultipartUploadRequest(bucketName, key);
InitiateMultipartUploadResult initResponse = cosClient.initiateMultipartUpload(initRequest);
String uploadId = initResponse.getUploadId();

上传分块

上传分块（Upload Part）。

方法原型

public UploadPartResult uploadPart(UploadPartRequest uploadPartRequest) throws CosClientException, CosServiceException;

参数说明

Request 成员说明：

返回结果说明

• 成功：返回 UploadPartResult，包含上传分块的eTag信息。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// 上传分块, 最多10000个分块, 分块大小支持为1M - 5G.
// 分块大小设置为4M. 如果总计 n 个分块, 则 1~n-1 的分块大小一致, 最后一块小于等于前面的分块大小
List<PartETag> partETags = new ArrayList<PartETag>();
int partNumber = 1;
int partSize = 4 * 1024 * 1024;
// partStream 代表 part 数据的输入流, 流长度为 partSize
UploadPartRequest uploadRequest =  new    UploadPartRequest().withBucketName(bucketName).
 withUploadId(uploadId).withKey(key).withPartNumber(partNumber).
  withInputStream(partStream).withPartSize(partSize);  
UploadPartResult uploadPartResult = cosClient.uploadPart(uploadRequest);
String eTag = uploadPartResult.getETag();  // 获取 part 的 Etag
partETags.add(new PartETag(partNumber, eTag));  // partETags 记录所有已上传的 part 的 Etag 信息
// ... 上传 partNumber 第2个到第 n 个分块

复制分块

功能说明

将一个对象的分块内容从源路径复制到目标路径（Upload Part Copy）。

方法原型

public CopyPartResult copyPart(CopyPartRequest copyPartRequest) throws CosClientException, CosServiceException

参数说明

Request 成员说明：

返回结果说明

• 成功：返回 CopyPartResult，包含分块的 ETag 信息。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// 1 初始化用户身份信息（secretId, secretKey）。
String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
// 采用了新的 region 名字，可用 region 的列表可以在官网文档中获取，也可以参见下面的 XML SDK 和 JSON SDK 的地域对照表
ClientConfig clientConfig = new ClientConfig(new Region("ap-guangzhou"));
COSClient cosclient = new COSClient(cred, clientConfig);
// 存储桶名称，格式为：BucketName-APPID
// 设置目标存储桶名称，对象名称和分块上传id
String destinationBucketName = "examplebucket-1250000000";
String destinationTargetKey = "target_exampleobject";
String uploadId = "1559020734eeca6640329099e680457e0ef653a72dd70d4eade64205d270b532c22a38649e";
int partNumber = 1;
CopyPartRequest copyPartRequest = new CopyPartRequest();
copyPartRequest.setDestinationBucketName(destinationBucketName);
copyPartRequest.setDestinationKey(destinationTargetKey);
copyPartRequest.setUploadId(uploadId);
copyPartRequest.setPartNumber(partNumber);
// 设置源存储桶的区域和名称，以及对象名称，偏移量区间
String sourceBucketRegion = "ap-guangzhou";
String sourceBucketName = "examplebucket-1250000000";
String sourceKey = "exampleobject";
Long firstByte = 1L;
Long lastByte = 5242880L;
copyPartRequest.setSourceBucketRegion(new Region(sourceBucketRegion));
copyPartRequest.setSourceBucketName(sourceBucketName);
copyPartRequest.setSourceKey(sourceKey);
copyPartRequest.setFirstByte(firstByte);
copyPartRequest.setLastByte(lastByte);

CopyPartResult copyPartResult = cosclient.copyPart(copyPartRequest);

查询已上传块

功能说明

查询特定分块上传操作中的已上传的块（List Parts）。

方法原型

public PartListing listParts(ListPartsRequest request)
            throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：返回 PartListing，包含每一分块的 ETag 和编号，以及下一次 list 的起点 marker。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// ListPart 用于在 complete 分块上传前或者 abort 分块上传前获取 uploadId 对应的已上传的分块信息, 可以用来构造 partEtags
List<PartETag> partETags = new ArrayList<PartETag>();
ListPartsRequest listPartsRequest = new ListPartsRequest(bucketName, key, uploadId);
do {
      PartListing partListing = cosClient.listParts(listPartsRequest);
    for (PartSummary partSummary : partListing.getParts()) {
        partETags.add(new PartETag(partSummary.getPartNumber(), partSummary.getETag()));
    }
    listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());
} while (partListing.isTruncated());

完成分块上传

功能说明

实现完成整个分块上传（Complete Multipart Upload）。

方法原型

public CompleteMultipartUploadResult completeMultipartUpload(CompleteMultipartUploadRequest request) throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：返回 CompleteMultipartUploadResult，包含完成对象的 eTag 信息。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// complete 完成分块上传.
CompleteMultipartUploadRequest compRequest = new CompleteMultipartUploadRequest(bucketName, key, uploadId, partETags);
CompleteMultipartUploadResult result =  cosClient.completeMultipartUpload(compRequest);

终止分块上传

功能说明

终止一个分块上传操作并删除已上传的块（Abort Multipart Upload）。

方法原型

public void abortMultipartUpload(AbortMultipartUploadRequest request)  throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：无返回值。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// abortMultipartUpload 用于终止一个还未 complete 的分块上传
AbortMultipartUploadRequest abortMultipartUploadRequest = new AbortMultipartUploadRequest(bucketName, key, uploadId);
cosClient.abortMultipartUpload(abortMultipartUploadRequest);

其他操作

设置对象 ACL

功能说明

设置存储桶中某个对象的访问控制列表。

注意：

当前访问策略条目限制为1000条，如果您不需要进行对象 ACL 控制，请不要设置，默认继承 Bucket 权限。

ACL 包括预定义权限策略（CannedAccessControlList）或者自定义的权限控制（AccessControlList）。两类权限当同时设置时将忽略预定义策略，以自定义策略为主。

方法原型

// 方法1 (设置自定义策略)
public void setObjectAcl(String bucketName, String key, AccessControlList acl)
       throws CosClientException, CosServiceException
// 方法2 (设置预定义策略)
public void setObjectAcl(String bucketName, String key, CannedAccessControlList acl)
       throws CosClientException, CosServiceException
// 方法3 (以上两种方法的封装, 包含两种策略设置，如果同时设置以自定定义策略为主)
public void setObjectAcl(SetObjectAclRequest setObjectAclRequest)
  throws CosClientException, CosServiceException;

参数说明

• 方法3 参数同时包含1和2，因此以方法3为例进行介绍。

Request 成员说明：

Grant 类成员说明：

Owner 类成员说明：

CannedAccessControlList 表示预设的策略，针对的是所有人。是一个枚举类，枚举值如下所示：

返回结果说明

• 成功：无返回值。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// 权限信息中身份信息有格式要求, 对于主账号与子账号的范式如下：
// 下面的 root_uin 和 sub_uin 都必须是有效的 QQ 号
// 主账号 qcs::cam::uin/<root_uin>:uin/<root_uin> 表示授予主账号 root_uin 这个用户(即前后填的 uin 一样)
//  如 qcs::cam::uin/2779643970:uin/2779643970
// 子账号 qcs::cam::uin/<root_uin>:uin/<sub_uin> 表示授予 root_uin 的子账号 sub_uin 这个客户
//  如 qcs::cam::uin/2779643970:uin/73001122 
// 存储桶的命名格式为 BucketName-APPID
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
// 设置自定义 ACL
AccessControlList acl = new AccessControlList();
Owner owner = new Owner();
// 设置 owner 的信息, owner 只能是主账号
owner.setId("qcs::cam::uin/2779643970:uin/2779643970");
acl.setOwner(owner);

// 授权给主账号73410000可读可写权限
UinGrantee uinGrantee1 = new UinGrantee("qcs::cam::uin/73410000:uin/73410000");
acl.grantPermission(uinGrantee1, Permission.FullControl);
// 授权给 2779643970 的子账号 72300000 可读权限
UinGrantee uinGrantee2 = new UinGrantee("qcs::cam::uin/2779643970:uin/72300000");
acl.grantPermission(uinGrantee2, Permission.Read);
// 授权给 2779643970 的子账号 7234444 可写权限
UinGrantee uinGrantee3 = new UinGrantee("qcs::cam::uin/7234444:uin/7234444");
acl.grantPermission(uinGrantee3, Permission.Write);
cosClient.setObjectAcl(bucketName, key, acl);

// 设置预定义 ACL
// 设置私有读写（Object 的权限默认集成 Bucket的）
cosClient.setObjectAcl(bucketName, key, CannedAccessControlList.Private);
// 设置公有读私有写
cosClient.setObjectAcl(bucketName, key, CannedAccessControlList.PublicRead);
// 设置公有读写
cosClient.setObjectAcl(bucketName, key, CannedAccessControlList.PublicReadWrite);

获取对象 ACL

功能说明

获取对象访问权限控制列表（ACL）（Get Object ACL）。

方法原型

public AccessControlList getObjectAcl(String bucketName, String key)
  throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：返回一个 Object 所在的 ACL。

• 失败：发生错误（如身份认证失败）， 抛出异常 CosClientException 或者 CosServiceException。

请求示例

// 存储桶的命名格式为 BucketName-APPID
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
AccessControlList acl = cosClient.getObjectAcl(bucketName, key);

高级接口（推荐）

高级 API 由类 TransferManger 通过封装上传以及下载接口，内部有一个线程池，接受用户的上传和下载请求，因此用户可选择异步的提交任务。

// 线程池大小，建议在客户端与 COS 网络充足(如使用腾讯云金融专区的 CVM，同地域上传 COS)的情况下，设置成16或32即可, 可较充分的利用网络资源
// 对于使用公网传输且网络带宽质量不高的情况，建议减小该值，避免因网速过慢，造成请求超时。
ExecutorService threadPool = Executors.newFixedThreadPool(32);
// 传入一个 threadpool, 若不传入线程池, 默认 TransferManager 中会生成一个单线程的线程池。
TransferManager transferManager = new TransferManager(cosClient, threadPool);
// .....(提交上传下载请求, 如下文所属)
// 关闭 TransferManger
transferManager.shutdownNow();

上传对象

功能说明

上传接口根据用户文件的长度，自动选择简单上传以及分块上传， 降低用户的使用门槛。用户不用关心分块上传的每个步骤。

Tips 有关其他一些设置属性，存储类别，MD5 校验等可参见 Put Object Api。

方法原型

// 上传对象
public Upload upload(final PutObjectRequest putObjectRequest)
            throws CosServiceException, CosClientException;

参数说明

Request 成员说明：

返回值

• 成功：返回 Upload，可以查询上传是否结束，也可同步的等待上传结束。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// 示例1：
// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
String key = "/doc/picture.jpg";
File localFile = new File("/doc/picture.jpg");
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
// 本地文件上传
Upload upload = transferManager.upload(putObjectRequest);
 // 等待传输结束（如果想同步的等待上传结束，则调用 waitForCompletion）
UploadResult uploadResult = upload.waitForUploadResult();

// 示例2：对大于分块大小的文件，使用断点续传
// 步骤一：获取 PersistableUpload
String bucketName = "examplebucket-1250000000";
String key = "exmpleobject";
File localFile = new File("exmpleobject");
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
// 本地文件上传
PersistableUpload persistableUpload = null;
Upload upload = transferManager.upload(putObjectRequest);
// 等待"分块上传初始化"完成，并获取到 persistableUpload （包含uploadId等）
while(persistableUpload == null) {
    persistableUpload = upload.getResumeableMultipartUploadId();
    Thread.sleep(100);
}
// 保存 persistableUpload

// 步骤二：当由于网络等问题，大文件的上传被中断，则根据 PersistableUpload 恢复该文件的上传，只上传未上传的分块
Upload newUpload = transferManager.resumeUpload(persistableUpload);
 // 等待传输结束（如果想同步的等待上传结束，则调用 waitForCompletion）
UploadResult uploadResult = newUpload.waitForUploadResult();

下载对象

功能说明

将 COS 上的对象下载到本地。

方法原型

// 下载对象
public Download download(final GetObjectRequest GetObjectRequest, final File file);

参数说明

Request 成员说明：

返回值

• 成功：返回 Download，可以查询下载是否结束，也可同步的等待下载结束。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// Bucket 的命名格式为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
String key = "/doc/picture.jpg";
File localDownFile = new File("/doc/picture.jpg");
GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, key);
// 下载文件
Download download = transferManager.download(getObjectRequest, localDownFile);
 // 等待传输结束（如果想同步的等待上传结束，则调用 waitForCompletion）
download.waitForCompletion();

复制对象

功能说明

Copy 接口支持根据对象大小自动选择简单复制或者分块复制，用户无需关心复制的文件大小。

方法原型

// 上传对象
public Copy copy(final CopyObjectRequest copyObjectRequest);

参数说明

Request 成员说明：

返回值

• 成功：返回 Copy，可以查询 Copy 是否结束，也可同步的等待上传结束。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// 要拷贝的 bucket region, 支持跨地域拷贝
Region srcBucketRegion = new Region("ap-shanghai");
// 源 Bucket, 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String srcBucketName = "srcBucket-1251668577";
// 要拷贝的源文件
String srcKey = "exampleobject";
// 目的 Bucket, 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String destBucketName = "examplebucket-1250000000";
// 要拷贝的目的文件
String destKey = "exampleobject";

// 生成用于获取源文件信息的 srcCOSClient
COSClient srcCOSClient = new COSClient(cred, new ClientConfig(srcBucketRegion));
CopyObjectRequest copyObjectRequest = new CopyObjectRequest(srcBucketRegion, srcBucketName,
        srcKey, destBucketName, destKey);
try {
    Copy copy = transferManager.copy(copyObjectRequest, srcCOSClient, null);
    // 返回一个异步结果 copy, 可同步的调用 waitForCopyResult 等待 copy 结束, 成功返回 CopyResult, 失败抛出异常.
    CopyResult copyResult = copy.waitForCopyResult();
} catch (CosServiceException e) {
    e.printStackTrace();
} catch (CosClientException e) {
    e.printStackTrace();
} catch (InterruptedException e) {
    e.printStackTrace();
}

客户端加密

功能说明

Java sdk 支持客户端加密, 将文件加密后再进行上传，并在下载时进行解密。客户端加密支持对称 AES 与非对称 RSA 加密。 这里的对称和非对称只是用来加密每次生成的随机密钥, 对文件数据的加密始终使用 AES256 对称加密。 客户端加密适用于存储敏感数据的客户，客户端加密会牺牲部分上传速度，SDK 内部对于分块上传会使用串行的方式进行上传。

使用客户端加密前准备事项

客户端加密内部使用 AES256 来对数据进行加密，默认 JDK6 - JDK8 早期的版本不支持256位加密，如果运行时会报出以下异常java.security.InvalidKeyException: Illegal key size or default parameters。那么我们需要补充 oracle 的 JCE 无政策限制权限文件，将其部署在 JRE 的环境中。 请根据目前使用的 JDK 版本，分别下载对应的文件，将其解压后保存在 JAVA_HOME 下的 jre/lib/security 目录下。

1. JDK6 JCE 补充包

2. JDK7 JCE 补充包

3. JDK8 JCE 补充包

上传加密流程

1. 每次上传一个文件对象前，我们随机生成一个对称加密密钥，随机生成的密钥通过用户的提供的对称或非对称密钥进行加密，将加密后的结果 base64 编码存储在对象的元数据中。

2. 进行文件对象的上传，上传时在内存使用 AES256 算法加密。

下载解密流程

1. 获取文件元数据中加密必要的信息，base64 解码后使用用户密钥进行解密，得到当时加密数据的密钥

2. 使用密钥对下载输入流进行使用 AES256 解密，得到解密后的文件输入流。

请求示例

示例1：使用对称 AES256 加密每次生成的随机密钥示例，完整的示例代码请参见 客户端对称密钥加密完整示例。

// 初始化用户身份信息(secretId, secretKey)
String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
// 设置存储桶地域
ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing"));

// 加载保存在文件中的密钥, 如果不存在，请先使用 buildAndSaveSymmetricKey 生成密钥
// buildAndSaveSymmetricKey();
SecretKey symKey = loadSymmetricAESKey();

EncryptionMaterials encryptionMaterials = new EncryptionMaterials(symKey);
// 使用 AES/GCM 模式，并将加密信息存储在文件元数据中.
CryptoConfiguration cryptoConf = new CryptoConfiguration(CryptoMode.AuthenticatedEncryption)
        .withStorageMode(CryptoStorageMode.ObjectMetadata);

// 生成加密客户端 EncryptionClient, COSEncryptionClient 是 COSClient 的子类, 所有 COSClient 支持的接口他都支持。
// EncryptionClient 覆盖了 COSClient 上传下载逻辑，操作内部会执行加密操作，其他操作执行逻辑和 COSClient 一致
COSEncryptionClient cosEncryptionClient =
        new COSEncryptionClient(new COSStaticCredentialsProvider(cred),
                new StaticEncryptionMaterialsProvider(encryptionMaterials), clientConfig,
                cryptoConf);

// 上传文件
// 这里给出 putObject 的示例, 对于高级 API 上传，只用在生成 TransferManager 时传入 COSEncryptionClient 对象即可
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
File localFile = new File("src/test/resources/plain.txt");
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
cosEncryptionClient.putObject(putObjectRequest);

示例2：使用非对称 RSA 加密每次生成的随机密钥示例，完整的示例代码请参见 客户端非对称密钥加密完整示例。

// 初始化用户身份信息(secretId, secretKey)
String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
// 设置存储桶地域，COS 地域的简称请参照 /document/product/436/6224
ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing"));


// 加载保存在文件中的密钥, 如果不存在，请先使用 buildAndSaveAsymKeyPair 生成密钥
buildAndSaveAsymKeyPair();
KeyPair asymKeyPair = loadAsymKeyPair();

EncryptionMaterials encryptionMaterials = new EncryptionMaterials(asymKeyPair);
// 使用 AES/GCM 模式，并将加密信息存储在文件元数据中.
CryptoConfiguration cryptoConf = new CryptoConfiguration(CryptoMode.AuthenticatedEncryption)
        .withStorageMode(CryptoStorageMode.ObjectMetadata);

// 生成加密客户端 EncryptionClient, COSEncryptionClient 是 COSClient 的子类, 所有COSClient 支持的接口他都支持。
// EncryptionClient 覆盖了 COSClient 上传下载逻辑，操作内部会执行加密操作，其他操作执行逻辑和 COSClient 一致
COSEncryptionClient cosEncryptionClient =
        new COSEncryptionClient(new COSStaticCredentialsProvider(cred),
                new StaticEncryptionMaterialsProvider(encryptionMaterials), clientConfig,
                cryptoConf);

// 上传文件
// 这里给出 putObject 的示例，对于高级 API 上传，只用在生成 TransferManager 时传入 COSEncryptionClient 对象即可
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
File localFile = new File("src/test/resources/plain.txt");
PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, key, localFile);
cosEncryptionClient.putObject(putObjectRequest);

存储桶管理

简介

本文档提供关于跨域访问、生命周期、版本控制和跨地域复制相关的 API 概览以及 SDK 示例代码。

跨域访问

版本控制

跨地域复制

跨域访问

设置跨域配置

功能说明

设置指定存储桶的跨域访问配置信息（PUT Bucket cors）。

方法原型

public void setBucketCrossOriginConfiguration(String bucketName, BucketCrossOriginConfiguration bucketCrossOriginConfiguration);

参数说明

返回结果说明

• 成功：无返回值。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// bucket的命名格式为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
BucketCrossOriginConfiguration bucketCORS = new BucketCrossOriginConfiguration();
List<CORSRule> corsRules = new ArrayList<>();
CORSRule corsRule = new CORSRule();
// 规则名称
corsRule.setId("set-bucket-cors-test");  
// 允许的 HTTP 方法
corsRule.setAllowedMethods(AllowedMethods.PUT, AllowedMethods.GET, AllowedMethods.HEAD);
corsRule.setAllowedHeaders("x-cos-grant-full-control");
corsRule.setAllowedOrigins("http://mail.qq.com",         "http://www.qq.com", "http://video.qq.com");
corsRule.setExposedHeaders("x-cos-request-id");
corsRule.setMaxAgeSeconds(60);
corsRules.add(corsRule);
bucketCORS.setRules(corsRules);
cosClient.setBucketCrossOriginConfiguration(bucketName, bucketCORS);

查询跨域配置

功能说明

查询指定存储桶的跨域访问配置信息（GET Bucket cors）。

方法原型

public BucketCrossOriginConfiguration getBucketCrossOriginConfiguration(String bucketName)
throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：返回存储桶的跨域规则。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// bucket的命名格式为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
BucketCrossOriginConfiguration corsGet = cosClient.getBucketCrossOriginConfiguration(bucketName);
List<CORSRule> corsRules = corsGet.getRules();
for (CORSRule rule : corsRules) {
List<AllowedMethods> allowedMethods = rule.getAllowedMethods();
List<String> allowedHeaders = rule.getAllowedHeaders();
List<String> allowedOrigins = rule.getAllowedOrigins();
List<String> exposedHeaders = rule.getExposedHeaders();
int maxAgeSeconds = rule.getMaxAgeSeconds();
}

删除跨域配置

功能说明

删除指定存储桶的跨域访问配置（DELETE Bucket cors）。

方法原型

public void deleteBucketCrossOriginConfiguration(String bucketName)
throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：无返回值。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

//存储桶的命名格式为 BucketName-APPID
String bucketName = "examplebucket-1250000000";
cosClient.deleteBucketCrossOriginConfiguration(bucketName);

版本控制

设置版本控制

功能说明

设置指定存储桶的版本控制功能（PUT Bucket versioning）。

方法原型

public void setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest setBucketVersioningConfigurationRequest)
    throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：无返回值。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

开启版本控制

String bucketName = "examplebucket-1250000000";
// 开启版本控制
cosClient.setBucketVersioningConfiguration(
new SetBucketVersioningConfigurationRequest(bucketName,
new BucketVersioningConfiguration(BucketVersioningConfiguration.ENABLED)));

暂停版本控制

String bucketName = "examplebucket-1250000000";
// 暂停版本控制
cosClient.setBucketVersioningConfiguration(
new SetBucketVersioningConfigurationRequest(bucketName,
new BucketVersioningConfiguration(BucketVersioningConfiguration.SUSPENDED)));

查询版本控制

功能说明

查询指定存储桶的版本控制信息（GET Bucket versioning）。

方法原型

// 方法1 传入存储桶名称即可
public BucketVersioningConfiguration getBucketVersioningConfiguration(String bucketName)
            throws CosClientException, CosServiceException;

// 方法2 通过GetBucketVersioningConfigurationRequest 获取
public BucketVersioningConfiguration getBucketVersioningConfiguration(
    GetBucketVersioningConfigurationRequest getBucketVersioningConfigurationRequest)
        throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：返回存储桶的多版本配置。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

String bucketName = "examplebucket-1250000000";
// 获取版本控制
BucketVersioningConfiguration bvc =
     cosClient.getBucketVersioningConfiguration(bucketName);
// 获取版本控制
BucketVersioningConfiguration bvc2 = cosClient.getBucketVersioningConfiguration(
   new GetBucketVersioningConfigurationRequest(bucketName));

跨地域复制

设置跨地域复制

功能说明

设置指定存储桶的跨地域复制规则（PUT Bucket replication）。

方法原型

public void setBucketReplicationConfiguration(
        SetBucketReplicationConfigurationRequest setBucketReplicationConfigurationRequest)
                throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：无返回值。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

// 源存储桶名称，需包含 appid
String bucketName = "examplebucket-1250000000";

BucketReplicationConfiguration bucketReplicationConfiguration = new BucketReplicationConfiguration();
// 设置发起者身份, 格式为： qcs::cam::uin/<OwnerUin>:uin/<SubUin>
bucketReplicationConfiguration.setRoleName("qcs::cam::uin/123456789:uin/987654543");

// 设置目标存储桶和存储类型，QCS 的格式为：qcs::cos:[region]::[bucketname-AppId]
ReplicationDestinationConfig replicationDestinationConfig = new ReplicationDestinationConfig();
replicationDestinationConfig.setBucketQCS("qcs::cos:ap-chongqing::examplebucket-target-1250000000");
replicationDestinationConfig.setStorageClass(StorageClass.Standard);

// 设置规则状态和前缀
ReplicationRule replicationRule = new ReplicationRule();
replicationRule.setStatus(ReplicationRuleStatus.Enabled);
replicationRule.setPrefix("");
replicationRule.setDestinationConfig(replicationDestinationConfig);
// 添加规则
String ruleId = "replication-to-chongqing";
bucketReplicationConfiguration.addRule("replication-to-chongqing", replicationRule);

try {
    SetBucketReplicationConfigurationRequest setBucketReplicationConfigurationRequest =
        new SetBucketReplicationConfigurationRequest(bucketName, bucketReplicationConfiguration);
  cosclient.setBucketReplicationConfiguration(setBucketReplicationConfigurationRequest);
} catch (CosServiceException e) {
    e.printStackTrace();
} catch (CosClientException e) {
    e.printStackTrace();
} finally {
    cosclient.shutdown();
}

查询跨地域复制

功能说明

查询指定存储桶的跨地域复制规则（GET Bucket replication）。

方法原型

// 获取存储桶跨地域复制配置方法1
public BucketReplicationConfiguration getBucketReplicationConfiguration(String bucketName)
            throws CosClientException, CosServiceException;

// 获取存储桶跨地域复制方法2        
public BucketReplicationConfiguration getBucketReplicationConfiguration(
            GetBucketReplicationConfigurationRequest getBucketReplicationConfigurationRequest)
            throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：返回存储桶的跨地域复制规则。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

String bucketName = "examplebucket-1250000000";

// 获取存储桶跨地域复制配置方法1
BucketReplicationConfiguration brcfRet = cosClient.getBucketReplicationConfiguration(bucketName);

// 获取存储桶跨地域复制配置方法2
BucketReplicationConfiguration brcfRet2 = cosClient.getBucketReplicationConfiguration(
 new GetBucketReplicationConfigurationRequest(bucketName));

删除跨地域复制

功能说明

删除指定存储桶的跨地域复制规则（DELETE Bucket replication）。

方法原型

// 删除存储桶跨地域复制配置方法1
public void deleteBucketReplicationConfiguration(String bucketName)
            throws CosClientException, CosServiceException;

// 删除存储桶跨地域复制方法2        
public void deleteBucketReplicationConfiguration(
            DeleteBucketReplicationConfigurationRequest deleteBucketReplicationConfigurationRequest)
            throws CosClientException, CosServiceException;

参数说明

返回结果说明

• 成功：无返回值。

• 失败：发生错误（如身份认证失败），抛出异常 CosClientException 或者 CosServiceException。

请求示例

String bucketName = "examplebucket-1250000000";

// 删除存储桶跨地域复制配置方法1
cosClient.deleteBucketReplicationConfiguration(bucketName);

// 删除存储桶跨地域复制配置方法2
cosClient.deleteBucketReplicationConfiguration(new DeleteBucketReplicationConfigurationRequest(bucketName));

预签名 URL

简介

Java SDK 提供获取请求预签名 URL 和生成签名接口，可以分发给客户端，用于下载或者上传。如果您的文件是私有读权限，那么请注意预签名链接只有一定的有效期。

获取请求预签名 URL

方法原型

public URL generatePresignedUrl(GeneratePresignedUrlRequest req) throws CosClientException

参数说明

Request 成员说明：

示例1

使用永久密钥生成一个带签名的下载链接，示例代码如下：

// 初始化用户身份信息
String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);

// 初始化客户端配置
String region = "REGION";
String domain = "DOMAIN.COM";
SelfDefinedEndpointBuilder selfDefinedEndpointBuilder = new SelfDefinedEndpointBuilder();
ClientConfig clientConfig = new ClientConfig(new Region(region));
clientConfig.setEndpointBuilder(selfDefinedEndpointBuilder);

// 生成 COS 客户端
COSClient cosClient = new COSClient(cred, clientConfig);

// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
GeneratePresignedUrlRequest req =
        new GeneratePresignedUrlRequest(bucketName, key, HttpMethodName.GET);
// 设置签名过期时间(可选), 若未进行设置, 则默认使用 ClientConfig 中的签名过期时间(1小时)
// 这里设置签名在半个小时后过期
Date expirationDate = new Date(System.currentTimeMillis() + 30L * 60L * 1000L);
req.setExpiration(expirationDate);
URL url = cosClient.generatePresignedUrl(req);
System.out.println(url.toString());
cosClient.shutdown();

示例2

使用临时密钥生成一个带签名的下载链接，并设置覆盖要返回的一些公共头部（例如 content-type，content-language），示例代码如下：

// 传入获取到的临时密钥 (tmpSecretId, tmpSecretKey, sessionToken)
String tmpSecretId = "COS_SECRETID";
String tmpSecretKey = "COS_SECRETKEY";
String sessionToken = "COS_TOKEN";
COSCredentials cred = new BasicSessionCredentials(tmpSecretId, tmpSecretKey, sessionToken);

// 初始化客户端配置
String region = "REGION";
String domain = "DOMAIN.COM";
SelfDefinedEndpointBuilder selfDefinedEndpointBuilder = new SelfDefinedEndpointBuilder();
ClientConfig clientConfig = new ClientConfig(new Region(region));
clientConfig.setEndpointBuilder(selfDefinedEndpointBuilder);

// 生成 COS 客户端
COSClient cosClient = new COSClient(cred, clientConfig);

// 存储桶的命名格式为 BucketName-APPID 
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
GeneratePresignedUrlRequest req =
        new GeneratePresignedUrlRequest(bucketName, key, HttpMethodName.GET);

// 设置下载时返回的 http 头
ResponseHeaderOverrides responseHeaders = new ResponseHeaderOverrides();
String responseContentType = "image/x-icon";
String responseContentLanguage = "zh-CN";
String responseContentDispositon = "filename=\"exampleobject\"";
String responseCacheControl = "no-cache";
String cacheExpireStr =
        DateUtils.formatRFC822Date(new Date(System.currentTimeMillis() + 24L * 3600L * 1000L));
responseHeaders.setContentType(responseContentType);
responseHeaders.setContentLanguage(responseContentLanguage);
responseHeaders.setContentDisposition(responseContentDispositon);
responseHeaders.setCacheControl(responseCacheControl);
responseHeaders.setExpires(cacheExpireStr);
req.setResponseHeaders(responseHeaders);

// 设置签名过期时间(可选)，若未进行设置，则默认使用 ClientConfig 中的签名过期时间(1小时)
// 这里设置签名在半个小时后过期
Date expirationDate = new Date(System.currentTimeMillis() + 30L * 60L * 1000L);
req.setExpiration(expirationDate);
URL url = cosClient.generatePresignedUrl(req);
System.out.println(url.toString());
cosClient.shutdown();

示例3

生成公有读 Bucket（匿名可读），不需要签名的链接，示例代码如下：

// 生成匿名的请求签名，需要重新初始化一个匿名的 cosClient
// 初始化用户身份信息, 匿名身份不用传入 SecretId、SecretKey 等密钥信息
COSCredentials cred = new AnonymousCOSCredentials();
// 设置 bucket 的区域，COS 地域的简称请参照 /document/product/436/6224
ClientConfig clientConfig = new ClientConfig(new Region("ap-beijing"));
// 生成 cos 客户端
COSClient cosClient = new COSClient(cred, clientConfig);
// bucket 名需包含 appid
String bucketName = "examplebucket-1250000000";

String key = "exampleobject";
GeneratePresignedUrlRequest req =
        new GeneratePresignedUrlRequest(bucketName, key, HttpMethodName.GET);
URL url = cosClient.generatePresignedUrl(req);
System.out.println(url.toString());
cosClient.shutdown();

示例4

生成一些预签名的上传链接，可直接分发给客户端进行文件的上传，示例代码如下：

// 存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String bucketName = "examplebucket-1250000000";
String key = "exampleobject";
// 设置签名过期时间(可选), 若未进行设置, 则默认使用 ClientConfig 中的签名过期时间(1小时)
// 这里设置签名在半个小时后过期
Date expirationTime = new Date(System.currentTimeMillis() + 30L * 60L * 1000L);
URL url = cosClient.generatePresignedUrl(bucketName, key, expirationTime, HttpMethodName.PUT);
System.out.println(url.toString());
cosClient.shutdown();

生成签名

COSSigner 类提供构造 COS 签名的方法，用于分发给移动端 SDK，进行文件的上传和下载。签名的路径和分发后要进行操作的 key 相匹配。

方法原型

// 构造 COS 签名
public String buildAuthorizationStr(HttpMethodName methodName, String resouce_path,
        COSCredentials cred, Date expiredTime);

// 构造 COS 签名
// 第二个方法比第一个方法额外提供对部分 HTTP Header 和所有传入的 URL 中的参数进行签名
// 用于更复杂的签名控制, 生成的签名必须在上传下载等操作时，也要携带对应的 header 和 param
public String buildAuthorizationStr(HttpMethodName methodName, String resouce_path,
        Map<String, String> headerMap, Map<String, String> paramMap, COSCredentials cred,
        Date expiredTime);

参数说明

返回值

签名字符串，类型为 String。

示例1：生成一个上传签名

String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
COSSigner signer = new COSSigner();
//设置过期时间为1个小时
Date expiredTime = new Date(System.currentTimeMillis() + 3600L * 1000L);
// 要签名的 key, 生成的签名只能用于对应此 key 的上传
String key = "/exampleobject";
String sign = signer.buildAuthorizationStr(HttpMethodName.PUT, key, cred, expiredTime);

示例2：生成一个下载签名

String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
COSSigner signer = new COSSigner();
// 设置过期时间为1个小时
Date expiredTime = new Date(System.currentTimeMillis() + 3600L * 1000L);
// 要签名的 key, 生成的签名只能用于对应此 key 的下载
String key = "/exampleobject";
String sign = signer.buildAuthorizationStr(HttpMethodName.GET, key, cred, expiredTime);

示例3：生成一个删除签名

String secretId = "COS_SECRETID";
String secretKey = "COS_SECRETKEY";
COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);
COSSigner signer = new COSSigner();
// 设置过期时间为1个小时
Date expiredTime = new Date(System.currentTimeMillis() + 3600L * 1000L);
// 要签名的 key, 生成的签名只能用于对应此 key 的删除
String key = "/exampleobject";
String sign = signer.buildAuthorizationStr(HttpMethodName.DELETE, key, cred, expiredTime);

异常处理

简介

调用 SDK 请求 COS 服务失败时，抛出的异常皆是 RuntimeExcpetion，目前 SDK 常见的异常有 CosClientException，CosServiceException 和 IllegalArgumentException。

客户端异常

客户端异常 CosClientException，是由于客户端原因导致无法和服务端完成正常的交互而导致的失败，如客户端无法连接到服务端，无法解析服务端返回的数据，读取本地文件发生 IO 异常等。CosClientException 继承自 RuntimeException，没有自定义的成员变量，使用方法同 RuntimeException。

服务端异常

服务端异常 CosServiceException，用于指交互正常完成，但是操作失败的场景。例如客户端访问一个不存在 Bucket，删除一个不存在的文件，没有权限进行某个操作， 服务端故障异常等。CosServiceException 包含了服务端返回的状态码，requestid，出错明细等。捕获异常后，建议对整个异常进行打印，异常包含了必须的排查因素。以下是异常成员变量的描述：

常见问题

若您在使用 Java SDK 过程中，有相关的疑问，请联系维护工程师。