Bucket Management

Last updated: 2019-08-19 10:20:31

    Overview

    This document provides an overview of APIs related to cross-origin access, lifecycle, versioning, and cross-region replication and corresponding SDK sample code.

    Cross-origin access

    API Operation Name Operation Description
    PUT Bucket cors Setting cross-origin access configuration Sets the cross-origin access permission of a bucket
    GET Bucket cors Querying cross-origin access configuration Queries the cross-origin access configuration information of a bucket
    DELETE Bucket cors Deleting cross-origin access configuration Deletes the cross-origin access configuration information of a bucket

    Lifecycle

    API Operation Name Operation Description
    PUT Bucket lifecycle Setting lifecycle Sets the lifecycle management configuration of a bucket
    GET Bucket lifecycle Querying lifecycle Queries the lifecycle management configuration of a bucket
    DELETE Bucket lifecycle Deleting lifecycle Deletes the lifecycle management configuration of a bucket

    Versioning

    API Operation Name Operation Description
    PUT Bucket versioning Setting versioning Sets the versioning feature of a bucket
    GET Bucket versioning Querying versioning Queries the versioning information of a bucket

    Cross-region replication

    API Operation Name Operation Description
    PUT Bucket replication Setting cross-region replication Sets the cross-region replication rule of a bucket
    GET Bucket replication Querying cross-region replication Queries the cross-region replication rule of a bucket
    DELETE Bucket replication Deleting cross-region replication Deletes the cross-region replication rule of a bucket

    Cross-origin Access

    Setting Cross-origin Access Configuration

    Feature Description

    This API is used to set the cross-origin access permission to a bucket.

    Method Prototype

    CosResult PutBucketCORS(const PutBucketCORSReq& req, PutBucketCORSResp* resp)

    Sample Request

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    // The constructor of PutBucketCORSReq requires bucket_name to be passed in
    qcloud_cos::PutBucketCORSReq req(bucket_name);
    qcloud_cos::CORSRule rule;
    rule.m_id = "123";
    rule.m_allowed_headers.push_back("x-cos-meta-test");
    rule.m_allowed_origins.push_back("http://www.qq.com");
    rule.m_allowed_origins.push_back("http://intl.cloud.tentent.com");
    rule.m_allowed_methods.push_back("PUT");
    rule.m_allowed_methods.push_back("GET");
    rule.m_max_age_secs = "600";
    rule.m_expose_headers.push_back("x-cos-expose");
    req.AddRule(rule);
    
    qcloud_cos::PutBucketCORSResp resp;
    qcloud_cos::CosResult result = cos.PutBucketCORS(req, &resp);
    
    // The call is successful. You can call the member function of resp to get the return content
    if (result.IsSucc()) {
        // ...
    } else {
        // You can call the member function of CosResult to output the error information such as requestID
    } 

    Parameter Descriptions

    Parameter Description
    req PutBucketCORSReq, which is the request for the PutBucketCORS operation
    resp PutBucketCORSResp, which is the return of the PutBucketCORS operation

    PutBucketCORSReq provides the following member functions:

    // Add a CORSRule
    void AddRule(const CORSRule& rule);
    
    // Set a CORSRule
    void SetRules(const std::vector<CORSRule>& rules)

    CORSRule is defined as follows:

    struct CORSRule {
        std::string m_id; // Configured rule ID; optional
        std::string m_max_age_secs; // Set the validity period of the result of the OPTIONS request
        std::vector<std::string> m_allowed_headers; // Tell the server what custom HTTP request headers can be used for subsequent requests when the OPTIONS request is sent. Wildcard * is supported
        std::vector<std::string> m_allowed_methods; // Allowed HTTP operations. Enumerated values: GET, PUT, HEAD, POST, DELETE
        std::vector<std::string> m_allowed_origins; // Allowed origin in the format of protocol://domain name[:port number], such as http://www.qq.com. Wildcard * is supported
        std::vector<std::string> m_expose_headers;  // Set custom header information from the server that the browser can receive
    };

    Querying Cross-origin Access Configuration

    Feature Description

    This API is used to query the cross-origin access configuration information of a bucket.

    Method Prototype

    CosResult GetBucketCORS(const GetBucketCORSReq& req, GetBucketCORSResp* resp)

    Sample Request

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    // The constructor of GetBucketCORSReq requires bucket_name to be passed in
    qcloud_cos::GetBucketCORSReq req(bucket_name);
    qcloud_cos::GetBucketCORSResp resp;
    qcloud_cos::CosResult result = cos.GetBucketCORS(req, &resp);
    
    // The call is successful. You can call the member function of resp to get the return content
    if (result.IsSucc()) {
        // ...
    } else {
        // You can call the member function of CosResult to output the error information such as requestID
    } 

    Parameter Descriptions

    Parameter Description
    req GetBucketCORSReq, which is the request for the GetBucketCORS operation
    resp GetBucketCORSResp, which is the return of the GetBucketCORS operation

    GetBucketCORSResp provides the following member functions:

    // Get CORSRules. For the definition of CORSRule, see Put Bucket CORS
    std::vector<CORSRule> GetCORSRules();

    Deleting Cross-origin Access Configuration

    Feature Description

    This API is used to delete the cross-origin access configuration of the specified bucket.

    Method Prototype

    CosResult DeleteBucketCORS(const DeleteBucketCORSReq& req, DeleteBucketCORSResp* resp)

    Sample Request

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    // The constructor of DeleteBucketCORSReq requires bucket_name to be passed in
    qcloud_cos::DeleteBucketCORSReq req(bucket_name);
    qcloud_cos::DeleteBucketCORSResp resp;
    qcloud_cos::CosResult result = cos.DeleteBucketCORS(req, &resp);
    
    // The call is successful. You can call the member function of resp to get the return content
    if (result.IsSucc()) {
        // ...
    } else {
        // You can call the member function of CosResult to output the error information such as requestID
    } 

    Parameter Descriptions

    Parameter Description
    req DeleteBucketCORSReq, which is the request for the DeleteBucketCORS operation
    resp DeleteBucketCORSResp, which is the return of the DeleteBucketCORS operation

    Lifecycle

    Setting Lifecycle

    Feature Description

    This API is used to set the lifecycle configuration information of the specified bucket.

    Method Prototype

    CosResult PutBucketLifecycle(const PutBucketLifecycleReq& req, PutBucketLifecycleResp* resp)

    Sample Request

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    // The constructor of PutBucketLifecycleReq requires bucket_name to be passed in
    qcloud_cos::PutBucketLifecycleReq req(bucket_name);
    // Set rule 1
    {
        qcloud_cos::LifecycleRule rule;
        rule.SetIsEnable(true);
        rule.SetId("lifecycle_rule00");
        qcloud_cos::LifecycleFilter filter;
        filter.SetPrefix("sevenyou_e1");
        rule.SetFilter(filter);
        qcloud_cos::LifecycleExpiration expiration;
        expiration.SetDays(1);
        rule.SetExpiration(expiration);
        req.AddRule(rule);
    }
    
    // Set rule 2
    {
        qcloud_cos::LifecycleRule rule;
        rule.SetIsEnable(true);
        rule.SetId("lifecycle_rule01");
        qcloud_cos::LifecycleFilter filter;
        filter.SetPrefix("sevenyou_e2");
        rule.SetFilter(filter);
        qcloud_cos::LifecycleExpiration expiration;
        expiration.SetDays(3);
        rule.SetExpiration(expiration);
        req.AddRule(rule);
    }
    
    qcloud_cos::PutBucketLifecycleResp resp;
    qcloud_cos::CosResult result = cos.PutBucketLifecycle(req, &resp);
    
    // The call is successful. You can call the member function of resp to get the return content
    if (result.IsSucc()) {
        // ...
    } else {
        // Failed to set the lifecycle. You can call the member function of CosResult to output the error information such as requestID
    } 

    Parameter Descriptions

    Parameter Description
    req PutBucketLifecycleReq, which is the request for the PutBucketLifecycle operation
    resp PutBucketLifecycleResp, which is the return of the PutBucketLifecycle operation

    PutBucketLifecycleReq provides the following member functions:

    // Add a LifecycleRule
    void AddRule(const LifecycleRule& rule)
    
    // Set a LifecycleRule
    void SetRule(const std::vector<LifecycleRule>& rules)

    The definition of LifecycleRule is quite complicated as follows:

    struct LifecycleTag {
        std::string key;
        std::string value;
    };
    
    class LifecycleFilter {
    public:
        LifecycleFilter();
    
        std::string GetPrefix();
        std::vector<LifecycleTag> GetTags();
    
        void SetPrefix(const std::string& prefix);
        void SetTags(const std::vector<LifecycleTag>& tags);
        void AddTag(const LifecycleTag& tag);
    
        bool HasPrefix();
        bool HasTags();
    
    private:
        std::string m_prefix; // Specify the prefix to which the rule applies. Objects that match the prefix are subject to this rule. There can be at most one prefix
        std::vector<LifecycleTag> m_tags; // Tag. There can be zero, one, or multiple tags
    };
    
    class LifecycleTransition {
    public:
        LifecycleTransition();
    
        uint64_t GetDays();
        std::string GetDate();
        std::string GetStorageClass();
    
        void SetDays(uint64_t days);
        void SetDate(const std::string& date);
        void SetStorageClass(const std::string& storage_class);
    
        bool HasDays();
        bool HasDate();
        bool HasStorageClass();
    
    private:
        // Days and Date cannot be used in the same rule at the same time
        uint64_t m_days; // Specify the number of days after the last modified date of an object that should elapse before the action corresponding to a rule is performed. A valid value is a non-negative integer
        std::string m_date; // Specify when the action corresponding to a rule should be performed
        std::string m_storage_class; // Specify the transitioned storage class of an object. Enumerated values: Standard_IA
    };
    
    class LifecycleExpiration {
    public:
        LifecycleExpiration();
    
        uint64_t GetDays();
        std::string GetDate();
        bool IsExpiredObjDelMarker();
    
        void SetDays(uint64_t days);
        void SetDate(const std::string& date);
        void SetExpiredObjDelMarker(bool marker);
    
        bool HasDays();
        bool HasDate();
        bool HasExpiredObjDelMarker();
    
    private:
        // Days and Date cannot be used in the same rule at the same time
        uint64_t m_days; // Specify the number of days after the last modified date of an object that should elapse before the action corresponding to a rule is performed. A valid value is a positive integer
        std::string m_date; // Specify when the action corresponding to a rule should be performed
        ool m_expired_obj_del_marker; // Delete the expired object deletion tag; enumerated values: true, false
    };
    
    class LifecycleNonCurrTransition {
    public:
        LifecycleNonCurrTransition();
    
        uint64_t GetDays();
        std::string GetStorageClass();
    
        void SetDays(uint64_t days);  
        void SetStorageClass(const std::string& storage_class);
    
        bool HasDays();
        bool HasStorageClass();
    
    private:
        uint64_t m_days; // Specify the number of days after the last modified date of an object that should elapse before the action corresponding to a rule is performed. A valid value is a non-negative integer
        std::string m_storage_class; // Specify the transitioned storage class of an object. Enumerated values: Standard_IA
    };
    
    class LifecycleNonCurrExpiration {
    public:
        LifecycleNonCurrExpiration();
    
        uint64_t GetDays();
    
        void SetDays(uint64_t days);
    
        bool HasDays();
    
    private:
        uint64_t m_days; // Specify the number of days after the last modified date of an object that should elapse before the action corresponding to a rule is performed. A valid value is a positive integer
    };
    
    struct AbortIncompleteMultipartUpload {
        uint64_t m_days_after_init; // Indicate in how many days a multipart upload has to be completed once started
    };
    
    class LifecycleRule {
    public:
        LifecycleRule();
    
        void SetIsEnable(bool is_enable);
        void SetId(const std::string& id);
        void SetFilter(const LifecycleFilter& filter);
        void AddTransition(const LifecycleTransition& rh);
        void SetExpiration(const LifecycleExpiration& rh);
        void SetNonCurrTransition(const LifecycleNonCurrTransition& rh);
        void SetNonCurrExpiration(const LifecycleNonCurrExpiration& rh);
        void SetAbortIncompleteMultiUpload(const AbortIncompleteMultipartUpload& rh);
    
        bool IsEnable();
        std::string GetId();
        LifecycleFilter GetFilter();
        std::vector<LifecycleTransition> GetTransitions();
        LifecycleExpiration GetExpiration();
        LifecycleNonCurrTransition GetNonCurrTransition();
        LifecycleNonCurrExpiration GetNonCurrExpiration();
        AbortIncompleteMultipartUpload GetAbortIncompleteMultiUpload();
    
        bool HasIsEnable();
        bool HasId();
        bool HasFilter();
        bool HasExpiration();
        bool HasNonCurrTransition();
        bool HasNonCurrExpiration();
        bool HasAbortIncomMultiUpload();
    
    private:
        bool m_is_enable; // Whether the rule is effective
        std::string m_id; // Rule ID
        LifecycleFilter m_filter; // Filter used to specify the range of objects for which the rule takes effect
        std::vector<LifecycleTransition> m_transitions; // Transition operation
        LifecycleExpiration m_expiration; // Expiration operation
        LifecycleNonCurrTransition m_non_curr_transition; // Non-current version transition operation
        LifecycleNonCurrExpiration m_non_curr_expiration; // Non-current version expiration operation
        AbortIncompleteMultipartUpload m_abort_multi_upload; // Set the maximum amount of time allowed for a multipart upload to keep running
    }

    Querying Lifecycle

    Feature Description

    This API is used to query the lifecycle configuration information of the specified bucket.

    Method Prototype

    CosResult GetBucketLifecycle(const GetBucketLifecycleReq& req, GetBucketLifecycleResp* resp)

    Sample Request

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    // The constructor of GetBucketLifecycleReq requires bucket_name to be passed in
    qcloud_cos::GetBucketLifecycleReq req(bucket_name);
    qcloud_cos::GetBucketLifecycleResp resp;
    qcloud_cos::CosResult result = cos.GetBucketLifecycle(req, &resp);
    
    // The call is successful. You can call the member function of resp to get the return content
    if (result.IsSucc()) {
        // ...
    } else {
        // Failed to get the lifecycle configuration. You can call the member function of CosResult to output the error information such as requestID
    } 

    Parameter Descriptions

    Parameter Description
    req GetBucketLifecycleReq, which is the request for the GetBucketLifecycle operation
    resp GetBucketLifecycleResp, which is the return of the GetBucketLifecycle operation

    GetBucketLifecycleResp provides the following member functions:

    // Get LifecycleRules
    std::vector<LifecycleRule> GetRules()

    For the definition of LifecycleRule, see PUT Bucket lifecycle.

    Deleting Lifecycle

    Feature Description

    This API is used to delete the lifecycle configuration information of the specified bucket.

    Method Prototype

    CosResult DeleteBucketLifecycle(const DeleteBucketLifecycleReq& req, DeleteBucketLifecycleResp* resp)

    Sample Request

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    // The constructor of DeleteBucketLifecycleReq requires bucket_name to be passed in
    qcloud_cos::DeleteBucketLifecycleReq req(bucket_name);
    qcloud_cos::DeleteBucketLifecycleResp resp;
    qcloud_cos::CosResult result = cos.DeleteBucketLifecycle(req, &resp);
    
    // The call is successful. You can call the member function of resp to get the return content
    if (result.IsSucc()) {
        // ...
    } else {
        // Failed to delete the lifecycle configuration. You can call the member function of CosResult to output the error information such as requestID
    } 

    Parameter Descriptions

    Parameter Description
    req DeleteBucketLifecycleReq, which is the request for the DeleteBucketLifecycle operation
    resp DeleteBucketLifecycleResp, which is the return of the DeleteBucketLifecycle operation

    Versioning

    Setting Versioning

    Feature Description

    This API is used to set the versioning feature of the specified bucket.

    Method Prototype

    CosResult PutBucketVersioning(const PutBucketVersioningReq& request, PutBucketVersioningResp* response)

    Sample Request

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    // The constructor of PutBucketVersioningReq requires bucket_name to be passed in
    qcloud_cos::PutBucketVersioningReq req(bucket_name);
    req.SetStatus(true);
    qcloud_cos::PutBucketVersioningResp resp;
    qcloud_cos::CosResult result = cos.PutBucketVersioning(req, &resp);
    
    // The call is successful. You can call the member function of resp to get the return content
    if (result.IsSucc()) {
        // ...
    } else {
        // You can call the member function of CosResult to output the error information such as requestID
    } 

    Parameter Descriptions

    Parameter Description
    req PutBucketVersioningReq, which is the request for the PutBucketVersioning operation
    resp PutBucketVersioningResp, which is the return of the PutBucketVersioning operation

    PutBucketVersioningReq provides the following member functions:

    // Whether versioning is enabled. Once enabled, it cannot be disabled; instead, it can only be suspended
    void SetStatus(bool is_enable);

    Querying Versioning

    Feature Description

    This API is used to query the versioning information of the specified bucket.

    Method Prototype

    CosResult GetBucketVersioning(const GetBucketVersioningReq& request, GetBucketVersioningResp* response) 

    Sample Request

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    qcloud_cos::GetBucketVersioningReq req(bucket_name);
    qcloud_cos::GetBucketVersioningResp resp;
    qcloud_cos::CosResult result = cos.GetBucketVersioning(req, &resp);
    
    // The call is successful. You can call the member function of resp to get the return content
    if (result.IsSucc()) {
        // ...
    } else {
        // You can call the member function of CosResult to output the error information such as requestID
    } 

    Parameter Descriptions

    Parameter Description
    req GetBucketVersioningReq, which is the request for the GetBucketVersioning operation
    resp GetBucketVersioningResp, which is the return of the GetBucketVersioning operation

    GetBucketVersioningResp provides the following member functions:

    // Return the versioning status of the bucket. 0: versioning never enabled; 1: versioning enabled; 2: versioning suspended
    int GetStatus() const

    Cross-region Replication

    Setting Cross-region Replication

    Feature Description

    This API is used to set the cross-region replication rule of the specified bucket.

    Method Prototype

    func (s *BucketService) PutBucketReplication(ctx context.Context, opt *PutBucketReplicationOptions) (*Response, error)

    Sample Request

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    qcloud_cos::PutBucketReplicationReq req(bucket_name);
    req.SetRole("qcs::cam::uin/100000000001:uin/100000000001");
    qcloud_cos::ReplicationRule rule("", "qcs::cos:ap-guangzhou::examplebucket-1250000000", "", "", true);
    
    req.AddReplicationRule(rule);
    qcloud_cos::PutBucketReplicationResp resp;
    qcloud_cos::CosResult result = cos.PutBucketReplication(req, &resp);
    
    // The call is successful. You can call the member function of resp to get the return content
    if (result.IsSucc()) {
        // ...
    } else {
        // You can call the member function of CosResult to output the error information such as requestID
    }

    Parameter Descriptions

    Parameter Description
    req PutBucketReplicationReq, which is the request for the PutBucketReplication operation
    resp PutBucketReplicationResp, which is the return of the PutBucketReplication operation

    PutBucketReplicationReq provides the following member functions:

    // Initiator ID: qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    void SetRole(const std::string& role);
    // Add specific configuration information of up to 1,000 rules. All rules must point to the same destination bucket
    void AddReplicationRule(const ReplicationRule& rule);
    
    // The structure of ReplicationRule is as follows:
    struct ReplicationRule {
        bool m_is_enable;
        std::string m_id; // Optional
        std::string m_prefix;
        std::string m_dest_bucket;
        std::string m_dest_storage_class; // Optional 
    }

    Querying Cross-region Replication

    Feature Description

    This API is used to query the cross-region replication rule of the specified bucket.

    Method Prototype

    CosResult GetBucketReplication(const GetBucketReplicationReq& request, GetBucketReplicationResp* response)

    Sample Request

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    qcloud_cos::GetBucketReplicationReq req(bucket_name);
    qcloud_cos::GetBucketReplicationResp resp;
    qcloud_cos::CosResult result = cos.GetBucketReplication(req, &resp);
    
    // The call is successful. You can call the member function of resp to get the return content
    if (result.IsSucc()) {
        // ...
    } else {
        // You can call the member function of CosResult to output the error information such as requestID
    } 

    Parameter Descriptions

    Parameter Description
    req GetBucketReplicationReq, which is the request for the GetBucketReplication operation
    resp GetBucketReplicationResp, which is the return of the GetBucketReplication operation

    GetBucketReplicationResp provides the following member functions:

    // Get the initiator ID: qcs::cam::uin/<OwnerUin>:uin/<SubUin>
    std::string GetRole();
    // Get specific configuration information of up to 1,000 rules. All rules must point to the same destination bucket
    std::vector<ReplicationRule> GetRules();
    // The structure of ReplicationRule is as described in PutBucketReplication

    Deleting Cross-region Replication

    Feature Description

    This API is used to delete the cross-region replication rule of the specified bucket.

    Method Prototype

    CosResult DeleteBucketReplication(const DeleteBucketReplicationReq& request, DeleteBucketReplicationResp* response)

    Sample Request

    qcloud_cos::CosConfig config("./config.json");
    qcloud_cos::CosAPI cos(config);
    
    std::string bucket_name = "examplebucket-1250000000";
    
    qcloud_cos::DeleteBucketReplicationReq req(bucket_name);
    qcloud_cos::DeleteBucketReplicationResp resp;
    qcloud_cos::CosResult result = cos.DeleteBucketReplication(req, &resp);
    
    // The call is successful. You can call the member function of resp to get the return content
    if (result.IsSucc()) {
        // ...
    } else {
        // You can call the member function of CosResult to output the error information such as requestID
    } 

    Parameter Descriptions

    Parameter Description
    req DeleteBucketReplicationReq, which is the request for the DeleteBucketReplication operation
    resp DeleteBucketReplicationResp, which is the return of the DeleteBucketReplication operation

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help