How to list buckets by using OSS SDK for Go 2.0 - Object Storage Service

This topic describes how to list buckets that belong to the current Alibaba Cloud account in all regions and meet specific conditions.

Usage notes

The sample code in this topic uses the region ID cn-hangzhou of the China (Hangzhou) region. By default, the public endpoint is used to access resources in a bucket. If you want to access resources in the bucket by using other Alibaba Cloud services in the same region in which the bucket is located, use the internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.
In this topic, access credentials are obtained from environment variables. For more information about how to configure the access credentials, see Configure access credentials.
To list buckets, you must have the oss:ListBuckets permission. For more information, see Attach a custom policy to a RAM user.

Method

Use the advanced API operation to list buckets

Important

OSS SDK for Go 2.0 provides a paginator that supports automatic pagination. If you call an API operation multiple times, OSS SDK for Go V2 automatically obtains the results of the next page. When you use the paginator, you need to only compile the code that is used to process the results.
The paginator contains an object in the <OperationName>Paginator format and the paginator creation method in the New<OperationName>Paginator format. The paginator creation method returns a paginator object that implements the HasNext and NextPage methods. The HasNext method is used to determine whether more pages exist and the NextPage method is used to call an API operation to obtain the next page.

Syntax:

type ListBucketsPaginator struct

func (c *Client) NewListBucketsPaginator(request *ListBucketsRequest, optFns ...func(*PaginatorOptions)) *ListBucketsPaginator

func (p *ListBucketsPaginator) HasNext() bool

func (p *ListBucketsPaginator) NextPage(ctx context.Context, optFns ...func(*Options)) (*<OperationName>Result, error)

Request parameters

Parameter	Type	Description
request	*ListBucketsRequest	The parameters of a specific API operation. For more information, visit ListBucketsRequest.
optFns	...func(*PaginatorOptions)	Optional. The operation-level parameter. For more information, visit PaginatorOptions.

Response parameters

Parameter	Description
*ListBucketsPaginator	The paginator object that implements the HasNext and NextPage methods. The HasNext method is used to determine whether more pages exist and the NextPage method is used to call an API operation to obtain the next page.

Use the basic API operation to list buckets

func (c *Client) ListBuckets(ctx context.Context, request *ListBucketsRequest, optFns ...func(*Options)) (*ListBucketsResult, error)

Request parameters

Parameter	Type	Description
ctx	context.Context	The context of the request, which can be used to specify the total duration of the request.
request	*ListBucketsRequest	The parameters of a specific API operation. For more information, visit ListBucketsRequest.
optFns	...func(*Options)	Optional. The operation-level parameter. For more information, visit Options.

Response parameters

Parameter	Type	Description
result	*ListBucketsResult	The response to the operation. This parameter is valid when the value of err is nil. For more information, visit ListBucketsResult.
err	error	The status of the request. If the request fails, the value of err cannot be nil.

Examples

Use the advanced API operation to list buckets

The following sample code provides an example on how to list buckets in all regions within the current Alibaba Cloud account:

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Specify the global variables.
var (
	region string // The region.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Check whether the region is empty.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSSClient instance.
	client := oss.NewClient(cfg)

	// Create a request to list buckets.
	request := &oss.ListBucketsRequest{}

	// Specify a function to handle PaginatorOptions.
	modifyOptions := func(opts *oss.PaginatorOptions) {
		// Modify the value of opts based on your business requirements. For example, you can specify the maximum number of buckets that can be listed per page.
		// For example, "opts.Limit = 5" specifies that up to five buckets are listed per page.
		opts.Limit = 5
	}

	// Create a paginator.
	p := client.NewListBucketsPaginator(request, modifyOptions)

	var i int
	log.Println("Buckets:")

	// Traverse each page in the paginator.
	for p.HasNext() {
		i++

		// Obtain the data of the next page.
		page, err := p.NextPage(context.TODO())
		if err != nil {
			log.Fatalf("failed to get page %v, %v", i, err)
		}

		// Display information about each bucket on the page.
		for _, b := range page.Buckets {
			log.Printf("Bucket: %v, StorageClass: %v, Location: %v\n", oss.ToString(b.Name), oss.ToString(b.StorageClass), oss.ToString(b.Location))
		}
	}
}

Use the basic API operation to list buckets

The following sample code provides an example on how to list buckets in all regions within the current Alibaba Cloud account:

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Specify the global variables.
var (
	region string // The region.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Check whether the region is empty.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSSClient instance.
	client := oss.NewClient(cfg)

	var marker string = ""

	// Create a ListBucketsRequest request.
	request := &oss.ListBucketsRequest{
		Prefix:  oss.Ptr(""),
		MaxKeys: 10,
		Marker:  &marker,
	}

	// List the buckets in all regions within the current Alibaba Cloud account.
	for {
		lsRes, err := client.ListBuckets(context.TODO(), request)
		if err != nil {
			log.Fatalf("Failed to list buckets: %v", err)
		}

		for _, bucket := range lsRes.Buckets {
			log.Printf("Bucket: %s", *bucket.Name)
		}

		if !lsRes.IsTruncated {
			break
		}
		marker = *lsRes.NextMarker
	}

	log.Println("List buckets successfully!")
}

Common scenarios

List buckets whose names contain a specific prefix

Use a paginator

