Actions on Buckets

Last updated: 2020-03-13 20:43:17

PDF

Introduction

This document provides an overview of APIs and SDK code samples related to basic operations on buckets and bucket access control list (ACL).

Basic Operations

API Operation Description
HEAD Bucket Retrieving information on a bucket and its permission Checks whether a bucket exists and if you have the permission to access it
DELETE Bucket Deleting a bucket Deletes an empty bucket under a specified account

ACL

API 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 specified bucket

Basic Operations

Retrieving Information on a Bucket and Its Permission

Feature Description

This API (HEAD Bucket) is used to verify whether a bucket exists and if you have the permission to access it.

  • An HTTP status code 200 will be returned if the bucket exists and you have access permissions.
  • An HTTP status code 403 will be returned if you do not have the permission to access the bucket.
  • HTTP status code 404 will be returned if the bucket does not exist.

Samples

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

Parameter Description

Parameter Name Description Type Required
Bucket Bucket name in the format of 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 Header information returned by the request Object
data Object returned when the request succeeds. If the request fails, this will be empty Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Header information returned by the request Object

Deleting a Bucket

Feature Description

This API (DELETE Bucket) is used to delete an empty bucket under a specified account. If the deletion succeeds, 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.

Samples

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

Parameter Description

Parameter Name Description Type Required
Bucket Bucket name in the format of 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 Header information returned by the request Object
data Object returned when the request succeeds. If the request fails, this will be empty Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Header information returned by the request Object

ACL

Setting Bucket ACL

Feature Description

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

Samples

Set a bucket to allow public-read:

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

Grant a user full access to a bucket:

cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket 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',     /* Bucket 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 is in the format of BucketName-APPID. The bucket name entered here must be in this format 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” section in ACL Overview. Default value: private String No
GrantRead Grants the user read access in the format of id="[OwnerUin]".
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
GrantWrite Grants the user write access in the format of id="[OwnerUin]".
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
GrantReadAcp Grants the user read access to ACL and policies in the format of id="[OwnerUin]".
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
GrantWriteAcp Grants the user write access to ACL and policies in the format of id="[OwnerUin]".
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
GrantFullControl Grants the user full access in the format of id="[OwnerUin]".
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 CORS configuration Object No
- Owner Object representing the bucket owner Object No
- - ID String representing the user ID in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]
E.g., qcs::cam::uin/100000000001:uin/100000000001, where 100000000001 is UIN
Object No
- Grants List of information on the authorized user and granted permissions ObjectArray No
- - Permission Permissions information. Valid values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL. For details on the enumerated values, see the “Actions permissions” section in ACL Overview. String No
- - Grantee Information of the authorized user Object No
- - - ID String representing the user ID in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]
E.g., qcs::cam::uin/100000000001:uin/100000000001, where 100000000001 is UIN
Object No
- - - DisplayName String representing the username, which is usually the same as the string you enter for ID String No
- - - URI Preset user group. See the section on preset user groups in ACL Overview. E.g., http://cam.qcloud.com/groups/global/AllUsers or http://cam.qcloud.com/groups/global/AuthenticatedUsers 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 Header information returned by the request Object
data Object returned when the request succeeds. If the request fails, this will be empty Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Header information returned by the request Object

Querying Bucket ACL

Feature Description

This API (GET Bucket ACL) is used to get the ACL of the specified bucket. To make this request, you need to have the permission to access the ACL of the bucket.

Samples

cos.getBucketAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket 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 of 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 Header information returned by the request Object
data Object returned when the request succeeds. If the request fails, this will be empty Object
- statusCode HTTP status code returned by the request, such as 200, 403, and 404 Number
- headers Header information 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” section in ACL Overview. Default value: private String
- GrantRead ID information of the user granted read access String
- GrantWrite ID information of the user granted write access String
- GrantReadAcp ID information of the user granted read access to the ACL and Policies String
- GrantWriteAcp ID information of the user granted write access to the ACL and Policies String
- GrantFullControl ID information of the user granted full access String
- Owner Bucket owner information Object
- - DisplayName Bucket owner username String
- - ID Bucket owner ID
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 user. Enumerated values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL String
- - Grantee Authorized user information Object
- - - DisplayName Authorized user username String
- - - ID User 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 group. See the section on preset user groups in ACL Overview. E.g., http://cam.qcloud.com/groups/global/AllUsers or http://cam.qcloud.com/groups/global/AuthenticatedUsers String