Put Object Tagging

You can call this operation to configure tagging or update the tagging configurations for an object.

Important notes

Object tagging uses a key-value pair to tag an object. When you call this operation, take note of the following items:

• A maximum of 10 tags can be set for each object. Each object tag must have a unique tag key.

  Rules of setting a key:

  • A key can contain letters, digits, spaces, and the following special characters: plus signs (+), minus signs (-), equal signs (=), periods (.), underscores (_), colons (\:), and forward slashes (/).

  • A key cannot start or end with a space or be left empty. It can be 1 to 128 characters in length and is case-sensitive.

  • Do not start a key with the reserved field of the system, that is, ksc: or kss:.

  Rules of setting a value:

  • A value can contain letters, digits, spaces, and the following special characters: plus signs (+), minus signs (-), equal signs (=), periods (.), underscores (_), colons (\:), and forward slashes (/).

  • A value cannot start or end with a space. It can be 1 to 256 characters in length and is case-sensitive.
• The Last-Modified value of an object is not updated when the object tags are changed.

If you configure the tags in the HTTP header and the tags contain any characters, you need to use URL encoding to encode the keys and values of the tags.

For more information about object tagging, see Object Tagging.

Permission

To call this operation, you must have the PutObjectTagging permission on the object. KS3 returns corresponding information based on whether you have the PutObjectTagging permission. If you do not have the PutObjectTagging permission on the object, KS3 returns an HTTP 403 error with the error message "access denied."

Request syntax

PUT /<ObjectKey>?tagging HTTP 1.1
Host:<BucketName>.<Region>.ksyuncs.com
Date: GMT Date
Authorization: Auth String
<Tagging>
    <TagSet>
        <Tag>
            <Key>string</Key>
            <Value>string</Value>
        </Tag>
    </TagSet>
</Tagging>    

Request elements

Examples

• Sample request

  ObjectKey is contained in BucketName. You can send a PUT request to add the {name:1} and {age:2} tags to ObjectKey. After the two tags are added, 200 OK is returned.

  PUT /<ObjectKey>?tagging HTTP 1.1
  Host:<BucketName>.<Region>.ksyuncs.com
  Date: GMT Date
  Authorization: Auth String
  <Tagging>
  <TagSet>
    <Tag>
      <Key>name</Key>
      <Value>1</Value>
    </Tag>
    <Tag>
      <Key>age</Key>
      <Value>2</Value>
    </Tag>
  </TagSet>
  </Tagging>

  • Sample response

  HTTP/1.1 200 OK
  Date: Fri, 26 Dec 2020 06:34:32 GMT
  x-kss-request-id: dbea4ce4ec23415b9e454ecfa25e****
  Content-Length: 0
  Server: Tengine

Error codes

References:

• Endpoints and regions
• Request signature