How to list buckets by using Go SDK V2 - Object Storage Service

This topic describes how to list buckets that meet specified conditions in all regions of your account.

Precautions

The sample code in this topic uses the China (Hangzhou) region ID cn-hangzhou as an example. By default, the public endpoint is used. If you want to access OSS from other Alibaba Cloud services within the same region, use the internal endpoint. For more information about the mappings between OSS regions and endpoints, see OSS regions and endpoints.
The examples in this topic demonstrate how to read access credentials from environment variables. For more information about how to configure access credentials, see Configure access credentials.
To list buckets, you must have the oss:ListBuckets permission. For more information, see Grant custom permissions to a RAM user.
When you use an SDK to list buckets, you can specify a resource group ID to filter buckets in a specific resource group.
- By default, the resource group ID parameter is not included when you use an SDK to list buckets. As a result, the XML response does not contain resource group information.
- If you include the resource group ID parameter in the request, OSS returns all buckets that belong to the resource group.
- If you do not include the resource group ID parameter in the request, OSS returns all buckets that the requester owns.

Method definition

API operation for listing buckets (Premium Edition)

Important

For frequent list operations, Go SDK V2 provides a paginator that supports automatic paging. The paginator automatically retrieves results from subsequent pages, so you only need to write the code to process the results.
A paginator consists of a paginator object, <OperationName>Paginator, and a paginator creation method, New<OperationName>Paginator. The creation method returns a paginator object that implements the HasNext and NextPage methods. You can use these methods to determine whether more pages exist and to call the operation to retrieve the next page.

The following code shows the definition of the operation for listing buckets:

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 request parameters of the operation. For more information, see ListBucketsRequest
optFns	...func(*PaginatorOptions)	(Optional) The operation-level configuration parameters. For more information, see PaginatorOptions

Return values

Return value	Description
*ListBucketsPaginator	The paginator object. This object implements the HasNext and NextPage methods, which are used to determine whether more pages exist and call the operation to retrieve the next page.

API operation for listing buckets (Basic Edition)

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 a request. You can use this parameter to set the timeout period for a request.
request	*ListBucketsRequest	The request parameters of the operation. For more information, see ListBucketsRequest
optFns	...func(*Options)	(Optional) The operation-level configuration parameters. For more information, see Options

Return values

Return value	Type	Description
result	*ListBucketsResult	The return value of the operation. This parameter is valid only when err is nil. For more information, see ListBucketsResult
err	error	The status of the request. If the request fails, err is not nil.

Sample code

List buckets using the API operation of the Premium Edition

You can use the following code to list all buckets in all regions of your 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"
)

// Define global variables
var (
	region string // The region where the bucket is stored
)

// The init function is 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 set the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

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

	// 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)
		}

		// Print the information of 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))
		}
	}

}

List buckets using the API operation of the Basic Edition

You can use the following code to list all buckets in all regions of your 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"
)

// Define global variables
var (
	region string // The region where the bucket is stored
)

// The init function is 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 set the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

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

	// List all buckets in all regions of the current 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
		}
		request.Marker = lsRes.NextMarker
	}

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

Common scenarios

List buckets with a specified prefix

Use a Paginator

You can use the following code to list buckets whose names have the prefix `example` in all regions of your 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"
)

// Define global variables
var (
	region string // The region where the bucket is stored
)

// The init function is 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 set the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSS client
	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 start with this 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)
		}

		// Print the information of 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 ListBuckets

You can use the following code to list buckets whose names have the prefix `example` in all regions of your 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"
)

// Define global variables
var (
	region string // The region where the bucket is stored
)

// The init function is 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 set the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

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

	// List all buckets in all regions of the current 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
		}
		request.Marker = lsRes.NextMarker
	}

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

List buckets that are after a specified marker

Use a Paginator

You can use the following code to list buckets whose names are alphabetically after `example-bucket` in all regions of your 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"
)

// Define global variables
var (
	region string // The region where the bucket is stored
)

// The init function is 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 set the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Create a request to list buckets
	request := &oss.ListBucketsRequest{
		Marker: oss.Ptr("example-bucket"), // Set the marker to "example-bucket". The list operation starts from this marker.
	}

	// 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)
		}

		// Print the information of 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 ListBuckets

You can use the following code to list buckets whose names are alphabetically after `example-bucket` in all regions of your 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"
)

// Define global variables
var (
	region string // The region where the bucket is stored
)

// The init function is 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 set the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	var marker string = "example-bucket"

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

	// List all buckets in all regions of the current 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
		}
		request.Marker = lsRes.NextMarker
	}

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

List a specified number of buckets

Use a Paginator

You can use the following code to list buckets in all regions of your account and specify the maximum number of buckets to return for each page.

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"
)

// Define global variables
var (
	region string // The region where the bucket is stored
)

// The init function is 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 set the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Create a request to list buckets
	request := &oss.ListBucketsRequest{
		MaxKeys: 5, // Set the number of buckets to return for each page to 5.
	}

	// 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)
		}

		// Print the information of 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 ListBuckets

You can use the following code to list buckets in all regions of your account and specify the maximum number of buckets to return for each page.

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"
)

// Define global variables
var (
	region string // The region where the bucket is stored
)

// The init function is 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 set the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Create a ListBucketsRequest request
	request := &oss.ListBucketsRequest{
		MaxKeys: 10, // The maximum number of buckets to return for each list operation.
	}

	// List all buckets in all regions of the current 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
		}
		request.Marker = lsRes.NextMarker
	}

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

List all buckets in a specified resource group

Use a Paginator

If you specify the resource group ID ResourceGroupId in the request parameters, OSS returns all buckets that belong to the resource group.
If you do not specify the resource group ID ResourceGroupId in the request parameters, OSS returns all buckets that the requester owns.

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"
)

// Define global variables
var (
	region string // The region where the bucket is stored
)

// The init function is 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 set the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Create a request to list buckets
	request := &oss.ListBucketsRequest{
		ResourceGroupId: oss.Ptr("rg-aek27tc********"), // List buckets in the specified resource group.
	}

	// 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)
		}

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

}

Use ListBuckets

If you specify the resource group ID ResourceGroupId in the request parameters, OSS returns all buckets that belong to the resource group.
If you do not specify the resource group ID ResourceGroupId in the request parameters, OSS returns all buckets that the requester owns.

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"
)

// Define global variables
var (
	region string // The region where the bucket is stored
)

// The init function is 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 set the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

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

	// Create a ListBucketsRequest request
	request := &oss.ListBucketsRequest{
		MaxKeys:         10,
		ResourceGroupId: oss.Ptr("rg-aek27tc********"), // List buckets in the specified resource group.
	}

	// List all buckets in all regions of the current 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, StorageClass: %v, Location: %v, ResourceGroupId: %v\n", oss.ToString(bucket.Name), oss.ToString(bucket.StorageClass), oss.ToString(bucket.Location), oss.ToString(bucket.ResourceGroupId))
		}

		if !lsRes.IsTruncated {
			break
		}
		request.Marker = lsRes.NextMarker
	}

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

References

For the complete sample code for listing buckets, see GitHub example.
For more information about the API operation for listing buckets (Premium Edition), see NewListBucketsPaginator.
For more information about the API operation for listing buckets (Basic Edition), see ListBuckets.
For more information about paginators, see Developer Guide.