Object tagging

KS3 allows you to classify objects by using tags. You can configure lifecycle rules for objects with specified tags.

Note: The object tagging feature is in public preview and is free of charge during this period. After the public preview ends, Kingsoft Cloud charges you for using this feature. For more information, see Billing modes and items.

Tags are key-value pairs that are attached to objects. You can attach tags to objects when you upload the objects or attach tags to existing objects.

A maximum of 10 tags can be attached to each object.

Rules of setting a key:

• A key can contain letters, digits, spaces, and the following special characters: plus signs (+), hyphens (-), 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 use a reserved field of the system as a key. Do not start a key with ksc: or kss:.

Rules of setting a value:

• A value can contain letters, digits, spaces, and the following special characters: plus signs (+), hyphens (-), 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.

Only the bucket owner and authorized users have read and write permissions on object tags.
Object tags are also replicated to the destination bucket during cross-region replication.

Scenarios

Object tags are not limited to folders. You can manage objects with specified tags in batches.

You can configure lifecycle rules for objects with specified tags. For example, you can configure tags for temporary objects that are periodically generated. Then, you can configure lifecycle rules to delete these objects based on the specified tags.

Usage notes

API operations related to object tagging

• PUT Object Tagging: You can call this operation to configure tags for an object. If an object already has tags, the existing tags are overwritten.
• GET Object Tagging: You can call this operation to read tags of an object.
• DELETE Object Tagging: You can call this operation to delete tags of an object.
• PUT Object: You can specify tags by using the x-kss-tagging request header when you upload an object.
• POST Object: You can specify tags by using the tagging request header when you upload an object by using an HTML form.
• Initiate Multipart Upload: You can specify tags by using the x-kss-tagging request header when you initialize a multipart upload task.
• PUT Object Copy: When you copy an object, you can use the x-kss-tagging-directive request header to specify whether to overwrite tags of the source object, and use the x-kss-tagging request header to configure tags for the target object.
• PUT Fetch: You can configure tags for the target object by using the x-kss-tagging request header when you pull an object and upload it to a specified KS3 bucket.
• GET Object: If you have the permission to read object tags, the number of tags is returned in the x-kss-tagging-count response header when you call this operation to obtain an object.
• HEAD Object: If you have the permission to read object tags, the number of tags is returned in the x-kss-tagging-count response header when you call this operation to obtain the metadata of an object.

Console operations related to object tagging

For more information, see Configure object tagging.

SDKs related to object tagging

• SDK for Java
• SDK for Go

Permissions

Users, roles, and services that perform operations related to tags must have the following permissions. You can manage these permissions by using bucket policies and IAM roles.

• GetObjectTagging: the permission to obtain object tags. If you have this permission, you can view the existing tags of an object.
• PutObjectTagging: the permission to configure tags for an object. If you have this permission, you can configure tags for objects.
• DeleteObjectTagging: the permission to delete object tags. If you have this permission, you can delete tags of an object.

Examples:

• You must have the PutObjectTagging permission to configure tags for existing objects or configure tags for objects when you upload them.

• You must have the following permissions to copy an object with tags by calling the PUT Object Copy operation:

  • GetObject and GetObjectTagging permissions on the source object
  • PutObject and PutObjectTagging permissions on the target object

• If you set the value of x-kss-tagging-directive to REPLACE but leave new tags empty, you only need to have the PutObject permission on the target object.

• You must have the DeleteObjectTagging permission to delete object tags.

• However, if you have the DeleteObject permission, you can delete an object together with its tags.

For more information about API permissions, see the description of the API operations that are listed in the “API operations related to object tagging” section.

Object tagging and lifecycle management

When you configure a lifecycle rule, you can specify a filter to select the objects on which the lifecycle rule applies. You can specify a filter based on an object name prefix, object tags, or both.

• If you specify a tag as a filter, the rule applies to an object only when the object has the specified tag and the value of the tag is the specified one.
• If you specify an object name prefix and multiple object tags as a filter, the rule applies to an object only when the object meets all the conditions. That is, the name of the object starts with the specified prefix and the object has all the specified tags with the specified values.

Example:

<LifecycleConfiguration>
  <Rule>
    <ID>1</ID>
    <Filter>
       <And>
          <Prefix>documents</Prefix>
          <Tag>
             <Key>age</Key>
             <Value>21</Value>
          </Tag>
          <Tag>
            <Key>name</Key>
            <Value>li</Value>
           </Tag>
       </And>
    </Filter>
    <Status>Enabled</Status>
    <Expiration>
        <Days>30</Days>
    </Expiration>
  </Rule>
  <Rule>
    <ID>2</ID>
      <Filter>
            <And>
               <Prefix>pic</Prefix>
               <Tag>
                  <Key>age</Key>
                  <Value>20</Value>
               </Tag>
            </And>
         </Filter>
    <Status>Enabled</Status>
    <Transition>
        <Days>60</Days>
        <StorageClass>Archive</StorageClass>
    </Transition>
  </Rule>
</LifecycleConfiguration>

Based on the preceding rules,

• Objects that have documents as the prefix in their names and have the tags age=21 and name=li are deleted after they are stored for 30 days.
• The storage class of objects that have pic as the prefix in their names and have the tag age=20 is changed to Archive after the objects are stored for 60 days.

Note: For more information of lifecycle rules, see Manage lifecycle.