Bucket Management

Overview

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

Basic operations

ACL

Basic Operations

Querying Bucket List

Feature Description

This API is used to query the list of all buckets under the specified account.

Method Prototype

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

Sample Request

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

Return Result Descriptions

The result of the request 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                                               
} 

Creating a Bucket

Feature Description

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

Method Prototype

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

Sample Request

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

Parameter Descriptions

type BucketPutOptions struct {
    XCosACL              string 
    XCosGrantRead        string  
    XCosGrantWrite       string  
    XCosGrantFullControl string 
}

Checking a Bucket and Its Permission

Feature Description

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

Method Prototype

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

Sample Request

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

Deleting a Bucket

Feature Description

This API is used to delete an empty bucket under the specified account.

Method Prototype

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

Sample Request

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

ACL

Setting Bucket ACL

Feature Description

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

Method Prototype

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

Sample Request

// 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: "RootAccount",
                    ID:"qcs::cam::uin/100000760461:uin/100000760461",
                },
                Permission: "FULL_CONTROL",
            },
        },
    },
}
resp, err := client.Bucket.PutACL(context.Background(), opt)

Parameter Descriptions

type ACLHeaderOptions struct {
    XCosACL              string 
    XCosGrantRead        string 
    XCosGrantWrite       string 
    XCosGrantFullControl string 
}

Querying Bucket ACL

Feature Description

This API (GET Bucket acl) is used to query the access control list (ACL) for the specified bucket.

Method Prototype

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

Sample Request

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

Return Result Descriptions

The result of the request 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 
}