Bucket Operations

Last updated: 2020-06-28 10:26:48

Introduction

This document provides an overview of APIs and SDK sample codes related to basic bucket operations and access control lists (ACL).

Basic Operations

API 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 permissions Checks whether a bucket exists and you have permission to access it
DELETE Bucket Deletes a bucket Deletes an empty bucket under a specified account

ACL

API Operation Description
PUT Bucket acl Setting bucket ACL Sets the ACL of a specified bucket
GET Bucket acl Querying bucket ACL Queries the ACL of a specified bucket

Basic operations

Querying a bucket list

Feature description

This API is used to query the list of all buckets under a particular account (i.e., the account being used to perform the request) or in a specified region. For more information, see GET Service.

Use case

Sample 1. Listing all buckets

cos.getService(function(err, data) {
    console.log(err || data);
});

Sample 2. Listing all buckets in a specified region

cos.getService({
    Region: 'COS_REGION',
}, function(err, data) {
    console.log(err || data);
});

Parameter Description

Parameter Name Description Type Required
Region Bucket region. For the enumerated values, see Regions and Access Domain Names String No

Callback function description

function(err, data) { ... }
Parameter Name Description Type
err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Headers returned by the request Object
data Data returned when the request is successful. If the request fails, this is null Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Headers returned by the request Object
- Owner Object representing the bucket owner Object
- - ID Complete ID of the bucket owner in the format: qcs::cam::uin/[OwnerUin]:uin/[OwnerUin], such as qcs::cam::uin/100000000001:uin/100000000001 string
- - - DisplayName Bucket owner name String
- Buckets Bucket List Object
Name ListBucketResult Bucket name in the format: <BucketName-APPID>, such as examplebucket-1250000000
- - Location Bucket region, such as ap-guangzhou,ap-beijing,ap-hongkong. For the enumerated values, see Regions and Access Domain Names String
CreationDate Time when the bucket was created, in ISO8601 format, such as 2016-11-09T08:46:32.000Z string

Creating a bucket

Feature description

This API is used to create a bucket under a specified account.

Use case

cos.putBucket({
    Bucket: 'examplebucket-1250000000',
    Region: 'COS_REGION'
}, function(err, data) {
    console.log(err || data);
});

Parameter Description

Parameter Name Description Type Required
Bucket Bucket name in the format: BucketName-APPID String Yes
Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
ACL Defines the access control list (ACL) attribute of the bucket. For enumerated values such as private and public-read, see the “Preset ACLs for buckets” section in ACL Overview. Default value: private Enum No
GrantRead Grants a user read permission in the format: id=" ",id=" ".
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String No
GrantWrite Grants a user write permission in the format: id=" ",id=" ".
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String No
GrantReadAcp Grants a user read permission for a bucket’s ACL and policies in the format: id=" ",id=" ".
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String No
GrantWriteAcp Grants a user write permission for a bucket’s ACL and policies in the format: id=" ",id=" ".
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String No
GrantFullControl Grants full permission in the format: id=" ",id=" ".
You can use a comma (,) to separate multiple users. To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String No

Callback function description

function(err, data) { ... }
Parameter Name Description Type
err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Headers returned by the request Object
data Data returned when the request is successful. If the request fails, this is null Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Headers returned by the request Object

Retrieving information on a bucket and its permissions

Feature description

This API is used to verify whether a bucket exists and you have permission to access it.

  • If the bucket exists and you have the permission to read it, HTTP status code 200 will be returned.
  • If you do not have the permission to read the bucket, HTTP status code 403 will be returned.
  • If the bucket does not exist, HTTP status code 404 will be returned.

Use case

cos.headBucket({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION', /*Required*/
}, function(err, data) {
    console.log(err || data);
});

Parameter Description

Parameter Name Description Type Required
Bucket Bucket name in the format: BucketName-APPID String Yes
Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes

Callback function description

function(err, data) { ... }
Parameter Name Description Type
err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Headers returned by the request Object
data Data returned when the request is successful. If the request fails, this is null Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Headers returned by the request Object

Deleting a bucket

Feature description

This API is used to delete an empty bucket under a specified account. Note that if the deletion is successful, HTTP status code 200 or 204 will be returned.

Before deleting a bucket, please make sure that all the data and incomplete multipart uploads in the bucket have been deleted; otherwise, the bucket cannot be deleted.

Use case

cos.deleteBucket({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION', /*Required*/
}, function(err, data) {
    console.log(err || data);
});

Parameter Description

Parameter Name Description Type Required
Bucket Bucket name in the format: BucketName-APPID String Yes
Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes

Callback function description

function(err, data) { ... }
Parameter Name Description Type
err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Headers returned by the request Object
data Data returned when the request is successful. If the request fails, this is null Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Headers returned by the request Object

ACL

Setting a bucket ACL

Feature description

This API is used to set the access control list (ACL) for a specified bucket.

Use case

Set a bucket to allow public-read:

cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION', /*Required*/
    ACL: 'public-read'
}, function(err, data) {
    console.log(err || data);
});

Grant a user full permission for a bucket:

cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION', /*Required*/
    GrantFullControl: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000011:uin/100000000011"' // 100000000001 is UIN
}, function(err, data) {
    console.log(err || data);
});

Modify bucket permission with AccessControlPolicy:

cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION', /*Required*/
    AccessControlPolicy: {
        "Owner": { // `Owner` is required in `AccessControlPolicy`
            "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 is the UIN of the bucket owner
        },
        "Grants": [{
            "Grantee": {
                "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 is UIN
            },
            "Permission": "WRITE"
        }]
    }
}, function(err, data) {
    console.log(err || data);
});

Parameter Description

Parameter Name Description Type Required
Bucket Bucket name in the format: BucketName-APPID String Yes
Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes
ACL Defines the access control list (ACL) attribute of the bucket. For the enumerated values such as private and public-read, see the “Preset ACL for buckets” section in ACL Overview. Default value: private Enum No
GrantRead Grants a user read permission in the format: id=" ",id=" ".
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String No
GrantWrite Grants a user write permission in the format: id=" ",id=" ".
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String No
GrantReadAcp Grants a user read permission for bucket ACL and policies in the format: id=" ",id=" ".
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String No
GrantWriteAcp Grants a user write permission for bucket ACL and policies in the format: id=" ",id=" ".
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String No
GrantFullControl Grants full permission in the format: id="[OwnerUin]".
You can use a comma (,) to separate multiple users.
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String No
AccessControlPolicy List of all the information on a CORS configuration Object No
- Owner Bucket owner information Object No
- - ID Complete ID of the bucket owner in the format: qcs::cam::uin/[OwnerUin]:uin/[OwnerUin],
such as `qcs::cam::uin/100000000001:uin/100000000001’, where 100000000001 is uin
String No
- Grants List of information on the authorized user and granted permissions ObjectArray No
- - Permission Permission granted to the authorized user. Valid values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL. For details on the enumerated values, see the Action permissions section in ACL Overview. String No
- - Grantee Authorized user information Object No
- - - ID Complete ID of the authorized user in the format: qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]
such as qcs::cam::uin/100000000001:uin/100000000001, where 100000000001 is uin
String No
- - - DisplayName Name of the authorized user, which is usually the same as the string you enter for ID String No
- - - URI Preset user groups, such as
http://cam.qcloud.com/groups/global/AllUsers or
http://cam.qcloud.com/groups/global/AuthenticatedUsers. For more information, see the preset user group section in [ACL Overview] (https://intl.cloud.tencent.com/document/product/436/30583).
String No

Callback function description

function(err, data) { ... }
Parameter Name Description Type
err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Headers returned by the request Object
data Data returned when the request is successful. If the request fails, this is null Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Headers returned by the request Object

Querying a bucket ACL

Feature description

This API is used to query the ACL of a specified bucket. To make this request, you need to have permission to access the ACL of the bucket.

Use case

cos.getBucketAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION', /*Required*/
}, function(err, data) {
    console.log(err || data);
});

Sample response

{
    "GrantFullControl": "",
    "GrantWrite": "",
    "GrantRead": "",
    "GrantReadAcp": "id=\"qcs::cam::uin/100000000011:uin/100000000011\"",
    "GrantWriteAcp": "id=\"qcs::cam::uin/100000000011:uin/100000000011\"",
    "ACL": "private",
    "Owner": {
        "ID": "qcs::cam::uin/100000000001:uin/100000000001",
        "DisplayName": "qcs::cam::uin/100000000001:uin/100000000001"
    },
    "Grants": [{
        "Grantee": {
            "ID": "qcs::cam::uin/100000000011:uin/100000000011",
            "DisplayName": "qcs::cam::uin/100000000011:uin/100000000011"
        },
        "Permission": "READ"
    }],
    "statusCode": 200,
    "headers": {}
}

Parameter Description

Parameter Name Description Type Required
Bucket Bucket name in the format: BucketName-APPID String Yes
Region Bucket region. For the enumerated values, see Regions and Access Domain Names String Yes

Callback function description

function(err, data) { ... }
Parameter Name Description Type
err Object returned when an error (network error or service error) occurs. If the request is successful, this is null. For more information, see Error Codes Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Headers returned by the request Object
data Data returned when the request is successful. If the request fails, this is null Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Headers returned by the request Object
- ACL Defines the access control list (ACL) attribute of the bucket. For the enumerated values such as private and public-read, see the “Preset ACL for buckets” section in ACL Overview. Default value: private Enum
- GrantRead ID of the authorized user with read permission String
- GrantWrite ID of the authorized user with write permission String
- GrantReadAcp ID of the authorized user with read permission for bucket ACL and policies String
- GrantWriteAcp ID of the authorized user with write permission for bucket ACL and policies String
- GrantFullControl ID of the authorized user granted full permission String
- Owner Bucket owner information Object
- - - DisplayName Bucket owner name String
- - - ID Bucket owner ID in the format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>.
For root accounts, <OwnerUin> and <SubUin> have the same value
String
- Grants List of information on the authorized user and granted permissions ObjectArray
- - Permission Specifies the permission granted to the authorized user. Enumerated values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL String
- - Grantee Authorized user information Object
- - - DisplayName Name of the authorized user String
- - - ID Complete ID of the authorized user
For root accounts, the format is qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>
or qcs::cam::anyone:anyone representing all users.
For sub-accounts, the format is qcs::cam::uin/<OwnerUin>:uin/<SubUin>
String
- - - URI Preset user groups, such as
http://cam.qcloud.com/groups/global/AllUsers or
http://cam.qcloud.com/groups/global/AuthenticatedUsers. For more information, see the preset user group section in [ACL Overview] (https://intl.cloud.tencent.com/document/product/436/30583).
String

Was this page helpful?

Was this page helpful?

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