Actions on Buckets

Last updated: 2019-12-23 21:18:03

PDF

Note

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

Basic Operations

API Operation name pedagogical operation
GET Service Query Bucket list Query all Bucket lists under the specified account
PUT Bucket Create Bucket Create a Bucket under the specified account
HEAD Bucket Retrieval of Bucket and its Permission Retrieve whether Bucket exists and whether Permission Access
DELETE Bucket Deleting Buckets Delete the empty Bucket under the specified account

Access control list

API Operation name pedagogical operation
PUT Bucket acl Setting Bucket ACL Set the ACL configuration for Bucket
GET Bucket acl Query Bucket ACL Query Bucket's ACL configuration

Basic Operations

Query Bucket list

Function description

Query all Bucket lists under the specified account.

Method prototype

func (s *ServiceService) Get(ctx context.Context) (*ServiceGetResult, *Response, error)

Request Sample

s, resp, err := c.Service.Get(context.Background()) 

Return result description

Request result is returned through GetServiceResult.

type ServiceGetResult struct {
    Owner   *Owner  
    Buckets []Bucket 
}
type Owner struct {
    ID          string 
    DisplayName string                                              
}
type Bucket struct {
    Name       string
    Region     string
    CreationDate string                                               
} 
Parameter name Parameter description Type
Id ID of the Bucket owner String
DisplayName Name information for the Bucket owner String
Name Name of Bucket String
Region Bucket region String
CreationDate Bucket creation time. ISO8601 format, such as 2016-11-09T08:46:32.000Z String

Create Bucket

Function description

Create a Bucket under the specified account.

Method prototype

func (s *BucketService) Put(ctx context.Context, opt *BucketPutOptions) (*Response, error)

Request Sample

opt := &cos.BucketPutOptions{
    XCosACL: "public-read",
}
resp, err := client.Bucket.Put(context.Background(), opt)

Parameter description

type BucketPutOptions struct {
    XCosACL              string 
    XCosGrantRead        string  
    XCosGrantWrite       string  
    XCosGrantFullControl string 
}
Parameter name Parameter description Type Required
XCosACL Set the ACL, of Bucket, such as private,public-read,public-read-write String No
XCosGrantFullControl Grants the specified account read and write Permission to Bucket. The format is id=" ",id=" " When authorization is required for a subaccount, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}" When authorization is required for the main account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}" For example id="qcs::cam::uin/100000000001:uin/100000000011",id="qcs::cam::uin/100000000001:uin/100000000001" String No
XCosGrantRead Grants the specified account read Permission to Bucket. The format is id=" ",id=" " When authorization is required for a subaccount, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}" When authorization is required for the main account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}" For example id="qcs::cam::uin/100000000001:uin/100000000011",id="qcs::cam::uin/100000000001:uin/100000000001" String No
XCosGrantWrite Grants the specified account write Permission to Bucket. The format is id=" ",id=" " When authorization is required for a subaccount, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}" When authorization is required for the main account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}" For example id="qcs::cam::uin/100000000001:uin/100000000011",id="qcs::cam::uin/100000000001:uin/100000000001" String No

Retrieval of Bucket and its Permission

Function description

Retrieves whether Bucket exists and has Permission Access.

Method prototype

func (s *BucketService) Head(ctx context.Context) (*Response, error)

Request Sample

resp, err := client.Bucket.Head(context.Background())

Deleting Buckets

Function description

Deletes the empty Bucket under the specified account.

Method prototype

func (s *BucketService) Delete(ctx context.Context) (*Response, error)

Request Sample

resp, err := client.Bucket.Delete(context.Background())

Access control list

Setting Bucket ACL

Function description

Sets the specified Bucket Access Permission control list (PUT Bucket acl).

Method prototype

func (s *BucketService) PutACL(ctx context.Context, opt *BucketPutACLOptions) (*Response, error)

Request Sample

// 1. Set Bucket ACL by header.
opt := &cos.BucketPutACLOptions{
    Header: &cos.ACLHeaderOptions{
        //private,public-read,public-read-write
        XCosACL: "private",
    },
}
resp, err := client.Bucket.PutACL(context.Background(), opt)

// 2. Set Bucket ACL by body.
opt := &cos.BucketPutACLOptions{
    Body: &cos.ACLXml{
        Owner: &cos.Owner{
            ID: "qcs::cam::uin/100000760461:uin/100000760461",
        },
        AccessControlList: []cos.ACLGrant{
            {
                Grantee: &cos.ACLGrantee{
            // Type can also chose the "Group", "CanonicalUser"
                    Type: "RootAccount",
                    ID:"qcs::cam::uin/100000760461:uin/100000760461",
                },
        // Permission can also chose the "WRITE","FULL_CONTROL" 
                Permission: "FULL_CONTROL",
            },
        },
    },
}
resp, err := client.Bucket.PutACL(context.Background(), opt)

Parameter description

type ACLHeaderOptions struct {
    XCosACL              string 
    XCosGrantRead        string 
    XCosGrantWrite       string 
    XCosGrantFullControl string 
}
Parameter name Parameter description Type Required
XCosACL Set the ACL, of Bucket, such as private,public-read,public-read-write String No
XCosGrantFullControl Grants the specified account read and write Permission to Bucket. The format is id=" ",id=" " When authorization is required for a subaccount, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}" When authorization is required for the main account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}" For example id="qcs::cam::uin/100000000001:uin/100000000011",id="qcs::cam::uin/100000000001:uin/100000000001" String No
XCosGrantRead Grants the specified account read Permission to Bucket. The format is id=" ",id=" " When authorization is required for a subaccount, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}" When authorization is required for the main account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}" For example id="qcs::cam::uin/100000000001:uin/100000000011",id="qcs::cam::uin/100000000001:uin/100000000001" String No
XCosGrantWrite Grants the specified account write Permission to Bucket. The format is id=" ",id=" " When authorization is required for a subaccount, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}" When authorization is required for the main account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}" For example id="qcs::cam::uin/100000000001:uin/100000000011",id="qcs::cam::uin/100000000001:uin/100000000001" String No
ACLXML Endow the specified account with Access and Permission to Bucket, as described in the GET Bucket acl return result Struct No

Query Bucket ACL

Function description

Query the Access Permission control list (GET Bucket acl) for the specified Bucket.

Method prototype

func (s *BucketService) GetACL(ctx context.Context) (*BucketGetACLResult, *Response, error)

Request Sample

v, resp, err := client.Bucket.GetACL(context.Background())

Return result description

Request result is returned through GetBucketACLResult.

type ACLXml struct {
    Owner             *Owner
    AccessControlList []ACLGrant 
}
type Owner struct { 
    ID          string 
    DisplayName string
}
type ACLGrant struct {
    Grantee    *ACLGrantee
    Permission string
}
type ACLGrantee struct {
    Type        string 
    ID          string 
    DisplayName string
    UIN         string 
}
Parameter name Parameter description Type
Owner Information about Bucket owners, including DisplayName and ID Struct
AccessControlList Information on Bucket Permission grantees, including Grantee and Permission Struct
Grantee Information about Permission grantees, including DisplayName,Type,ID and UIN Struct
Type Type of Permission grantee, type CanonicalUser or Group String
Id When Type is CanonicalUser, the ID corresponding to the Permission grantor String
DisplayName The name of the Permission grantee String
Uin When Type is Group, the UIN corresponding to the Permission grantor String
Permission The grantee has the Permission of Bucket, the optional values are FULL_CONTROL,WRITE,READ, corresponding to read and write Permission, write Permission, read Permission respectively String