Object Storage Service (OSS) allows you to configure object tags to classify objects. You can configure lifecycle rules and control access to objects based on tags.

Background information

When you configure object tagging, take note of the following items:

  • You can add tags to an object when and after you upload the object. If the object already has tags, the existing tags are overwritten. For more information about how to configure object tags, see PutObjectTagging.
  • To add tags to an object, you must have the permissions to add tags.
  • The Last-Modified value of an object is not updated when its tags are changed.
  • You can add up to 10 tags to an object. The tags added to an object must have unique keys.
  • A tag key can be a maximum of 128 characters in length. A tag value can be a maximum of 256 characters in length.
  • Tag keys and tag values are case-sensitive.
  • The key and value of a tag can contain letters, digits, spaces, and the following special characters:

    + - = ._:/

    Note If you configure the tags in the HTTP header and the tags contain characters, you can encode the keys and values of the tags by using URL encoding.

Object tagging uses a key-value pair to identify objects. For more information about object tags, see Configure object tagging.

Add tags to an object when you upload the object

  • Add tags to an object when you upload the object by using simple upload

    The following code provides an example on how to add tags to an object when you upload the object by using simple upload:

    # -*- coding: utf-8 -*-
    
    import oss2
    from oss2.headers import OSS_OBJECT_TAGGING
    
    # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a Resource Access Management (RAM) user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
    # Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'yourEndpoint', 'examplebucket')
    # Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
    object_name = 'exampledir/exampleobject.txt'
    
    # Configure the tagging string. 
    tagging = "k1=v1&k2=v2&k3=v3"
    
    # If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
    k4 = "k4+-="
    v4 = "+-=._:/"
    tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)
    
    # Configure the tags in the HTTP headers. 
    headers = dict()
    headers[OSS_OBJECT_TAGGING] = tagging
    
    # Specify the headers when you call the put_object operation so that the tags are added to the object when it is uploaded. 
    result = bucket.put_object(object_name, 'content', headers=headers)
    print('http response status: ', result.status)
    
    # Query the tags added to the object. 
    result = bucket.get_object_tagging(object_name)
    for key in result.tag_set.tagging_rule:
        print('tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))
  • Add tags to an object when you upload the object by using multipart upload

    The following code provides an example on how to add tags to an object when you upload the object by calling multipart_upload:

    # -*- coding: utf-8 -*-
    
    import os
    import oss2
    from oss2 import SizedFileAdapter, determine_part_size
    from oss2.models import PartInfo
    from oss2.headers import OSS_OBJECT_TAGGING
    
    # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
    # Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'yourEndpoint', 'examplebucket')
    # Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
    object_name = 'exampledir/exampleobject.txt'
    # Specify the full path of the local file that you want to upload. Example: D:\\localpath\\examplefile.txt. 
    # By default, if you specify only the name of the local file such as examplefile.txt without specifying the local path, the local file is uploaded from the path of the project to which the sample program belongs. 
    filename = 'D:\\localpath\\examplefile.txt'
    
    total_size = os.path.getsize(filename)
    # Use the determine_part_size method to determine the size of each part. 
    part_size = determine_part_size(total_size, preferred_size=100 * 1024)
    
    # Configure the tagging string. 
    tagging = "k1=v1&k2=v2&k3=v3"
    
    # If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
    k4 = "k4+-="
    v4 = "+-=._:/"
    tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)
    
    # Configure the tags in the HTTP headers. 
    headers = dict()
    headers[OSS_OBJECT_TAGGING] = tagging
    
    # Initiate a multipart upload task. 
    # Specify the headers when you call the init_multipart_upload operation so that the tags are added to the object to be uploaded. 
    upload_id = bucket.init_multipart_upload(object_name, headers=headers).upload_id
    parts = []
    
    # Upload the parts one by one. 
    with open(filename, 'rb') as fileobj:
        part_number = 1
        offset = 0
        while offset < total_size:
            num_to_upload = min(part_size, total_size - offset)
            # The SizedFileAdapter(fileobj, size) method generates a new object and recalculates the position from which the append operation starts. 
            result = bucket.upload_part(object_name, upload_id, part_number,
                                        SizedFileAdapter(fileobj, num_to_upload))
            parts.append(PartInfo(part_number, result.etag))
    
            offset += num_to_upload
            part_number += 1
    
    # Complete the multipart upload task. 
    result = bucket.complete_multipart_upload(object_name, upload_id, parts)
    print('http response status: ', result.status)
    
    # Query the tags added to the object. 
    result = bucket.get_object_tagging(object_name)
    for key in result.tag_set.tagging_rule:
        print('tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))
    
    # Verify multipart upload. 
    with open(filename, 'rb') as fileobj:
        assert bucket.get_object(object_name).read() == fileobj.read()
  • Add tags to an object when you upload the object by using append upload

    The following code provides an example on how to add tags to an object when you upload the object by calling append_object:

    # -*- coding: utf-8 -*-
    
    import oss2
    from oss2.headers import OSS_OBJECT_TAGGING
    
    # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
    # Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'yourEndpoint', 'examplebucket')
    # Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
    object_name = 'exampledir/exampleobject.txt'
    
    # Configure the tagging string. 
    tagging = "k1=v1&k2=v2&k3=v3"
    
    # If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
    k4 = "k4+-="
    v4 = "+-=._:/"
    tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)
    
    # Configure the tags in the HTTP headers. 
    headers = dict()
    headers[OSS_OBJECT_TAGGING] = tagging
    
    # Append the object. Specify the headers when you call the append_object operation so that the tags are added to the object. 
    # Only the tags configured when the object is appended for the first time are added to the object. 
    result = bucket.append_object(object_name, 0, '<yourContent>', headers=headers)
    
    # Query the tags added to the object. 
    result = bucket.get_object_tagging(object_name)
    for key in result.tag_set.tagging_rule:
        print('tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))
  • Add tags to an object when you upload the object by using resumable upload

    The following code provides an example on how to add tags to an object when you upload the object by calling resumable_upload:

    # -*- coding: utf-8 -*-
    
    import oss2
    from oss2.headers import OSS_OBJECT_TAGGING
    
    # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
    # Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'yourEndpoint', 'examplebucket')
    # Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
    object_name = 'exampledir/exampleobject.txt'
    # Specify the full path of the local file. By default, if you do not specify the path of the local file, the local file is uploaded from the path of the project to which the sample program belongs. 
    local_file = 'D:\\localpath\\examplefile.txt'
    
    # Configure the tagging string. 
    tagging = "k1=v1&k2=v2&k3=v3"
    
    # If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
    k4 = "k4+-="
    v4 = "+-=._:/"
    tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)
    
    # Configure the tags in the HTTP headers. 
    headers = dict()
    headers[OSS_OBJECT_TAGGING] = tagging
    
    # When the object length is greater than or equal to the value of the multipart_threshold parameter, multipart upload is used. The multipart_threshold parameter is optional. The default value of multipart_threshold is 10 MB. If you do not specify a directory by using the store parameter, the .py-oss-upload directory is created in the HOME directory to store the checkpoint information. 
    # Specify the headers when you call the resumable_upload operation so that the tags are added to the object to be uploaded. 
    oss2.resumable_upload(bucket, object_name, local_file, headers=headers)
    
    result = bucket.get_object_tagging(object_name)
    for key in result.tag_set.tagging_rule:
        print('object tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

Add tags to an uploaded object or modify the existing tags of the object

If an existing object has no tags or the added tags of the object do not meet your requirements, you can add tags to or modify the existing tags of the existing object.

The following code provides an example on how to add tags to or modify the existing tags of an existing object:

# -*- coding: utf-8 -*-

import oss2
from oss2.models import Tagging, TaggingRule

# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'yourEndpoint', 'examplebucket')
# Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
object_name = 'exampledir/exampleobject.txt'

# Create a tagging rule. 
rule = TaggingRule()
rule.add('key1', 'value1')
rule.add('key2', 'value2')

# Create a tag. 
tagging = Tagging(rule)

# Add the tag to the object. 
result = bucket.put_object_tagging(object_name, tagging)
# Query the HTTP status code. 
print('http response status:', result.status)

Add tags to or modify the existing tags of a specified version of an object

If versioning is enabled for the bucket that contains the object, you can specify the version ID of the object to add tags to or modify the existing tags of the specified version of the object.

The following code provides an example on how to add tags to or modify the existing tags of a specified version of an object:

Note For more information about how to obtain the version IDs of an object, see List objects.
# -*- coding: utf-8 -*-

import oss2
from oss2.models import Tagging

# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. Example: examplebucket. 
bucket = oss2.Bucket(auth, 'yourEndpoint', 'examplebucket')
# Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
object_name = 'exampledir/exampleobject.txt'
# Specify the version ID of the object. Example: CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****. 
version_id = 'CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****'

tagging = Tagging()
# Specify the key and value of the object tag. Example: the key is owner, and the value is John. 
tagging.tag_set.add('owner', 'John')
tagging.tag_set.add('type', 'document')

params = dict()
params['versionId'] = version_id

bucket.put_object_tagging(object_name, tagging, params=params)

Add tags to an object when you copy the object

You can configure one of the following tagging parameters when you copy an object. Default value: Copy. Valid values:
  • Copy: The tag of the source object is copied to the destination object.
  • Replace: The tag of the destination object is set to the tag specified in the request instead of the tag of the source object.

The following examples describe how to add tags to objects smaller than 1 GB in simple copy mode and larger than 1 GB in multipart copy mode:

  • Add tags to an object when you copy the object in simple copy mode

    The following code provides an example on how to add tags to an object smaller than 1 GB when you copy it by calling CopyObject:

    # -*- coding: utf-8 -*-
    
    import oss2
    from oss2.headers import OSS_OBJECT_TAGGING, OSS_OBJECT_TAGGING_COPY_DIRECTIVE
    
    # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
    # Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'yourEndpoint', 'examplebucket')
    # Specify the full path of the source object. Example: srcexampledir/exampleobject.txt. 
    src_object_name = 'srcexampledir/exampleobject.txt'
    # Specify the full path of the destination object. Example: destexampledir1/exampleobject.txt. 
    dest_object_name1 = 'destexampledir1/exampleobject.txt.'
    # Specify the full path of the destination object. Example: destexampledir2/exampleobject.txt. 
    dest_object_name2 = 'destexampledir2/exampleobject.txt.'
    
    # Configure the tagging string. 
    tagging = "k1=v1&k2=v2&k3=v3"
    
    # If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
    k4 = "k4+-="
    v4 = "+-=._:/"
    tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)
    
    # Set OSS_OBJECT_TAGGING_COPY_DIRECTIVE to COPY or keep the default value in the HTTP headers, so that the tags of the source object are added to the dest_object_name1 object. 
    headers=dict()
    headers[OSS_OBJECT_TAGGING_COPY_DIRECTIVE] = 'COPY'
    bucket.copy_object(bucket.bucket_name, src_object_name, dest_object_name1, headers=headers)
    
    # Set OSS_OBJECT_TAGGING_COPY_DIRECTIVE to REPLACE in the HTTP headers, so that the tags specified in OSS_OBJECT_TAGGING are added to the dest_object_name2 object. 
    headers[OSS_OBJECT_TAGGING_COPY_DIRECTIVE] = 'REPLACE'
    headers[OSS_OBJECT_TAGGING] = tagging
    bucket.copy_object(bucket.bucket_name, src_object_name, dest_object_name2, headers=headers)
    
    # Query the tags added to the src_object_name object. 
    result = bucket.get_object_tagging(src_object_name)
    for key in result.tag_set.tagging_rule:
        print('src tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))
    
    # Query the tags added to the dest_object_name1 object. The tags added to the dest_object_name1 object are the same as those of the src_object_name object. 
    result = bucket.get_object_tagging(dest_object_name1)
    for key in result.tag_set.tagging_rule:
        print('dest1 object tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))
    
    # Query the tags added to the dest_object_name2 object. The tags added to the dest_object_name2 object are those specified in headers[OSS_OBJECT_TAGGING]. 
    result = bucket.get_object_tagging(dest_object_name2)
    for key in result.tag_set.tagging_rule:
        print('dest2 object tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))
  • Add tags to an object when you copy the object in multipart copy mode

    The following code provides an example on how to add tags to an object larger than 1 GB when you copy it by calling MultipartUpload:

    # -*- coding: utf-8 -*-
    
    import os
    import oss2
    from oss2 import determine_part_size
    from oss2.models import PartInfo
    from oss2.headers import OSS_OBJECT_TAGGING
    
    # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
    # Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'yourEndpoint', 'examplebucket')
    # Specify the full path of the source object. Example: srcexampledir/exampleobject.txt. 
    src_object_name = 'srcexampledir/exampleobject.txt'
    # Specify the full path of the destination object. Example: destexampledir/exampleobject.txt. 
    dest_object_name = 'destexampledir/exampleobject.txt'
    
    # Obtain the size of the source object. 
    head_info = bucket.head_object(src_object_name)
    total_size = head_info.content_length
    print('src object size:', total_size)
    
    # Use the determine_part_size method to determine the size of each part. 
    part_size = determine_part_size(total_size, preferred_size=100 * 1024)
    print('part_size:', part_size)
    
    # Configure the tagging string. 
    tagging = "k1=v1&k2=v2&k3=v3"
    
    # If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
    k4 = "k4+-="
    v4 = "+-=._:/"
    tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)
    
    # Configure the tags in the HTTP headers. 
    headers = dict()
    headers[OSS_OBJECT_TAGGING] = tagging
    
    # Initiate a multipart copy task. 
    # Specify the headers when you call the init_multipart_upload operation so that the tags are added to the destination object. 
    upload_id = bucket.init_multipart_upload(dest_object_name, headers=headers).upload_id
    parts = []
    
    # Upload the parts one by one. 
    part_number = 1
    offset = 0
    while offset < total_size:
        num_to_upload = min(part_size, total_size - offset)
        end = offset + num_to_upload - 1;
        result = bucket.upload_part_copy(bucket.bucket_name, src_object_name, (offset, end), dest_object_name, upload_id, part_number)
        # Save the part information.
        parts.append(PartInfo(part_number, result.etag))
    
        offset += num_to_upload
        part_number += 1
    
    # Complete the multipart upload task. 
    result = bucket.complete_multipart_upload(dest_object_name, upload_id, parts)
    
    # Obtain the metadata of the destination object. 
    head_info = bucket.head_object(dest_object_name)
    
    # Query the size of the destination object. 
    dest_object_size = head_info.content_length
    print('dest object size:', dest_object_size)
    
    # Compare the size of the destination object with that of the source object. 
    assert dest_object_size == total_size
    
    # Query the tags of the source object. 
    result = bucket.get_object_tagging(src_object_name)
    for key in result.tag_set.tagging_rule:
        print('src tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))
    
    # Query the tags added to the destination object. 
    result = bucket.get_object_tagging(dest_object_name)
    for key in result.tag_set.tagging_rule:
        print('dest tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))                   

Add tags to a symbolic link object

The following code provides an example on how to add tags to a symbolic link object:

# -*- coding: utf-8 -*-

import oss2
from oss2.headers import OSS_OBJECT_TAGGING

# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. Example: examplebucket. 
bucket = oss2.Bucket(auth, 'yourEndpoint', 'examplebucket')
# Specify the full path of the destination object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name. 
object_name = 'exampledir/exampleobject.txt'
# Specify the full path of the symbolic link object. Example: shortcut/myobject.txt. 
symlink_name = 'shortcut/myobject.txt'

# Configure the tagging string. 
tagging = "k1=v1&k2=v2&k3=v3"

# If tags contain characters, you must encode the keys and values of the tags by using URL encoding. 
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# Configure the tags in the HTTP headers. 
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# Add a symbolic link to the object. 
# Specify the headers when you call the put_symlink operation so that the tags are added to the symbolic link object. 
result = bucket.put_symlink(object_name, symlink_name, headers=headers)
print('http response status: ', result.status)

# Query the tags added to the symbolic link object. 
result = bucket.get_object_tagging(symlink_name)
for key in result.tag_set.tagging_rule:
    print('tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))