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 requests
    PUT /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 responses
    200 (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 requests
    PUT /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 responses
    200 (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.