List buckets with filtering conditions using Go SDK V2 - Object Storage Service

Use ListBuckets to query all buckets in your account, with optional filters for prefix, marker, page size, and resource group. For a complete runnable project, see the GitHub example.

Prerequisites

Before you begin, make sure you have:

The oss:ListBuckets permission. For details, see Grant custom permissions to a RAM user.
Access credentials configured as environment variables. For details, see Configure access credentials.

The examples on this page use the cn-hangzhou region and connect via the public endpoint. To access OSS from another Alibaba Cloud service in the same region, use the internal endpoint instead. For endpoint mappings, see OSS regions and endpoints.

Choose an API

Go SDK V2 provides two ways to call ListBuckets:

API	When to use
Paginator (`NewListBucketsPaginator`)	Iterating over all results automatically. The paginator handles pagination-token tracking so you only write the result-processing logic.
Direct call (`ListBuckets`)	Fetching a single page, or when you need fine-grained control over each request.

All examples below share the same client setup:

cfg := oss.LoadDefaultConfig().
    WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
    WithRegion(region)

client := oss.NewClient(cfg)

Method definitions

Paginator

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)

Parameters

Parameter	Type	Description
`request`	`*ListBucketsRequest`	Request parameters. See ListBucketsRequest.
`optFns`	`...func(*PaginatorOptions)`	(Optional) Operation-level configuration. See PaginatorOptions.

Return value

Return value	Description
`*ListBucketsPaginator`	Paginator object implementing `HasNext` and `NextPage`. Call `HasNext` to check whether more pages exist, then call `NextPage` to retrieve the next page.

Direct call

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

Parameters

Parameter	Type	Description
`ctx`	`context.Context`	Request context, used to set the timeout.
`request`	`*ListBucketsRequest`	Request parameters. See ListBucketsRequest.
`optFns`	`...func(*Options)`	(Optional) Operation-level configuration. See Options.

Return values

Return value	Type	Description
`result`	`*ListBucketsResult`	List result. Valid only when `err` is `nil`. See ListBucketsResult.
`err`	`error`	`nil` if the request succeeds.

Examples

List all buckets

Using the paginator

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

var (
	region string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
}

func main() {
	flag.Parse()

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg)

	request := &oss.ListBucketsRequest{}

	p := client.NewListBucketsPaginator(request)

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

	for p.HasNext() {
		i++

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

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

Using ListBuckets

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

var (
	region string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
}

func main() {
	flag.Parse()

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg)

	request := &oss.ListBucketsRequest{}

	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

All scenario examples share the same client setup as above. Only the ListBucketsRequest fields differ.

Filter by prefix

Returns only buckets whose names start with the specified prefix.

Using the paginator

request := &oss.ListBucketsRequest{
    Prefix: oss.Ptr("example"), // Only buckets whose names start with "example" are returned.
}

p := client.NewListBucketsPaginator(request)

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

for p.HasNext() {
    i++

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

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

Using ListBuckets

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

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

Start from a marker

Returns only buckets whose names are alphabetically after the specified marker.

Using the paginator

request := &oss.ListBucketsRequest{
    Marker: oss.Ptr("example-bucket"), // Results start from the bucket after "example-bucket".
}

p := client.NewListBucketsPaginator(request)

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

for p.HasNext() {
    i++

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

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

Using ListBuckets

var marker string = "example-bucket"

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

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

Control page size

Sets the maximum number of buckets returned per page.

Using the paginator

request := &oss.ListBucketsRequest{
    MaxKeys: 5, // Return up to 5 buckets per page.
}

p := client.NewListBucketsPaginator(request)

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

for p.HasNext() {
    i++

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

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

Using ListBuckets

request := &oss.ListBucketsRequest{
    MaxKeys: 10, // Return up to 10 buckets per page.
}

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

Filter by resource group

Pass ResourceGroupId to return only buckets in a specific resource group. If ResourceGroupId is omitted, OSS returns all buckets owned by the requester, and the response does not include resource group information.

Using the paginator

request := &oss.ListBucketsRequest{
    ResourceGroupId: oss.Ptr("rg-aek27tc********"),
}

p := client.NewListBucketsPaginator(request)

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

for p.HasNext() {
    i++

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

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

Using ListBuckets

request := &oss.ListBucketsRequest{
    MaxKeys:         10,
    ResourceGroupId: oss.Ptr("rg-aek27tc********"),
}

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

Complete runnable example: list_buckets.go on GitHub
Paginator API reference: NewListBucketsPaginator
Direct call API reference: ListBuckets
Paginator design guide: Developer guide