Como listar buckets usando o Go SDK V2 - Object Storage Service: Central de Documentação do Alibaba Cloud

Precauções

O código de exemplo deste tópico usa o ID da região China (Hangzhou) cn-hangzhou. Por padrão, o sistema usa o endpoint público. Para acessar o OSS a partir de outros serviços da Alibaba Cloud na mesma região, use o endpoint interno. Para obter mais informações sobre os mapeamentos entre regiões e endpoints do OSS, consulte Regiões e endpoints do OSS.
Os exemplos deste tópico demonstram como ler credenciais de acesso de variáveis de ambiente. Para saber mais sobre como configurar credenciais de acesso, consulte Configurar credenciais de acesso.
Para listar buckets, você precisa da permissão oss:ListBuckets. Para mais detalhes, consulte Conceder permissões personalizadas a um usuário RAM.
Ao usar um SDK para listar buckets, especifique um ID de grupo de recursos para filtrar buckets em um grupo específico.
- Por padrão, a listagem de buckets via SDK não inclui o parâmetro de ID do grupo de recursos. Consequentemente, a resposta XML não contém informações sobre grupos de recursos.
- Se você incluir o parâmetro de ID do grupo de recursos na solicitação, o OSS retornará todos os buckets pertencentes a esse grupo.
- Caso você não inclua o parâmetro de ID do grupo de recursos na solicitação, o OSS retornará todos os buckets de propriedade do solicitante.

Definição do método

Operação de API para listar buckets (Edição Premium)

Importante

Para operações de listagem frequentes, o Go SDK V2 oferece um paginador com suporte a paginação automática. Esse componente recupera automaticamente os resultados das páginas subsequentes; assim, você só precisa escrever o código para processar os dados.
Um paginador consiste em um objeto paginador, <OperationName>Paginator, e um método de criação, New<OperationName>Paginator. O método de criação retorna um objeto que implementa os métodos HasNext e NextPage. Use esses métodos para verificar a existência de mais páginas e invocar a operação para recuperar a próxima página.

O código abaixo apresenta a definição da operação para listar 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)

Parâmetros da solicitação

Parâmetro	Tipo	Descrição
request	*ListBucketsRequest	Os parâmetros da solicitação da operação. Para mais informações, consulte ListBucketsRequest
optFns	...func(*PaginatorOptions)	(Opcional) Os parâmetros de configuração no nível da operação. Para mais informações, consulte PaginatorOptions

Valores de retorno

Valor de retorno	Descrição
*ListBucketsPaginator	O objeto paginador. Este objeto implementa os métodos HasNext e NextPage, usados para determinar se existem mais páginas e chamar a operação para recuperar a próxima página.

Operação de API para listar buckets (Edição Básica)

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

Parâmetros da solicitação

Parâmetro	Tipo	Descrição
ctx	context.Context	O contexto de uma solicitação. Use este parâmetro para definir o tempo limite de uma solicitação.
request	*ListBucketsRequest	Os parâmetros da solicitação da operação. Para mais informações, consulte ListBucketsRequest
optFns	...func(*Options)	(Opcional) Os parâmetros de configuração no nível da operação. Para mais informações, consulte Options

Valores de retorno

Valor de retorno	Tipo	Descrição
result	*ListBucketsResult	O valor de retorno da operação. Este parâmetro é válido apenas quando err é nil. Para mais informações, consulte ListBucketsResult
err	error	O status da solicitação. Se a solicitação falhar, err não será nil.

Código de exemplo

Listar buckets usando a operação de API da Edição Premium

Use o código a seguir para listar todos os buckets em todas as regiões da sua conta.

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

}

Listar buckets usando a operação de API da Edição Básica

Use o código a seguir para listar todos os buckets em todas as regiões da sua conta.

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

Cenários comuns

Listar buckets com um prefixo especificado

Usar um Paginator

Execute o código abaixo para listar buckets cujos nomes tenham o prefixo example em todas as regiões da sua conta.

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

Usar ListBuckets

Execute o código abaixo para listar buckets cujos nomes tenham o prefixo example em todas as regiões da sua conta.

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

Listar buckets posteriores a um marcador especificado

Usar um Paginator

Use o código a seguir para listar buckets cujos nomes sejam alfabeticamente posteriores a example-bucket em todas as regiões da sua conta.

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

Usar ListBuckets

Use o código a seguir para listar buckets cujos nomes sejam alfabeticamente posteriores a example-bucket em todas as regiões da sua conta.

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

Listar um número especificado de buckets

Usar um Paginator

O código abaixo lista buckets em todas as regiões da sua conta e define o número máximo de buckets retornados por página.

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

}

Usar ListBuckets

O código abaixo lista buckets em todas as regiões da sua conta e define o número máximo de buckets retornados por página.

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

Listar todos os buckets em um grupo de recursos especificado

Usar um Paginator

Ao especificar o ID do grupo de recursos ResourceGroupId nos parâmetros da solicitação, o OSS retorna todos os buckets pertencentes a esse grupo.
Se você não especificar o ID do grupo de recursos ResourceGroupId nos parâmetros da solicitação, o OSS retorna todos os buckets de propriedade do solicitante.

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

}

Usar ListBuckets

Ao especificar o ID do grupo de recursos ResourceGroupId nos parâmetros da solicitação, o OSS retorna todos os buckets pertencentes a esse grupo.
Se você não especificar o ID do grupo de recursos ResourceGroupId nos parâmetros da solicitação, o OSS retorna todos os buckets de propriedade do solicitante.

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

Referências

Para ver o código de exemplo completo sobre como listar buckets, consulte o exemplo no GitHub.
Para obter mais informações sobre a operação de API para listar buckets (Edição Premium), consulte NewListBucketsPaginator.
Para obter mais informações sobre a operação de API para listar buckets (Edição Básica), consulte ListBuckets.
Para saber mais sobre paginadores, consulte o Guia do Desenvolvedor.