存储桶操作

最后更新时间:2021-04-02 21:21:55

    简介

    本文档提供关于存储桶基本操作的相关 API 概览以及 SDK 示例代码。

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

    查询存储桶列表

    功能说明

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

    方法原型

    CosResult GetService(const GetServiceReq& request, GetServiceResp* response)
    

    请求示例

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    qcloud_cos::GetServiceReq req;
    qcloud_cos::GetServiceResp resp;
    qcloud_cos::CosResult result = cos.GetService(req, &resp);
    
    // 调用成功,调用 resp 的成员函数获取返回内容
    if (result.IsSucc()) {
        const qcloud_cos::Owner& owner = resp.GetOwner();
        const std::vector<qcloud_cos::Bucket>& buckets = resp.GetBuckets();
        std::cout << "owner.m_id=" << owner.m_id << ", owner.display_name=" << owner.m_display_name << std::endl;               
         for (std::vector<qcloud_cos::Bucket>::const_iterator itr = buckets.begin(); itr != buckets.end(); ++itr) {
             const qcloud_cos::Bucket& bucket = *itr;
             std::cout << "Bucket name=" << bucket.m_name << ", location=" 
             << bucket.m_location << ", create_date=" << bucket.m_create_date << std::endl;                                  
         } 
    } else {
        // 可以调用 CosResult 的成员函数输出错误信息,如 requestID 等
    } 
    

    参数说明

    参数 参数描述 类型 是否必填
    req GetService 操作的请求 GetServiceReq
    resp GetService 操作的响应 GetServiceResp

    GetServiceResp 提供以下成员函数,用于获取 Get Service 返回的 XML 格式中的具体内容。

    // 获取 Bucket 持有者的信息
    Owner GetOwner() const;
    // 获取所有 Bucket 列表信息
    std::vector<Bucket> GetBuckets() const
    

    其中 Owner 的定义如下:

    struct Owner {
        std::string m_id;    // 存储桶所有者的 ID
        std::string m_display_name; // 存储桶所有者的名字信息
    }; 
    

    其中 Bucket 的定义如下:

    // 描述单个 Bucket 的信息                                                                                                                                                                    
    struct Bucket {
        std::string m_name; // Bucket 名称
        std::string m_location; // Bucket 所在地域
        std::string m_create_date; // Bucket 创建时间。ISO8601 格式,例如 2016-11-09T08:46:32.000Z
    };
    

    创建存储桶

    功能说明

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

    方法原型

    CosResult PutBucket(const PutBucketReq& req, PutBucketResp* resp)
    

    请求示例

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    qcloud_cos::PutBucketReq req(bucket_name);
    qcloud_cos::PutBucketResp resp;
    qcloud_cos::CosResult result = cos.PutBucket(req, &resp);
    
    // 调用成功,调用 resp 的成员函数获取返回内容
    if (result.IsSucc()) {
        // ...
    } else {
        // 可以调用 CosResult 的成员函数输出错误信息,如 requestID 等
    } 
    

    参数说明

    参数 参数描述 类型 是否必填
    req PutBucket 操作的请求 PutBucketReq
    resp PutBucket 操作的响应 PutBucketResp

    PutBucketReq 提供以下成员函数:

    // 定义 Bucket 的 ACL 属性,有效值:private,public-read-write,public-read
    // 默认值:private
    void SetXCosAcl(const std::string& str);
    
    // 赋予被授权者读的权限.格式:x-cos-grant-read: id=" ",id=" ".
    // 当需要给子账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
    // 当需要给根账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
    void SetXCosGrantRead(const std::string& str);
    
    // 赋予被授权者写的权限,格式:x-cos-grant-write: id=" ",id=" "./
    // 当需要给子账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
    // 当需要给根账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
    void SetXCosGrantWrite(const std::string& str);
        
    // 赋予被授权者读写权限.格式:x-cos-grant-full-control: id=" ",id=" ".
    // 当需要给子账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
    // 当需要给根账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
    void SetXCosGrantFullControl(const std::string& str);
    

    检索存储桶及其权限

    功能说明

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

    方法原型

    CosResult HeadBucket(const HeadBucketReq& req, HeadBucketResp* resp)
    

    请求示例

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    qcloud_cos::HeadBucketReq req(bucket_name);
    qcloud_cos::HeadBucketResp resp;
    qcloud_cos::CosResult result = cos.HeadBucket(req, &resp);
    
    // 调用成功,调用 resp 的成员函数获取返回内容
    if (result.IsSucc()) {
        // ...
    } else {
        // 可以调用 CosResult 的成员函数输出错误信息,如 requestID 等
    } 
    

    参数说明

    参数 参数描述 类型 是否必填
    req HeadBucket 操作的请求 HeadBucketReq
    resp HeadBucket 操作的响应 HeadBucketResp

    删除存储桶

    功能说明

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

    方法原型

    CosResult DeleteBucket(const DeleteBucketReq& req, DeleteBucketResp* resp)
    

    请求示例

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    // DeleteBucketReq 的构造函数需要传入 bucket_name
    qcloud_cos::DeleteBucketReq req(bucket_name);
    qcloud_cos::DeleteBucketResp resp;
    qcloud_cos::CosResult result = cos.DeleteBucket(req, &resp);
    
    // 调用成功,调用 resp 的成员函数获取返回内容
    if (result.IsSucc()) {
        // ...
    } else {
        // 可以调用 CosResult 的成员函数输出错误信息,如 requestID 等
    } 
    

    参数说明

    参数 参数描述 类型 是否必填
    req DeleteBucket 操作的请求 DeleteBucketReq
    resp DeleteBucket 操作的响应 DeleteBucketResp