存储桶操作

最近更新时间:2019-04-30 17:17:05

简介

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

基本操作

API 操作名 操作描述
GET Service 查询存储桶列表 查询指定账号下所有的存储桶列表
PUT Bucket 创建存储桶 在指定账号下创建一个存储桶
HEAD Bucket 检索存储桶及其权限 检索存储桶是否存在且是否有权限访问
DELETE Bucket 删除存储桶 删除指定账号下的空存储桶

访问控制列表

API 操作名 操作描述
PUT Bucket acl 设置存储桶 ACL 设置存储桶的 ACL 配置
GET Bucket acl 查询存储桶 ACL 查询存储桶的 ACL 配置

基本操作

查询存储桶列表

功能说明

用于查询指定账号下所有存储桶列表。

方法原型

GetServiceResult getService(GetServiceRequest request)throws CosXmlClientException, CosXmlServiceException;

void getServiceAsync(GetServiceRequest request, CosXmlResultListener cosXmlResultListen);

请求示例

GetServiceRequest getServiceRequest = new GetServiceRequest();
// 使用同步方法
try {
    GetServiceResult result = cosXmlService.getService(getServiceRequest);
} catch (CosXmlClientException e) {
    e.printStackTrace();
} catch (CosXmlServiceException e) {
    e.printStackTrace();
}

// 使用异步回调请求
cosXmlService.getServiceAsync(getServiceRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        // todo Put Bucket Lifecycle success
        GetServiceResult getServiceResult = (GetServiceResult)result;
    }

    @Override
    public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException)  {
        // todo Put Bucket Lifecycle failed because of CosXmlClientException or CosXmlServiceException...
    }
});

说明:

请求时,如需直接设置已计算好的签名串,则可通过调用 getServiceRequest.setSign("已计算好的签名串") 方法设置,默认由 SDK 计算签名串。

参数说明

参数名称 设置方法 描述 类型
headerKeys setSign 签名是否校验 header Set<String>
queryParameterKeys setSign 签名是否校验请求 url 中查询参数 Set<String>
cosXmlResultListener getServiceAsync 结果回调 CosXmlResultListener

返回结果说明

通过 GetServiceResult 返回请求结果。

成员变量 类型 描述
httpCode int HTTP Code, [200,300)之间表示操作成功,否则表示操作失败
listAllMyBuckets ListAllMyBuckets 返回指定账号下的存储桶列表的信息

说明:

操作失败时,SDK 将抛出 CosXmlClientExceptionCosXmlServiceException 异常。

创建存储桶

功能说明

创建一个存储桶(PUT Bucket)。

方法原型

PutBucketResult putBucket(PutBucketRequest request) throws CosXmlClientException, CosXmlServiceException;

void putBucketAsync(PutBucketRequest request, CosXmlResultListener cosXmlResultListener);

请求示例

String bucket = "examplebucket-1250000000";
PutBucketRequest putBucketRequest = new PutBucketRequest(bucket);

//定义存储桶的 ACL 属性。有效值:private,public-read-write,public-read;默认值:private
putBucketRequest.setXCOSACL("private");

//赋予被授权者读的权限
ACLAccount readACLS = new ACLAccount();
readACLS.addAccount("OwnerUin", "SubUin");
putBucketRequest.setXCOSGrantRead(readACLS);

//赋予被授权者写的权限
ACLAccount writeACLS = new ACLAccount();
writeACLS.addAccount("OwnerUin", "SubUin");
putBucketRequest.setXCOSGrantRead(writeACLS);

//赋予被授权者读写的权限
ACLAccount writeandReadACLS = new ACLAccount();
writeandReadACLS.addAccount("OwnerUin", "SubUin");
putBucketRequest.setXCOSGrantRead(writeandReadACLS);

//使用同步方法
try {
    PutBucketResult putBucketResult = cosXmlService.putBucket(putBucketRequest);
} catch (CosXmlClientException e) {
    e.printStackTrace();
} catch (CosXmlServiceException e) {
    e.printStackTrace();
}

// 使用异步回调请求
cosXmlService.putBucketAsync(putBucketRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        // todo Put Bucket success
        PutBucketResult putBucketResult = (putBucketResult)result;
    }

    @Override
    public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException)  {
        // todo Put Bucket failed because of CosXmlClientException or CosXmlServiceException...
    }
});

说明:

请求时,如需直接设置已计算好的签名串,则可通过调用 putBucketRequest.setSign("已计算好的签名串") 方法设置,默认由 SDK 计算签名串。

参数说明

参数名称 设置方法 描述 类型
bucket 构造方法 存储桶名称,格式:BucketName-APPID string
headerKeys setSign 签名是否校验 header Set<String>
queryParameterKeys setSign 签名是否校验请求 url 中查询参数 Set<String>
cosXmlResultListener putBucketAsync 结果回调 CosXmlResultListener

