Put Object Tagging

Last updated:2021-04-07 21:41:14

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>.ksyun.com
Date: GMT Date
Authorization: Auth String
<Tagging>
    <TagSet>
        <Tag>
            <Key>string</Key>
            <Value>string</Value>
        </Tag>
    </TagSet>
</Tagging>    

Request elements

Element Type Required Description
Tagging Container Yes The collection of tags.
Child node: TagSet
TagSet Container Yes The collection of tags.
Parent node: Tagging
Child node: Tag
Tag Container Yes The collection of tags.
Parent node: TagSet
Child nodes: Key and Value
Key String Yes The key of the object tag. A key can be 1 to 128 characters in length and can contain uppercase letters, lowercase letters, digits, spaces, plus signs (+), minus signs (–), underscores (_), equal signs (=), periods (.), colons (😃, and forward slashes (/).
Parent node: Tag
Child node: none
Value String Yes The value of the object tag. A value can be 1 to 256 characters in length and can contain uppercase letters, lowercase letters, digits, spaces, plus signs (+), minus signs (–), underscores (_), equal signs (=), periods (.), colons (😃, and forward slashes (/).
Parent node: Tag
Child node: none

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>.ksyun.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

Error code Description HTTP status code
SignatureDoesNotMatch The error code returned because the provided signature does not comply with the signature rules. 403 Forbidden
TNoSuchObject The error code returned because the object does not exist and you cannot configure tagging for the object. 404 Not Found
MalformedXML The error code returned because the XML format is invalid. Check the XML format based on the RESTful API documentation. 400 Bad Request
InvalidTag The error code returned because the tag key or value contains the reserved field of the system, ksc: or kss:. 400 Bad Request
BadRequest The error code returned because the number of tags exceeds the upper limit. A maximum of 10 tags can be set for each object. 400 Bad Reques

References:

Did you find the above information helpful?

Unhelpful
Mostly Unhelpful
A little helpful
Helpful
Very helpful

What might be the problems?

  • Insufficient
  • Outdated
  • Unclear or awkward
  • Redundant or clumsy
  • Lack of context for the complex system or functionality

More suggestions

0/200

Please give us your feedback.

Submitted

Thank you for your feedback.

问题反馈