The following sample code provides an example on how to list buckets whose names contain the example prefix in all regions within the current Alibaba Cloud account:

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Specify the global variables.
var (
	region string // The region.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Check whether the region is empty.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSSClient instance.
	client := oss.NewClient(cfg)

	// Create a request to list buckets.
	request := &oss.ListBucketsRequest{
		Prefix: oss.Ptr("example"), // Set the prefix to example. Only buckets whose names contain the prefix are listed.
	}

	// Create a paginator.
	p := client.NewListBucketsPaginator(request)

	var i int
	log.Println("Buckets:")

	// Traverse each page in the paginator.
	for p.HasNext() {
		i++

		// Obtain the data of the next page.
		page, err := p.NextPage(context.TODO())
		if err != nil {
			log.Fatalf("failed to get page %v, %v", i, err)
		}

		// Display information about each bucket on the page.
		for _, b := range page.Buckets {
			log.Printf("Bucket: %v, StorageClass: %v, Location: %v\n", oss.ToString(b.Name), oss.ToString(b.StorageClass), oss.ToString(b.Location))
		}
	}
}

Call ListBuckets

The following sample code provides an example on how to list buckets whose names contain the example prefix in all regions within the current Alibaba Cloud account:

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Specify the global variables.
var (
	region string // The region.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Check whether the region is empty.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSSClient instance.
	client := oss.NewClient(cfg)

	var marker string = ""

	// Create a ListBucketsRequest request.
	request := &oss.ListBucketsRequest{
		Prefix:  oss.Ptr("example"),
		MaxKeys: 10,
		Marker:  &marker,
	}

	// List the buckets in all regions within the current Alibaba Cloud account.
	for {
		lsRes, err := client.ListBuckets(context.TODO(), request)
		if err != nil {
			log.Fatalf("Failed to list buckets: %v", err)
		}

		for _, bucket := range lsRes.Buckets {
			log.Printf("Bucket: %s", *bucket.Name)
		}

		if !lsRes.IsTruncated {
			break
		}
		marker = *lsRes.NextMarker
	}

	log.Println("List buckets successfully!")
}

List buckets whose names are alphabetically after the bucket specified by marker

Use a paginator

The following sample code provides an example on how to list buckets whose names are alphabetically after the example-bucket bucket in all regions within the current Alibaba Cloud account:

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Specify the global variables.
var (
	region string // The region.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Check whether the region is empty.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSSClient instance.
	client := oss.NewClient(cfg)

	// Create a request to list buckets.
	request := &oss.ListBucketsRequest{
		Marker: oss.Ptr("example-bucket"), // Set marker to example-bucket and list buckets whose names are alphabetically after the example-bucket bucket.
	}

	// Create a paginator.
	p := client.NewListBucketsPaginator(request)

	var i int
	log.Println("Buckets:")

	// Traverse each page in the paginator.
	for p.HasNext() {
		i++

		// Obtain the data of the next page.
		page, err := p.NextPage(context.TODO())
		if err != nil {
			log.Fatalf("failed to get page %v, %v", i, err)
		}

		// Display information about each bucket on the page.
		for _, b := range page.Buckets {
			log.Printf("Bucket: %v, StorageClass: %v, Location: %v\n", oss.ToString(b.Name), oss.ToString(b.StorageClass), oss.ToString(b.Location))
		}
	}
}

Call ListBuckets

The following sample code provides an example on how to list buckets whose names are alphabetically after the example-bucket bucket in all regions within the current Alibaba Cloud account:

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Specify the global variables.
var (
	region string // The region.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Check whether the region is empty.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSSClient instance.
	client := oss.NewClient(cfg)

	var marker string = "example-bucket"

	// Create a ListBucketsRequest request.
	request := &oss.ListBucketsRequest{
		Marker: &marker,
	}

	// List the buckets in all regions within the current Alibaba Cloud account.
	for {
		lsRes, err := client.ListBuckets(context.TODO(), request)
		if err != nil {
			log.Fatalf("Failed to list buckets: %v", err)
		}

		for _, bucket := range lsRes.Buckets {
			log.Printf("Bucket: %s", *bucket.Name)
		}

		if !lsRes.IsTruncated {
			break
		}
		marker = *lsRes.NextMarker
	}

	log.Println("List buckets successfully!")
}

List a specific number of buckets

Call ListBuckets

The following sample code provides an example on how to list buckets in all regions within the current Alibaba Cloud account and specify the maximum number of buckets that can be listed per page for a list operation:

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Specify the global variables.
var (
	region string // The region.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Check whether the region is empty.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSSClient instance.
	client := oss.NewClient(cfg)

	var marker string = ""

	// Create a ListBucketsRequest request.
	request := &oss.ListBucketsRequest{
		Marker:  &marker,
		MaxKeys: 10, // Set the maximum number of buckets that can be listed per page for a list operation to 10.
	}

	// List the buckets in all regions within the current Alibaba Cloud account.
	for {
		lsRes, err := client.ListBuckets(context.TODO(), request)
		if err != nil {
			log.Fatalf("Failed to list buckets: %v", err)
		}

		for _, bucket := range lsRes.Buckets {
			log.Printf("Bucket: %s", *bucket.Name)
		}

		if !lsRes.IsTruncated {
			break
		}
		marker = *lsRes.NextMarker
	}

	log.Println("List buckets successfully!")
}

References

For the sample code that is used to list buckets, visit GitHub.
For more information about the advanced API operation that you can call to list buckets, visit NewListBucketsPaginator.
For more information about the basic API operation that you can call to list buckets, visit ListBuckets.
For more information about the Uploader, see Developer Guide.