All Products
Search
Document Center

Object Storage Service:Bucket tagging

Last Updated:Oct 19, 2023

Bucket tags allow you to classify and manage buckets. For example, you can specify to list only buckets with specific tags when you call the ListBucket operation.

Usage notes

  • In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS by using other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about the regions and endpoints supported by OSS, see Regions and endpoints.

  • In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.

  • In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Create an OSSClient instance.

  • Only the bucket owner and users who are granted the oss:PutBucketTagging permission can configure tags for buckets. If other users attempt to configure tags for buckets, the 403 Forbidden message that contains the AccessDenied error code is returned.

  • You can configure up to 20 tags (key-value pairs) for each bucket.

  • The key and value of a tag must be encoded in UTF-8.

  • The key can be up to 64 characters in length. It is case-sensitive and cannot be empty. The key cannot start with http://, https://, or Aliyun. These prefixes are not case-sensitive.

  • The value of a tag can be up to 128 characters in length and can be empty.

Configure tags for a bucket

The following code provides an example on how to configure tags for a bucket:

const OSS = require('ali-oss')

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET
});

// Configure tags for the bucket. 
async function putBucketTags(bucketName, tag) {
  try {
    const result = await client.putBucketTags(bucketName, tag);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

const tag = { a: '1', b: '2' };
putBucketTags('bucketName', tag)

Query the tags of a bucket

The following code provides an example on how to query the tags of a bucket:

const OSS = require('ali-oss')

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET
});

// Query the tags of the bucket. 
async function getBucketTags(bucketName) {
  try {
    const result = await client.getBucketTags(bucketName);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

getBucketTags('bucketName')

List the buckets that have a specific tag

The following code provides an example on how to list the buckets that have a specific tag:

const OSS = require('ali-oss')

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET
});

// List the buckets that have a specific tag. 
async function listBucketTags() {
  try {
    const params = {
      // Add the tag-key and tag-value fields to the params parameter in the listBuckets operation. 
      'tag-key': 'yourTagKey',
      'tag-value': 'yourTagValue'
    }
    const result = await client.listBuckets(params);
    console.log(result);
  } catch (err) {
    console.log(err);
  }
}

listBucketTags();

Delete the tags of a bucket

The following code provides an example on how to delete the tags of a bucket:

const OSS = require('ali-oss')

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET
});

// Delete the tags of the bucket. 
async function deleteBucketTags(bucketName) {
  try {
    const result = await client.deleteBucketTags(bucketName);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

deleteBucketTags('bucketName')

References

  • For the complete sample code that is used to manage the tags of a bucket, visit GitHub.

  • For more information about the API operation that you can call to configure tags for a bucket, see PutBucketTags.

  • For more information about the API operation that you can call to query the tags of a bucket, see GetBucketTags.

  • For more information about the API operation that you can call to delete the tags of a bucket, see DeleteBucketTags.