Adds tags to an object or updates the tags added to the object. The object tagging feature uses a key-value pair to tag an object.
Usage notes
- You can add up to 10 tags to an object. The tags added to an object must have unique tag keys.
- A tag key can be up to 128 characters in length. A tag value can be up to 256 characters in length.
- Tag keys and values are case-sensitive.
- The key and value of a tag can contain letters, digits, spaces, and the following
special characters:
+ - = ._:/
If the tags of the HTTP header contain characters, you must perform URL encoding on the keys and values of the tags.
- The Last-Modified value of an object is not updated when the object tags are changed.
For more information about object tags, see Configure object tagging.
Versioning
By default, when you call PutObjectTagging to add tags to an object or update the tags configured for an object, the tags are added to the current version of the object or the tags configured for the current version of the object are updated. You can specify the versionId parameter in the request to add tags to a specified version of an object or update the tags configured for a specified version of an object. If the specified version is a delete marker, OSS returns 404 Not Found.
Request syntax
PUT /objectname?tagging
Content-Length: 114
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: Mon, 18 Mar 2019 08:25:17 GMT
Authorization: SignatureValue
<Tagging>
<TagSet>
<Tag>
<Key>Key</Key>
<Value>Value</Value>
</Tag>
</TagSet>
</Tagging>
Request elements
Element | Type | Required | Description |
---|---|---|---|
Tagging | Container | Yes | The container used to store the collection of tags.
Child nodes: TagSet |
TagSet | Container | Yes | The container used to store the collection of tags.
Parent nodes: Tagging Child nodes: Tag |
Tag | Container | No | The container used to store the collection of tags.
Parent nodes: TagSet Child nodes: Key and Value |
Key | String | No | The key of the object tag.
Parent nodes: Tag Child nodes: none |
Value | String | No | The value of the object tag.
Parent nodes: Tag Child nodes: none |
Examples
- Add tags to an object in an unversioned bucket
In this example, an object named objectname is stored in an unversioned bucket named bucketname. A PutObjectTagging request is sent to add the {a:1} and {b:2} tags to objectname. After the two tags are added to the object, 200 (OK) is returned.
Sample requestsPUT /objectname?tagging Content-Length: 114 Host: BucketName.oss-cn-hangzhou.aliyuncs.com Date: Mon, 18 Mar 2019 08:25:17 GMT Authorization: OSS ***********:********************* <Tagging> <TagSet> <Tag> <Key>a</Key> <Value>1</Value> </Tag> <Tag> <Key>b</Key> <Value>2</Value> </Tag> </TagSet> </Tagging>
Sample responses200 (OK) content-length: 0 server: AliyunOSS x-oss-request-id: 5C8F55ED461FB4A64C00**** date: Mon, 18 Mar 2019 08:25:17 GMT
- Add tags to an object in a versioned bucket
In this example, an object named objectname is stored in a versioned bucket named bucketname. A PutObjectTagging request is sent to add the {age:18} tag to the specified version of objectname. After the tag is added to the specified version of the object, 200 (OK) is returned.
Sample requestsPUT /objectname?tagging&versionId=CAEQExiBgID.jImWlxciIDQ2ZjgwODIyNDk5MTRhNzBiYmQwYTZkMTYzZjM0**** Content-Length: 90 Host: BucketName.oss-cn-hangzhou.aliyuncs.com Date: Wed, 24 Jun 2020 08:58:15 GMT Authorization: OSS ************:******************** <Tagging> <TagSet> <Tag> <Key>age</Key> <Value>18</Value> </Tag> </TagSet> </Tagging>
Sample responses200 (OK) content-length: 0 server: AliyunOSS x-oss-request-id: 5EF315A7FBD3EC3232B4**** date: Wed, 24 Jun 2020 08:58:15 GMT x-oss-version-id: CAEQExiBgID.jImWlxciIDQ2ZjgwODIyNDk5MTRhNzBiYmQwYTZkMTYzZjM0****
SDK
You can use OSS SDKs for the following programming languages to call the PutObjectTagging operation:
Error codes
Error code | HTTP status code | Description |
---|---|---|
FileAlreadyExists | 409 | The error message returned because the object for which you want to configure or update tags is a directory within a bucket that has the hierarchical namespace feature enabled. |