Manage bucket tags using Go SDK - Object Storage Service

Assign key-value tags to OSS buckets to classify, filter, and manage them across environments, teams, or cost centers.

Prerequisites

Before you begin, ensure that you have:

Set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables with valid access credentials. For setup instructions, see Configure access credentials
The endpoint and region for your bucket. Examples in this topic use the China (Hangzhou) public endpoint (https://oss-cn-hangzhou.aliyuncs.com, region cn-hangzhou). For other regions, see Regions and endpoints. To access OSS from another Alibaba Cloud service in the same region, use the internal endpoint instead
(Optional) If you need to create the OSSClient instance using a custom domain name or Security Token Service (STS), see Configure OSSClient instances

How it works

All examples in this topic use the same OSSClient initialization pattern:

Load credentials from environment variables using oss.NewEnvironmentVariableCredentialsProvider.
Create the client with oss.New, passing the endpoint, region, and V4 signature version (oss.AuthV4).
Call the tagging method on the client.

Replace yourEndpoint and yourRegion with your bucket's endpoint and region in every example.

Set bucket tags

The following code shows how to set tags for a bucket named examplebucket.

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Load credentials from environment variables.
	// OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET must be set before running this example.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// Create an OSSClient instance.
	// Replace yourEndpoint with your bucket's endpoint, e.g., https://oss-cn-hangzhou.aliyuncs.com.
	// Replace yourRegion with your bucket's region, e.g., cn-hangzhou.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// Build the tag set.
	tag1 := oss.Tag{Key: "key1", Value: "value1"}
	tag2 := oss.Tag{Key: "key2", Value: "value2"}
	tagging := oss.Tagging{Tags: []oss.Tag{tag1, tag2}}

	// Apply tags to the bucket.
	err = client.SetBucketTagging("examplebucket", tagging)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
}

Get bucket tags

GetBucketTagging returns all tags on a bucket. The response includes a Tags slice — iterate over it to read individual key-value pairs.

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	ret, err := client.GetBucketTagging("examplebucket")
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// Print the number of tags.
	fmt.Println("Tag count:", len(ret.Tags))
}

List buckets by tag

ListBuckets accepts oss.TagKey and oss.TagValue as filter options. Filter by key alone to match all buckets with that key regardless of value, or combine both options to narrow results to an exact key-value pair.

oss.TagValue must always be paired with oss.TagKey. Using oss.TagValue alone has no filtering effect.

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// Filter by tag key only — returns all buckets that have the key,
	// regardless of the associated value.
	ret, err := client.ListBuckets(oss.TagKey("yourTaggingKey"))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	for _, bucket := range ret.Buckets {
		fmt.Println("Bucket:", bucket)
	}

	// Filter by both tag key and tag value — returns only buckets
	// where the key and value both match exactly.
	res, err := client.ListBuckets(oss.TagKey("yourTaggingKey"), oss.TagValue("yourTaggingValue"))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	for _, b := range res.Buckets {
		fmt.Println("Bucket:", b)
	}
}

Delete bucket tags

Delete a specific tag

Pass the tag key as a comma-separated string to oss.AddParam("tagging", ...). The following example deletes the tag with key key1.

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	err = client.DeleteBucketTagging("examplebucket", oss.AddParam("tagging", "key1"))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
}

Delete multiple tags

Provide a comma-separated list of keys. The following example deletes the tags with keys key1 and key2.

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	err = client.DeleteBucketTagging("examplebucket", oss.AddParam("tagging", "key1,key2"))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
}

Delete all tags

Call DeleteBucketTagging without additional parameters to remove all tags from the bucket.

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	err = client.DeleteBucketTagging("examplebucket")
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
}

Object Storage Service:Bucket tagging (Go SDK V1)