This document provides an overview of APIs related to basic bucket operations and access control lists (ACL) as well as their corresponding SDK sample code.
Basic operations
API | Operation Name | Operation Description |
---|---|---|
GET Service | Querying a bucket list | Queries the list of all buckets under a specified account |
PUT Bucket | Creating a bucket | Creates a bucket under a specified account |
HEAD Bucket | Checking a bucket and its permission | Checks whether a bucket exists and you have permission to access it |
DELETE Bucket | Deleting a bucket | Deletes an empty bucket under a specified account |
ACL
API | Operation Name | Operation Description |
---|---|---|
PUT Bucket acl | Setting bucket ACL | Sets the ACL for a specified bucket |
GET Bucket acl | Querying bucket ACL | Queries the ACL of a bucket |
This API is used to query the list of all buckets under a specified account.
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);
// The call is successful. You can call the resp member functions to get the return content
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 {
// You can call the CosResult member functions to output the error information, such as requestID
}
Parameter | Description |
---|---|
req | GetServiceReq, the request for the GetServiceReq operation |
resp | GetServiceResp, the return of the GetService operation |
GetServiceResp provides the following member functions for getting the specific content (in XML format) returned by Get Service.
// Get bucket owner information
Owner GetOwner() const;
// Get list information for all buckets
std::vector<Bucket> GetBuckets() const
Owner is defined as follows:
struct Owner {
std::string m_id; // Bucket owner ID
std::string m_display_name; // Bucket owner name
};
Bucket is defined as follows:
// Describe the information of a single bucket
struct Bucket {
std::string m_name; // Bucket name
std::string m_location; // Bucket region
std::string m_create_date; // Bucket creation time in ISO8601 format, such as 2016-11-09T08:46:32.000Z
};
This API is used to create a 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);
// The call is successful. You can call the resp member functions to get the return content
if (result.IsSucc()) {
// ...
} else {
// You can call the CosResult member functions to output the error information, such as requestID
}
Parameter | Description |
---|---|
req | PutBucketReq, the request for the PutBucket operation |
resp | PutBucketResp, the return of the PutBucket operation |
PutBucketReq provides the following member functions:
// Define the ACL attribute of the bucket. Valid values: private, public-read-write, public-read
// Default value: private
void SetXCosAcl(const std::string& str);
// Grant read permission in the format: x-cos-grant-read: id=" ",id=" ".
// When you need to authorize a sub-account, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
// When you need to authorize a root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXCosGrantRead(const std::string& str);
// Grant write permission in the format: x-cos-grant-write: id=" ",id=" "./
// When you need to authorize a sub-account, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
// When you need to authorize a root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXCosGrantWrite(const std::string& str);
// Grant read-write permission in the format: x-cos-grant-full-control: id=" ",id=" ".
// When you need to authorize a sub-account, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
// When you need to authorize a root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXCosGrantFullControl(const std::string& str);
This API is used to check whether a bucket exists and you have permission to access it.
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);
// The call is successful. You can call the resp member functions to get the return content
if (result.IsSucc()) {
// ...
} else {
// You can call the CosResult member functions to output the error information, such as requestID
}
Parameter | Description |
---|---|
req | HeadBucketReq, the request for the HeadBucket operation |
resp | HeadBucketResp, the return of the HeadBucket operation |
This API is used to delete an empty bucket under a specified account.
CosResult DeleteBucket(const DeleteBucketReq& req, DeleteBucketResp* resp)
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
// The constructor of DeleteBucketReq requires bucket_name to be passed in
qcloud_cos::DeleteBucketReq req(bucket_name);
qcloud_cos::DeleteBucketResp resp;
qcloud_cos::CosResult result = cos.DeleteBucket(req, &resp);
// The call is successful. You can call the resp member functions to get the return content
if (result.IsSucc()) {
// ...
} else {
// You can call the CosResult member functions to output the error information, such as requestID
}
Parameter | Description |
---|---|
req | DeleteBucketReq, the request for the DeleteBucket operation |
resp | DeletBucketResp, the return of the DeletBucket operation |
This API is used to set the access control list (ACL) for a specified bucket.
CosResult PutBucketACL(const PutBucketACLReq& req, PutBucketACLResp* resp)
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
// The constructor of PutBucketACLReq requires bucket_name to be passed in
qcloud_cos::PutBucketACLReq req(bucket_name);
qcloud_cos::ACLRule 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://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::PutBucketACLResp resp;
qcloud_cos::CosResult result = cos.PutBucketACL(req, &resp);
// The call is successful. You can call the resp member functions to get the return content
if (result.IsSucc()) {
// ...
} else {
// Set the ACL. You can call the CosResult member functions to output the error information, such as requestID
}
Parameter | Description |
---|---|
req | PutBucketACLReq, the request for the PutBucketACL operation |
resp | PutBucketACLResp, the return of the PutBucketACL operation |
PutBucketACLReq provides the following member functions:
// Define the ACL attribute of the bucket. Valid values: private, public-read-write, public-read
// Default value: private
void SetXCosAcl(const std::string& str);
// Grant read permission in the format: x-cos-grant-read: id=" ",id=" ".
// When you need to authorize a sub-account, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
// When you need to authorize a root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXCosGrantRead(const std::string& str);
// Grant write permission in the format: x-cos-grant-write: id=" ",id=" "./
// When you need to authorize a sub-account, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
// When you need to authorize a root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXCosGrantWrite(const std::string& str);
// Grant read-write permission in the format: x-cos-grant-full-control: id=" ",id=" ".
// When you need to authorize a sub-account, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
// When you need to authorize a root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXCosGrantFullControl(const std::string& str);
// Bucket owner ID
void SetOwner(const Owner& owner);
// Set grantee and permission information
void SetAccessControlList(const std::vector<Grant>& grants);
// Add the permission information of a single bucket
void AddAccessControlList(const Grant& grant);
APIs such as
SetXCosAcl
,SetXCosGrantRead
,SetXCosGrantWrite
, andSetXCosGrantFullControl
cannot be used together withSetAccessControlList
orAddAccessControlList
at the same time. Because the former type is implemented by setting the HTTP header, while the latter is used for adding content in XML format to the body, you can choose only one type. The former type is preferred within the SDK.
ACLRule is defined as follows:
struct Grantee {
// The type can be RootAccount or SubAccount
// If the type is RootAccount, you can enter an account ID in the uin field or enter "anyone" (representing all types of users) in place of uin/<OwnerUin> and uin/<SubUin>
// If the type is RootAccount, uin represents the root account, while Subaccount represents the sub-account
std::string m_type;
std::string m_id; // qcs::cam::uin/<OwnerUin>:uin/<SubUin>
std::string m_display_name; // Optional
std::string m_uri;
};
struct Grant {
Grantee m_grantee; // Resource information of the grantee
std::string m_perm; // Specify the permission granted to the grantee. Enumerated values: READ, WRITE, FULL_CONTROL
};
This API is used to query the access control list (ACL) of a bucket.
CosResult GetBucketACL(const GetBucketACLReq& req, GetBucketACLResp* resp)
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
// The constructor of GetBucketACLReq requires bucket_name to be passed in
qcloud_cos::GetBucketACLReq req(bucket_name);
qcloud_cos::GetBucketACLResp resp;
qcloud_cos::CosResult result = cos.GetBucketACL(req, &resp);
// The call is successful. You can call the resp member functions to get the return content
if (result.IsSucc()) {
// ...
} else {
// Failed to get the ACL. You can call the CosResult member functions to output the error information, such as requestID
}
Parameter | Description |
---|---|
req | GetBucketACLReq, the request for the GetBucketACL operation |
resp | GetBucketACLResp, the return of the GetBucketACL operation |
GetBucketACLResp provides the following member functions:
std::string GetOwnerID();
std::string GetOwnerDisplayName();
std::vector<Grant> GetAccessControlList();
Was this page helpful?