PutBucketTags - Add or modify bucket tags - Object Storage Service

Usage notes

When you call PutBucketTags, note the following:

Only the bucket owner and authorized RAM users can configure bucket tags. Other users receive a 403 Forbidden error with the AccessDenied error code.
Each bucket supports up to 20 tags (key-value pairs).
PutBucketTags uses overwrite semantics: a new tag replaces any existing tag with the same key.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

Request syntax

PUT /?tagging HTTP/1.1
Date: GMT Date
Content-Length: ContentLength
Authorization: SignatureValue
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
<?xml version="1.0" encoding="UTF-8"?>
<Tagging>
  <TagSet>
    <Tag>
      <Key>key1</Key>
      <Value>value1</Value>
    </Tag>
    <Tag>
      <Key>key2</Key>
      <Value>value2</Value>
    </Tag>
  </TagSet>
</Tagging>

Request headers

This request uses only common request headers. For more information, seeCommon request headers.

Request elements

Element	Type	Required	Description
Tagging	Container	Yes	Container for TagSet. Child nodes: TagSet Parent nodes: none
TagSet	Container	Yes	Container for tags. Child nodes: Tag Parent nodes: Tagging
Tag	Container	Yes	Container for the tag to add or modify. Child nodes: Key and Value Parent nodes: TagSet
Key	STRING	Yes	The tag key. Maximum length: 64 bytes. A tag key cannot start with `http://`, `https://`, or `Aliyun`. Must be UTF-8 encoded. Cannot be empty. Child nodes: none Parent nodes: Tag
Value	STRING	No	The tag value. Maximum length: 128 bytes. Must be UTF-8 encoded. Can be empty. Child nodes: none Parent nodes: Tag

Response headers

This response uses only common response headers. For more information, seeCommon response headers.

Examples

Sample request

PUT /?tagging
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 11:49:13 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<Tagging>
  <TagSet>
    <Tag>
      <Key>testa</Key>
      <Value>testv1</Value>
    </Tag>
    <Tag>
      <Key>testb</Key>
      <Value>testv2</Value>
    </Tag>
  </TagSet>
</Tagging>

Sample response

200 (OK)
content-length: 0
server: AliyunOSS
x-oss-request-id: 5C1B138A109F4E405B2D****
date: Thu, 20 Dec 2018 11:59:06 GMT
x-oss-server-time: 148
connection: keep-alive

OSS SDKs

You can call PutBucketTags by using OSS SDKs for the following languages:

ossutil

For information about the ossutil command that corresponds to the PutBucketTags operation, see put-bucket-tags.

API	Action	Description
PutBucketTags	oss:PutBucketTagging	Adds tags to or modifies the tags of a bucket.