Description
COS allows you to set tags for an existing bucket. The PUT Bucket tagging API is used to set key-value pairs as bucket tags, helping you manage existing bucket resources and conduct cost management through tags.
Note:
Currently, the bucket tag feature supports a maximum of 50 different tags for a bucket.
Request
Request Example
PUT /?tagging HTTP 1.1
Host:<BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String
Content-MD5: MD5
Content-Length: Content Length
Content-Type: application/xml
[Request Body]
Note:
Authorization: Auth String (For details, see Request Signature documentation).
Request Header
In addition to using common request headers, this API also supports the following request headers. For details about common request headers, see Public Request Headers documentation.
| Name | Description | Type | Required |
|---|---|---|---|
| Content-MD5 | The MD5 hash value of the request body content, encoded in Base64 as defined in RFC 1864, is used for integrity checking to verify whether the request body has changed during the transmission. | string | Yes |
Request Body
This request needs to set the following tag set:
<?xml version="1.0" encoding="UTF-8" ?>
<Tagging>
<TagSet>
<Tag>
<Key>age</Key>
<Value>18</Value>
</Tag>
<Tag>
<Key>name</Key>
<Value>xiaoming</Value>
</Tag>
</TagSet>
</Tagging>
The data are described as follows:
| Node Name (Keyword) | Parent Node | Description | Type | Required |
|---|---|---|---|---|
| Tagging | No | Tag Set | Container | Yes |
| TagSet | Tagging | Tag Set | Container | Yes |
| Tag | Tagging.TagSet | Tag set, supports up to 10 tags. | Containers | Yes |
| Key | Tagging.TagSet.Tag | The length of the tag key is no more than 128 bytes, and the tag key supports English letters, numbers, spaces, plus signs, minus signs, underscores, equal signs, periods, colons, and slashes. | String | Yes |
| Value | Tagging.TagSet.Tag | The value of the tag is no longer than 256 bytes, and the value supports English letters, numbers, spaces, plus signs, minus signs, underscores, equal signs, periods, colons, and slashes. | String | Yes |
Response
Response Headers
This API only returns the public response header. For details, see Common Response Headers documentation.
Response Body
The response body is empty.
Error Code
The following describes some special but common errors that may occur with this request:
| Error Code | Description | HTTP Status Code |
|---|---|---|
| SignatureDoesNotMatch | If this error code is returned, it means the provided signature is incorrect. | 403 Forbidden |
| NoSuchBucket | If this error code is returned, it means the bucket you want to add the rule to is not found. | 404 Not Found |
| MalformedXML | The XML syntax of the request body is incorrect. Please compare it carefully with the restful API document. | 400 Bad Request |
| BadRequest | If the maximum number of tags allowed for a bucket is exceeded, a maximum of 10 tags are currently supported. | 400 Bad Request |
| InvalidTag | The key and value of the tag contain the reserved string cos: or Project. | 400 Bad Request |
Practical Case
Request
The following request writes two tags {age:18} and {name:xiaoming} to the bucket examplebucket-1250000000. COS configures the tags successfully and returns a 204 success response.
PUT /?tagging HTTP/1.1
User-Agent: curl/7.29.0
Accept: */*
Host: examplebucket-1250000000.cos.city.yfm4.fsphere.cn
Authorization: q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&q-sign-time=1516361923;1517361973&q-key-time=1516361923;1517361973&q-url-param-list=tagging&q-header-list=content-md5;host&q-signature=71251feb4501494edcfbd01747fa873003759404
Content-MD5: LIbd5t5HLPhuNWYkP6qHcQ==
Content-Length: 127
Content-Type: application/xml
<Tagging>
<TagSet>
<Tag>
<Key>age</Key>
<Value>18</Value>
</Tag>
<Tag>
<Key>name</Key>
<Value>xiaoming</Value>
</Tag>
</TagSet>
</Tagging>
Response
HTTP/1.1 204 No Content
Content-Type: application/xml
Content-Length: 0
Connection: keep-alive
Date: Fri, 19 Jan 2018 11:40:22 GMT
x-cos-request-id: NWE2MWQ5MjZfMTBhYzM1MGFfMTA5ODVfMTVjNDM=