返回结果说明

通过 PutBucketResult 返回请求结果。

成员变量 类型 描述
httpCode int HTTP Code, [200,300)之间表示操作成功,否则表示操作失败

说明:

操作失败时,SDK 将抛出 CosXmlClientExceptionCosXmlServiceException 异常。

检索存储桶及其权限

功能说明

检索存储桶是否存在且是否有权限访问(HEAD Bucket)。

HeadBucketResult headBucket(HeadBucketRequest request) throws CosXmlClientException, CosXmlServiceException;

void headBucketAsync(HeadBucketRequest request, CosXmlResultListener cosXmlResultListener);

请求示例

String bucket = "examplebucket-1250000000"; //格式:BucketName-APPID
HeadBucketRequest headBucketRequest = new HeadBucketRequest(bucket);

//使用同步方法
try {
    HeadBucketResult headBucketResult = cosXmlService.headBucket(headBucketRequest);
} catch (CosXmlClientException e) {
    e.printStackTrace();
} catch (CosXmlServiceException e) {
    e.printStackTrace();
}

// 使用异步回调请求
cosXmlService.headBucketAsync(headBucketRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        // todo Head Bucket success
        HeadBucketResult headBucketResult = (HeadBucketResult)result;
    }

    @Override
    public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException)  {
        // todo Head Bucket failed because of CosXmlClientException or CosXmlServiceException...
    }
});

说明:

请求时,如需直接设置已计算好的签名串,则可通过调用 headBucketRequest.setSign("已计算好的签名串") 方法设置,默认由 SDK 计算签名串。

参数说明

参数名称 设置方法 描述 类型
bucket 构造方法 存储桶名称,格式:BucketName-APPID string
headerKeys setSign 签名是否校验 header Set<String>
queryParameterKeys setSign 签名是否校验请求 url 中查询参数 Set<String>
cosXmlResultListener headBucketAsync 结果回调 CosXmlResultListener

返回结果说明

通过 HeadBucketResult 返回请求结果。

成员变量 类型 描述
httpCode int HTTP Code, [200,300)之间表示操作成功,否则表示操作失败

说明:

操作失败时,SDK 将抛出 CosXmlClientExceptionCosXmlServiceException 异常。

删除存储桶

功能说明

删除指定的存储桶(DELETE Bucket)。

方法原型

DeleteBucketResult deleteBucket(DeleteBucketRequest request) throws CosXmlClientException, CosXmlServiceException;

void deleteBucketAsync(DeleteBucketRequest request, CosXmlResultListener cosXmlResultListener);

请求示例

String bucket = "examplebucket-1250000000"; //格式:BucketName-APPID
DeleteBucketRequest deleteBucketRequest = new DeleteBucketRequest(bucket);

// 使用同步方法
try {
    DeleteBucketResult deleteBucketResult = cosXmlService.deleteBucket(deleteBucketRequest);
} catch (CosXmlClientException e) {
    e.printStackTrace();
} catch (CosXmlServiceException e) {
    e.printStackTrace();
}

// 使用异步回调请求
cosXmlService.deleteBucketAsync(deleteBucketRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        // todo Delete Bucket success
        DeleteBucketResult deleteBucketResult = (DeleteBucketResult)result;
    }

    @Override
    public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException)  {
        // todo Delete Bucket failed because of CosXmlClientException or CosXmlServiceException...
    }
});

说明:

请求时,如需直接设置已计算好的签名串,则可通过调用 deleteBucketRequest.setSign("已计算好的签名串") 方法设置,默认由 SDK 计算签名串。

参数说明

参数名称 设置方法 描述 类型
bucket 构造方法 存储桶名称,格式:BucketName-APPID string
headerKeys setSign 签名是否校验 header Set<String>
queryParameterKeys setSign 签名是否校验请求 url 中查询参数 Set<String>
cosXmlResultListener deleteBucketAsync 结果回调 CosXmlResultListener

返回结果说明

通过 DeleteBucketResult 返回请求结果。

成员变量 类型 描述
httpCode int HTTP Code, [200,300)之间表示操作成功,否则表示操作失败

说明:

操作失败时,SDK 将抛出 CosXmlClientExceptionCosXmlServiceException 异常。

访问控制列表

设置存储桶 ACL

功能说明

设置指定存储桶访问权限控制列表(PUT Bucket acl)。

方法原型

PutBucketACLResult putBucketACL(PutBucketACLRequest request) throws CosXmlClientException, CosXmlServiceException;

void putBucketACLAsync(PutBucketACLRequest request, CosXmlResultListener cosXmlResultListener);

请求示例

String bucket = "examplebucket-1250000000"; //格式:BucketName-APPID
PutBucketACLRequest putBucketACLRequest = new PutBucketACLRequest(bucket);

