Description
COS allows you to set tags for existing objects. The PUT Object tagging API is used to add key-value pairs for objects as object tags to help you group and manage existing object resources. For details, see Object Tag Overview.
If you use a sub-account to call this interface, make sure you have obtained permission for PUT Object tagging at the root account level.
Note
- The object tagging feature can set up to 10 different tags for a single object.
- If object tags already exist, calling this API will overwrite the existing tags.
Versioning
If versioning is enabled for your bucket and you need to add tags to a specific version of an object, you can include the VersionId parameter in the request, and the object tags will be added to the specified object version.
Request
Request Example
PUT /<ObjectKey>?tagging&VersionId=VersionId HTTP 1.1
Host:<BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String
Description
- indicates the bucket name with APPID as the suffix, for example, examplebucket-1250000000.
- Authorization: Auth String (For details, please refer to the Request Signature document).
Request Parameters
| Name | Description | Type | Required |
|---|---|---|---|
| versionId | When versioning is enabled, specify the version ID of the object to operate on. If it is not specified, the tags are added to the latest version of the object. | string | No |
Request Header
This API only uses common request headers. For details, see Common Request Headers documentation.
Request Body
This request needs to set the following tag set:
<?xml version="1.0" encoding="UTF-8" ?>
<Tagging>
<TagSet>
<Tag>
<Key>string</Key>
<Value>string</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 | Tag key, which cannot be empty and has a length of less than 128 bytes, supporting letters, digits, spaces, plus signs, minus signs, underscores, equal signs, periods, colons, and slashes. | String | Yes |
| Value | Tagging.TagSet.Tag | Tag value, with a length of less than 256 bytes, supporting letters, digits, 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
This API follows unified error response and error codes. For details, please refer to the Error Codes document.
Practical Case
Request
The following request adds the {age:18} and {name:xiaoming} tags to the exampleobject.txt object in the examplebucket-1250000000 bucket. COS configures the tags and returns 200 (success).
PUT /exampleobject.txt?tagging HTTP/1.1
User-Agent: curl/7.29.0
Accept: */*
Host: examplebucket-1250000000.cos.city.yfm4.fsphere.cn
Authorization: Auth String
Content-Length: 127
Content-MD5:MD5 String
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 200 OK
Content-Type: application/xml
Content-Length: 0
Connection: keep-alive
Date: Fri, 19 Jan 2020 11:40:22 GMT
x-cos-request-id: NWE2MWQ5MjZfMTBhYzM1MGFfMTA5ODVfMTVj****