//设置 bucket 访问权限
putBucketACLRequest.setXCOSACL("public-read");

//赋予被授权者读的权限
ACLAccount readACLS = new ACLAccount();
readACLS.addAccount("OwnerUin", "SubUin");
putBucketACLRequest.setXCOSGrantRead(readACLS);

//赋予被授权者写的权限
ACLAccount writeACLS = new ACLAccount();
writeACLS.addAccount("OwnerUin", "SubUin");
putBucketACLRequest.setXCOSGrantRead(writeACLS);

//赋予被授权者读写的权限
ACLAccount writeandReadACLS = new ACLAccount();
writeandReadACLS.addAccount("OwnerUin", "SubUin");
putBucketACLRequest.setXCOSGrantRead(writeandReadACLS);

// 使用同步方法
try {
    PutBucketACLResult putBucketACLResult = cosXmlService.putBucketACL(putBucketACLRequest);
} catch (CosXmlClientException e) {
    e.printStackTrace();
} catch (CosXmlServiceException e) {
    e.printStackTrace();
}

// 使用异步回调请求
cosXmlService.putBucketACLAsync(putBucketACLRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        // todo Put Bucket ACL success
        PutBucketACLResult putBucketACLResult = (PutBucketACLResult)result;
    }

    @Override
    public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException)  {
        // todo Put Bucket ACL failed because of CosXmlClientException or CosXmlServiceException...
    }
});

说明:

请求时,如需直接设置已计算好的签名串,则可通过调用 putBucketACLRequest.setSign("已计算好的签名串") 方法设置,默认由 SDK 计算签名串。

参数说明

参数名称 设置方法 描述 类型
bucket 构造方法 存储桶名称,格式:BucketName-APPID string
cosAcl SetCosAcl 设置存储桶的 ACL 权限 string
grandtAccout SetXCosGrantRead 或 SetXCosGrantWrite 或 SetXCosReadWrite 授予用户读写权限 GrantAccount
headerKeys setSign 签名是否校验 header Set<String>
queryParameterKeys setSign 签名是否校验请求 url 中查询参数 Set<String>
cosXmlResultListener putBucketACLAsync 结果回调 CosXmlResultListener

返回结果说明

通过 PutBucketACLResult 返回请求结果。

成员变量 类型 描述
httpCode int HTTP Code, [200,300)之间表示操作成功,否则表示操作失败

说明:

操作失败时,SDK 将抛出 CosXmlClientExceptionCosXmlServiceException 异常。

查询存储桶 ACL

功能说明

查询指定存储桶的访问权限控制列表(GET Bucket acl)。

方法原型

GetBucketACLResult getBucketACL(GetBucketACLRequest request) throws CosXmlClientException, CosXmlServiceException;

void getBucketACLAsync(GetBucketACLRequest request, CosXmlResultListener cosXmlResultListener);

请求示例

String bucket = "examplebucket-1250000000"; //格式:BucketName-APPID
GetBucketACLRequest getBucketACLRequest = new GetBucketACLRequest(bucket);

// 使用同步方法
try {
    GetBucketACLResult getBucketACLResult = cosXmlService.getBucketACL(getBucketACLRequest);
} catch (CosXmlClientException e) {
    e.printStackTrace();
} catch (CosXmlServiceException e) {
    e.printStackTrace();
}

// 使用异步回调请求
cosXmlService.getBucketACLAsync(getBucketACLRequest, new CosXmlResultListener() {
    @Override
    public void onSuccess(CosXmlRequest request, CosXmlResult result) {
        // todo Get Bucket ACL success
        GetBucketACLResult getBucketACLResult = (GetBucketACLResult)result;
    }

    @Override
    public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException)  {
        // todo Get Bucket ACL failed because of CosXmlClientException or CosXmlServiceException...
    }
});

说明:

请求时,如需直接设置已计算好的签名串,则可通过调用 getBucketACLRequest.setSign("已计算好的签名串") 方法设置,默认由 sdk 计算签名串。

参数说明

参数名称 设置方法 描述 类型
bucket 构造方法 存储桶名称,格式:BucketName-APPID string
headerKeys setSign 签名是否校验 header Set<String>
queryParameterKeys setSign 签名是否校验请求 url 中查询参数 Set<String>
cosXmlResultListener getBucketACLAsync 结果回调 CosXmlResultListener

返回结果说明

通过 GetBucketACLResult 返回请求结果。

成员变量 类型 描述
httpCode int HTTP Code, [200,300)之间表示操作成功,否则表示操作失败
accessControlPolicy AccessControlPolicy 返回 Bucket 访问权限列表信息

说明:

操作失败时,SDK 将抛出 CosXmlClientExceptionCosXmlServiceException 异常。