Object Storage Service (OSS) allows you to configure object tags to classify objects. Tags allow you to configure lifecycle rules and access control lists (ACLs) for objects that have the same tag.

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 object tags, see PutObjectTagging.
  • To add tags to an object, you must have permissions to call the PutObjectTagging operation.

    You can create a custom policy by using scripts to grant the permissions to RAM users. For more information, see Attach a custom policy to a RAM user.

  • The Last-Modified value of an object is not updated when the 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 up to 128 characters in length. A tag value can be up to 256 characters in length.
  • Tag keys and tag values are case-sensitive.
  • The key and the 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 special characters, you can encode the keys and the 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 Object tagging.

Add tags to an object when you upload the object

The following examples describe how to add tags to objects in simple upload, multipart upload, append upload, and resumable upload:

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

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

    import com.aliyun.oss.ClientException;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.OSSClientBuilder;
    import com.aliyun.oss.OSSException;
    import com.aliyun.oss.model.*;
    import java.io.ByteArrayInputStream;
    import java.util.HashMap;
    import java.util.Map;
    
    public class Demo {
        public static void main(String[] args) throws Exception {
            // In this example, the endpoint of the China (Hangzhou) region is used. Specify the actual endpoint. 
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
            // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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. 
            String accessKeyId = "yourAccessKeyId";
            String accessKeySecret = "yourAccessKeySecret";
            // Specify the name of the bucket. Example: examplebucket. 
            String bucketName = "examplebucket";
            // Specify the full path of the object, not including the bucket name. Example: exampledir/exampleobject.txt. 
            String objectName = "exampledir/exampleobject.txt";
    
            // Create an OSSClient instance. 
            OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
            try {
                Map<String, String> tags = new HashMap<String, String>();
                // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
                tags.put("owner", "John");
                tags.put("type", "document");
    
                // Configure the tags in the HTTP header. 
                ObjectMetadata metadata = new ObjectMetadata();
                metadata.setObjectTagging(tags);
    
                // Upload the object and add tags to it. 
                String content = "<yourtContent>";
                ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()), metadata);
            } catch (OSSException oe) {
                System.out.println("Caught an OSSException, which means your request made it to OSS, "
                        + "but was rejected with an error response for some reason.");
                System.out.println("Error Message:" + oe.getErrorMessage());
                System.out.println("Error Code:" + oe.getErrorCode());
                System.out.println("Request ID:" + oe.getRequestId());
                System.out.println("Host ID:" + oe.getHostId());
            } catch (ClientException ce) {
                System.out.println("Caught an ClientException, which means the client encountered "
                        + "a serious internal problem while trying to communicate with OSS, "
                        + "such as not being able to access the network.");
                System.out.println("Error Message:" + ce.getMessage());
            } finally {
                if (ossClient != null) {
                    ossClient.shutdown();
                }
            }
        }
    }
  • Add tags to an object when you upload it by using multipart upload

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

    import com.aliyun.oss.ClientException;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.OSSClientBuilder;
    import com.aliyun.oss.OSSException;
    import com.aliyun.oss.model.*;
    import java.io.*;
    import java.util.*;
    
    public class Demo {
        public static void main(String[] args) throws Exception {
            // In this example, the endpoint of the China (Hangzhou) region is used. Specify the actual endpoint. 
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
            // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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. 
            String accessKeyId = "yourAccessKeyId";
            String accessKeySecret = "yourAccessKeySecret";
            // Specify the name of the bucket. Example: examplebucket. 
            String bucketName = "examplebucket";
            // Specify the full path of the object, not including the bucket name. Example: exampledir/exampleobject.txt. 
            String objectName = "exampledir/exampleobject.txt";
            // Specify the full path of the local file that you want to upload. If you do not specify the full path of the local file, the local file is uploaded from the path of the project to which the sample program belongs. 
            String localFile = "D:\\localpath\\examplefile.txt";
    
            // Create an OSSClient instance. 
            OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
            try {
                /*
                   Step 1: Initialize a multipart upload task. 
                */
                // Configure the tags in the HTTP header. 
                Map<String, String> tags = new HashMap<String, String>();
                // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
                tags.put("owner", "John");
                tags.put("type", "document");
    
                ObjectMetadata metadata = new ObjectMetadata();
                metadata.setObjectTagging(tags);
    
                // Send an InitiateMultipartUploadRequest request and add tags to the object. 
                InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, objectName, metadata);
                InitiateMultipartUploadResult result = ossClient.initiateMultipartUpload(request);
                // Obtain the upload ID, which uniquely identifies the multipart upload task. The upload ID can be used to query or cancel a multipart upload task. 
                String uploadId = result.getUploadId();
    
                /*
                   Step 2: Upload parts. 
                */
                // partETags is the set of PartETags. A PartETag consists of an ETag and a part number. 
                List<PartETag> partETags =  new ArrayList<PartETag>();
                // Calculate the total number of parts to upload. 
                final long partSize = 1 x 1024 x 1024L; // Set the part size to 1 MB. 
                final File sampleFile = new File(localFile);
                long fileLength = sampleFile.length();
                int partCount = (int) (fileLength / partSize);
                if (fileLength % partSize != 0) {
                    partCount++;
                }
                // Upload each part until all parts are uploaded. 
                for (int i = 0; i < partCount; i++) {
                    long startPos = i * partSize;
                    long curPartSize = (i + 1 == partCount) ? (fileLength - startPos) : partSize;
                    InputStream instream = null;
                    try {
                        instream = new FileInputStream(sampleFile);
                        // Skip the parts that have been uploaded. 
                        instream.skip(startPos);
                    } catch (FileNotFoundException e) {
                        e.printStackTrace();
                    } catch (IOException e) {
                        e.printStackTrace();
                    }
                    UploadPartRequest uploadPartRequest = new UploadPartRequest();
                    uploadPartRequest.setBucketName(bucketName);
                    uploadPartRequest.setKey(objectName);
                    uploadPartRequest.setUploadId(uploadId);
                    uploadPartRequest.setInputStream(instream);
                    // Set the size available for each part. Each part except the last part must be equal to or greater than 100 KB. 
                    uploadPartRequest.setPartSize(curPartSize);
                    // Set part numbers. Each part is configured with a part number. The number ranges from 1 to 10000. If you configure a part number that exceeds this range, OSS returns an InvalidArgument error code. 
                    uploadPartRequest.setPartNumber( i + 1);
                    // Parts are not necessarily uploaded in order. They can be uploaded from different OSS clients. OSS sorts the parts based on their part numbers and combines them to into a complete object. 
                    UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
                    // After you upload a part, OSS returns a result that contains a PartETag. The PartETag is stored in partETags. 
                    partETags.add(uploadPartResult.getPartETag());
                }
    
                /* Step 3: Complete multipart upload. 
                 */
                // PartETags stored in partEtags are sorted in ascending order by part numbers. 
                Collections.sort(partETags, new Comparator<PartETag>() {
                    public int compare(PartETag p1, PartETag p2) {
                        return p1.getPartNumber() - p2.getPartNumber();
                    }
                });
                // You must provide all valid PartETags when you perform this operation. OSS verifies the validity of all parts one by one after it receives PartETags. After all parts are verified, OSS combines these parts into a complete object. 
                CompleteMultipartUploadRequest completeMultipartUploadRequest =
                        new CompleteMultipartUploadRequest(bucketName, objectName, uploadId, partETags);
                ossClient.completeMultipartUpload(completeMultipartUploadRequest);
    
                // View the tags added to the object. 
                TagSet tagSet = ossClient.getObjectTagging(bucketName, objectName);
                Map<String, String> getTags = tagSet.getAllTags();
                System.out.println("object tagging: "+ getTags.toString());
            } catch (OSSException oe) {
                System.out.println("Caught an OSSException, which means your request made it to OSS, "
                        + "but was rejected with an error response for some reason.");
                System.out.println("Error Message:" + oe.getErrorMessage());
                System.out.println("Error Code:" + oe.getErrorCode());
                System.out.println("Request ID:" + oe.getRequestId());
                System.out.println("Host ID:" + oe.getHostId());
            } catch (ClientException ce) {
                System.out.println("Caught an ClientException, which means the client encountered "
                        + "a serious internal problem while trying to communicate with OSS, "
                        + "such as not being able to access the network.");
                System.out.println("Error Message:" + ce.getMessage());
            } finally {
                if (ossClient != null) {
                    ossClient.shutdown();
                }
            }
        }
    }
  • Add tags to an object when you upload it by using append upload

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

    import com.aliyun.oss.ClientException;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.OSSClientBuilder;
    import com.aliyun.oss.OSSException;
    import com.aliyun.oss.model.*;
    import java.io.*;
    import java.util.*;
    
    public class Demo {
        public static void main(String[] args) throws Exception {
            // In this example, the endpoint of the China (Hangzhou) region is used. Specify the actual endpoint. 
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
            // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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. 
            String accessKeyId = "yourAccessKeyId";
            String accessKeySecret = "yourAccessKeySecret";
            // Specify the name of the bucket. Example: examplebucket. 
            String bucketName = "examplebucket";
            // Specify the full path of the object, not including the bucket name. Example: exampledir/exampleobject.txt. 
            String objectName = "exampledir/exampleobject.txt";
    
            // Create an OSSClient instance. 
            OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
            try {
                String content1 = "Hello OSS A \n";
                String content2 = "Hello OSS B \n";
                String content3 = "Hello OSS C \n";
    
                Map<String, String> tags = new HashMap<String, String>();
                // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
                tags.put("owner", "John");
                tags.put("type", "document");
    
                ObjectMetadata meta = new ObjectMetadata();
                // Configure tags for the object that you want to upload. 
                meta.setObjectTagging(tags);
                // Specify the type of content that you want to upload. 
                meta.setContentType("text/plain");
    
                // Configure parameters by using AppendObjectRequest. 
                AppendObjectRequest appendObjectRequest = new AppendObjectRequest(bucketName, objectName, new ByteArrayInputStream(content1.getBytes()), meta);
    
                // Configure a single parameter by using AppendObjectRequest. 
                //appendObjectRequest.setBucketName(bucketName);
                //appendObjectRequest.setKey(objectName);
                // Specify the content that you want to append. Two types of content are available: InputStream and File. The following code provides an example on how to specify the content of the InputStream type: 
                //appendObjectRequest.setInputStream(new ByteArrayInputStream(content1.getBytes()));
                // Specify the content that you want to append. Two types of content are available: InputStream and File. The following code provides an example on how to specify the content of the File type: 
                // Specify the full path of the local file that you want to upload. If you do not specify the full path of the local file, the local file is uploaded from the path of the project to which the sample program belongs. 
                //appendObjectRequest.setFile(new File("D:\\localpath\\examplefile.txt"));
                // Specify the object metadata. You can specify the metadata of an object only when you perform the append operation on the object for the first time. 
                //appendObjectRequest.setMetadata(meta);
    
                // Start the first append. Only the tags configured when the object is appended for the first time are added to the object. 
                // Configure the position from which the append operation starts. 
                appendObjectRequest.setPosition(0L);
                AppendObjectResult appendObjectResult = ossClient.appendObject(appendObjectRequest);
                // Calculate the CRC-64 of the object. The value is calculated based on the ECMA-182 specification. 
                System.out.println(appendObjectResult.getObjectCRC());
    
                // Start the second append. 
                // NextPosition specifies the position from which the next append operation starts, which is the current length of the object. 
                appendObjectRequest.setPosition(appendObjectResult.getNextPosition());
                appendObjectRequest.setInputStream(new ByteArrayInputStream(content2.getBytes()));
                appendObjectResult = ossClient.appendObject(appendObjectRequest);
    
                // Start the third append. 
                appendObjectRequest.setPosition(appendObjectResult.getNextPosition());
                appendObjectRequest.setInputStream(new ByteArrayInputStream(content3.getBytes()));
                appendObjectResult = ossClient.appendObject(appendObjectRequest);
    
                // View the tags added to the uploaded object. 
                TagSet tagSet = ossClient.getObjectTagging(bucketName, objectName);
                Map<String, String> getTags = tagSet.getAllTags();
                System.out.println("object tagging: "+ getTags.toString());
            } catch (OSSException oe) {
                System.out.println("Caught an OSSException, which means your request made it to OSS, "
                        + "but was rejected with an error response for some reason.");
                System.out.println("Error Message:" + oe.getErrorMessage());
                System.out.println("Error Code:" + oe.getErrorCode());
                System.out.println("Request ID:" + oe.getRequestId());
                System.out.println("Host ID:" + oe.getHostId());
            } catch (ClientException ce) {
                System.out.println("Caught an ClientException, which means the client encountered "
                        + "a serious internal problem while trying to communicate with OSS, "
                        + "such as not being able to access the network.");
                System.out.println("Error Message:" + ce.getMessage());
            } finally {
                if (ossClient != null) {
                    ossClient.shutdown();
                }
            }
        }
    }
  • Add tags to an object when you upload it by using resumable upload

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

    import com.aliyun.oss.ClientException;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.OSSClientBuilder;
    import com.aliyun.oss.OSSException;
    import com.aliyun.oss.model.*;
    import java.util.*;
    
    public class Demo {
        public static void main(String[] args) throws Throwable {
            // In this example, the endpoint of the China (Hangzhou) region is used. Specify the actual endpoint. 
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
            // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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. 
            String accessKeyId = "yourAccessKeyId";
            String accessKeySecret = "yourAccessKeySecret";
            // Specify the name of the bucket. Example: examplebucket. 
            String bucketName = "examplebucket";
            // Specify the full path of the object, not including the bucket name. Example: exampledir/exampleobject.txt. 
            String objectName = "exampledir/exampleobject.txt";
            // Specify the full path of the local file that you want to upload. If you do not specify the full path of the local file, the local file is uploaded from the path of the project to which the sample program belongs. 
            String localFile = "D:\\localpath\\examplefile.txt";
            // Specify the file that records the upload result of each part. Example: D:\localpath\uploadFile.ucp. 
            String yourCheckpointFile = "D:\\localpath\\uploadFile.ucp";
    
            // Create an OSSClient instance. 
            OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
            try {
                // Configure the tags to be added to the object. 
                Map<String, String> tags = new HashMap<String, String>();
                // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
                tags.put("owner", "John");
                tags.put("type", "document");
    
                ObjectMetadata meta = new ObjectMetadata();
                // Specify the type of content that you want to upload. 
                meta.setContentType("text/plain");
                // Add the tags to the object. 
                meta.setObjectTagging(tags);
    
                // Configure parameters by using UploadFileRequest. 
                UploadFileRequest uploadFileRequest = new UploadFileRequest(bucketName,objectName);
    
                // Configure a single parameter by using UploadFileRequest. 
                // Specify the bucket name. 
                //uploadFileRequest.setBucketName(bucketName);
                // Specify the full path of the object, not including the bucket name. 
                //uploadFileRequest.setKey(objectName);
                // Specify the local file that you want to upload. 
                uploadFileRequest.setUploadFile(localFile);
                // Specify the number of threads for the resumable upload task. Default value: 1. 
                uploadFileRequest.setTaskNum(5);
                // Specify the size of each part to upload. Valid values: 100 KB to 5 GB. The default size of each part is calculated based on the following formula: Default size of each part = Object size/10,000. 
                uploadFileRequest.setPartSize(1 * 1024 * 1024);
                // Enable resumable upload. By default, resumable upload is disabled. 
                uploadFileRequest.setEnableCheckpoint(true);
                // Specify the file that records the upload result of each part. You need to configure this parameter when you enable resumable upload. This file stores progress information. If a part upload fails, it can be continued based on the progress information recorded in this file. After the local file is uploaded, the file that stores progress information is deleted. By default, this file shares the same directory (uploadFile.ucp) as the file you want to upload. 
                uploadFileRequest.setCheckpointFile(yourCheckpointFile);
                // Configure object metadata. 
                uploadFileRequest.setObjectMetadata(meta);
                // Configure callback after successful uploads. The parameter type is Callback. 
                //uploadFileRequest.setCallback("yourCallbackEvent");
    
                // Start the resumable upload task and configure the tags to be added to the object. 
                ossClient.uploadFile(uploadFileRequest);
    
                // View the tags added to the object. 
                TagSet tagSet = ossClient.getObjectTagging(bucketName, objectName);
                Map<String, String> getTags = tagSet.getAllTags();
                System.out.println("object tagging: "+ getTags.toString());
            } catch (OSSException oe) {
                System.out.println("Caught an OSSException, which means your request made it to OSS, "
                        + "but was rejected with an error response for some reason.");
                System.out.println("Error Message:" + oe.getErrorMessage());
                System.out.println("Error Code:" + oe.getErrorCode());
                System.out.println("Request ID:" + oe.getRequestId());
                System.out.println("Host ID:" + oe.getHostId());
            } catch (ClientException ce) {
                System.out.println("Caught an ClientException, which means the client encountered "
                        + "a serious internal problem while trying to communicate with OSS, "
                        + "such as not being able to access the network.");
                System.out.println("Error Message:" + ce.getMessage());
            } finally {
                if (ossClient != null) {
                    ossClient.shutdown();
                }
            }
        }
    }

Add tags to or modify the tags of an existing 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 tags of the existing object.

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

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import java.util.*;

public class Demo {
    public static void main(String[] args) throws Throwable {
        // In this example, the endpoint of the China (Hangzhou) region is used. Specify the actual endpoint. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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. 
        String accessKeyId = "yourAccessKeyId";
        String accessKeySecret = "yourAccessKeySecret";
        // Specify the name of the bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the full path of the object, not including the bucket name. Example: exampledir/exampleobject.txt. 
        String objectName = "exampledir/exampleobject.txt";

        // Create an OSSClient instance. 
        OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

        try {
            Map<String, String> tags = new HashMap<String, String>();
            // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
            tags.put("owner", "John");
            tags.put("type", "document");

            // Add tags to the object. 
            ossClient.setObjectTagging(bucketName, objectName, tags);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

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

If versioning is enabled for the bucket, you can add tags to or modify the tags of a specified version of an object by specifying the version ID of the object.

The following code provides an example on how to add tags to or modify the 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.
import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.SetObjectTaggingRequest;
import java.util.*;

public class Demo {
    public static void main(String[] args) throws Throwable {
        // In this example, the endpoint of the China (Hangzhou) region is used. Specify the actual endpoint. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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. 
        String accessKeyId = "yourAccessKeyId";
        String accessKeySecret = "yourAccessKeySecret";
        // Specify the name of the bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the full path of the object, not including the bucket name. Example: exampledir\exampleobject.txt. 
        String objectName = "exampledir/exampleobject.txt";
        // Specify the version ID of the object. Example: CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****. 
        String versionId = "CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****";

        // Create an OSSClient instance. 
        OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

        try {
            Map<String, String> tags = new HashMap<String, String>(1);
            // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
            tags.put("owner", "John");
            tags.put("type", "document");

            SetObjectTaggingRequest setObjectTaggingRequest = new SetObjectTaggingRequest(bucketName, objectName, tags);
            setObjectTaggingRequest.setVersionId(versionId);
            ossClient.setObjectTagging(setObjectTaggingRequest);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

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 an object 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 simply copy mode

    The following code provides an example on how to add tags to an object smaller than 1 GB when you copy it in simply copy mode:

    import com.aliyun.oss.ClientException;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.OSSClientBuilder;
    import com.aliyun.oss.OSSException;
    import com.aliyun.oss.internal.OSSHeaders;
    import com.aliyun.oss.model.CopyObjectRequest;
    import com.aliyun.oss.model.CopyObjectResult;
    import com.aliyun.oss.model.TagSet;
    import java.util.*;
    
    public class Demo {
        public static void main(String[] args) throws Throwable {
            // In this example, the endpoint of the China (Hangzhou) region is used. Specify the actual endpoint. 
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
            // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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. 
            String accessKeyId = "yourAccessKeyId";
            String accessKeySecret = "yourAccessKeySecret";
            // Specify the name of the source bucket. Example: srcexamplebucket. 
            String sourceBucketName = "srcexamplebucket";
            // Specify the full path of the object in the source bucket, not including the bucket name. Example: srcexampledir/exampleobject.txt. 
            String sourceObjectName = "srcexampledir/exampleobject.txt";
            // Specify the name of the destination bucket. Example: destexamplebucket. 
            String destinationBucketName = "destexamplebucket";
            // Specify the full path of the object in the destination bucket, not including the bucket name. Example: destexampledir/exampleobject.txt. 
            String destinationObjectName = "destexampledir/exampleobject.txt";
    
            // Create an OSSClient instance. 
            OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
            try {
                // Create a CopyObjectRequest object. 
                CopyObjectRequest copyObjectRequest = new CopyObjectRequest(sourceBucketName, sourceObjectName, destinationBucketName, destinationObjectName);
    
                // Configure the tags to be added to the destination object. If the headers are not configured, the tags of the source object are added to the destination object by default. 
                Map<String, String> headers = new HashMap<String, String>();
                headers.put(OSSHeaders.COPY_OBJECT_TAGGING_DIRECTIVE, "REPLACE");
                headers.put(OSSHeaders.OSS_TAGGING, "key1=value1&key2=value2");
                copyObjectRequest.setHeaders(headers);
    
                // Copy the object. 
                CopyObjectResult result = ossClient.copyObject(copyObjectRequest);
                System.out.println("ETag: " + result.getETag() + " LastModified: " + result.getLastModified());
    
                // View the tags added to the destination object. 
                TagSet tagSet = ossClient.getObjectTagging(destinationBucketName, destinationObjectName);
                Map<String, String> getTags = tagSet.getAllTags();
                System.out.println("dest object tagging: "+ getTags.toString());
            } catch (OSSException oe) {
                System.out.println("Caught an OSSException, which means your request made it to OSS, "
                        + "but was rejected with an error response for some reason.");
                System.out.println("Error Message:" + oe.getErrorMessage());
                System.out.println("Error Code:" + oe.getErrorCode());
                System.out.println("Request ID:" + oe.getRequestId());
                System.out.println("Host ID:" + oe.getHostId());
            } catch (ClientException ce) {
                System.out.println("Caught an ClientException, which means the client encountered "
                        + "a serious internal problem while trying to communicate with OSS, "
                        + "such as not being able to access the network.");
                System.out.println("Error Message:" + ce.getMessage());
            } finally {
                if (ossClient != null) {
                    ossClient.shutdown();
                }
            }
        }
    }
                        
  • 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 in multipart copy mode:

    import com.aliyun.oss.ClientException;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.OSSClientBuilder;
    import com.aliyun.oss.OSSException;
    import com.aliyun.oss.model.*;
    import java.util.*;
    
    public class Demo {
        public static void main(String[] args) throws Throwable {
            // In this example, the endpoint of the China (Hangzhou) region is used. Specify the actual endpoint. 
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
            // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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. 
            String accessKeyId = "yourAccessKeyId";
            String accessKeySecret = "yourAccessKeySecret";
            // Specify the name of the source bucket. Example: srcexamplebucket. 
            String sourceBucketName = "srcexamplebucket";
            // Specify the full path of the object in the source bucket, not including the bucket name. Example: srcexampledir/exampleobject.txt. 
            String sourceObjectName = "srcexampledir/exampleobject.txt";
            // Specify the name of the destination bucket. Example: destexamplebucket. 
            String destinationBucketName = "destexamplebucket";
            // Specify the full path of the object in the destination bucket, not including the bucket name. Example: destexampledir/exampleobject.txt. 
            String destinationObjectName = "destexampledir/exampleobject.txt";
    
            // Create an OSSClient instance. 
            OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
            try {
                ObjectMetadata objectMetadata = ossClient.getObjectMetadata(sourceBucketName, sourceObjectName);
                // Query the size of the object to copy. 
                long contentLength = objectMetadata.getContentLength();
                // Set the size of each part to 10 MB. 
                long partSize = 1024 * 1024 * 10;
                // Calculate the total number of parts. 
                int partCount = (int) (contentLength / partSize);
                if (contentLength % partSize != 0) {
                    partCount++;
                }
    
                System.out.println("total part count:" + partCount);
    
                // Configure the tags in the HTTP header. 
                Map<String, String> tags2 = new HashMap<String, String>();
                // Specify the key and value of the object tag. For example, set the key to owner and the value to Lily. 
                tags2.put("owner", "Lily");
                tags2.put("type", "document");
    
                ObjectMetadata metadata = new ObjectMetadata();
                metadata.setObjectTagging(tags2);
    
                // Initiate a multipart copy task and configure the tags to be added to the destination object. 
                InitiateMultipartUploadRequest initiateMultipartUploadRequest = new InitiateMultipartUploadRequest(destinationBucketName, destinationObjectName, metadata);
                InitiateMultipartUploadResult initiateMultipartUploadResult = ossClient.initiateMultipartUpload(initiateMultipartUploadRequest);
                String uploadId = initiateMultipartUploadResult.getUploadId();
    
                // Start the multipart copy task. 
                List<PartETag> partETags = new ArrayList<PartETag>();
                for (int i = 0; i < partCount; i++) {
                    // Calculate the size of each part. 
                    long skipBytes = partSize * i;
                    long size = partSize < contentLength - skipBytes ? partSize : contentLength - skipBytes;
    
                    // Create an UploadPartCopyRequest object. You can call the UploadPartCopyRequest operation to specify conditions. 
                    UploadPartCopyRequest uploadPartCopyRequest =
                            new UploadPartCopyRequest(sourceBucketName, sourceObjectName, destinationBucketName, destinationObjectName);
                    uploadPartCopyRequest.setUploadId(uploadId);
                    uploadPartCopyRequest.setPartSize(size);
                    uploadPartCopyRequest.setBeginIndex(skipBytes);
                    uploadPartCopyRequest.setPartNumber(i + 1);
    
                    UploadPartCopyResult uploadPartCopyResult = ossClient.uploadPartCopy(uploadPartCopyRequest);
                    // Store the returned PartETags in partETags. 
                    partETags.add(uploadPartCopyResult.getPartETag());
                }
    
                // Complete the multipart copy task. 
                CompleteMultipartUploadRequest completeMultipartUploadRequest = new CompleteMultipartUploadRequest(
                        destinationBucketName, destinationObjectName, uploadId, partETags);
                CompleteMultipartUploadResult completeMultipartUploadResult = ossClient.completeMultipartUpload(completeMultipartUploadRequest);
                System.out.println("versionId: "+completeMultipartUploadResult.getVersionId());
    
                // View the tags of the source object. 
                TagSet tagSet = ossClient.getObjectTagging(sourceBucketName, sourceObjectName);
                Map<String, String> getTags = tagSet.getAllTags();
                System.out.println("src object tagging: "+ getTags.toString());
    
                // View the tags added to the destination object. 
                tagSet = ossClient.getObjectTagging(destinationBucketName, destinationObjectName);
                getTags = tagSet.getAllTags();
                System.out.println("dest object tagging: "+ getTags.toString());
            } catch (OSSException oe) {
                System.out.println("Caught an OSSException, which means your request made it to OSS, "
                        + "but was rejected with an error response for some reason.");
                System.out.println("Error Message:" + oe.getErrorMessage());
                System.out.println("Error Code:" + oe.getErrorCode());
                System.out.println("Request ID:" + oe.getRequestId());
                System.out.println("Host ID:" + oe.getHostId());
            } catch (ClientException ce) {
                System.out.println("Caught an ClientException, which means the client encountered "
                        + "a serious internal problem while trying to communicate with OSS, "
                        + "such as not being able to access the network.");
                System.out.println("Error Message:" + ce.getMessage());
            } finally {
                if (ossClient != null) {
                    ossClient.shutdown();
                }
            }
        }
    }

Add tags to a symbolic link

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

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;
import java.util.*;

public class Demo {
    public static void main(String[] args) throws Throwable {
        // In this example, the endpoint of the China (Hangzhou) region is used. Specify the actual endpoint. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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. 
        String accessKeyId = "yourAccessKeyId";
        String accessKeySecret = "yourAccessKeySecret";
        // Specify the name of the bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the full path of the symbolic link. Example: shortcut/myobject.txt. 
        String symLink = "shortcut/myobject.txt";
        // Specify the full path of the object, not including the bucket name. Example: exampledir/exampleobject.txt. 
        String destinationObjectName = "exampledir/exampleobject.txt";

        // Create an OSSClient instance. 
        OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

        try {
            // Configure the tags to be added to the symbolic link. 
            Map<String, String> tags = new HashMap<String, String>();
            // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
            tags.put("owner", "John");
            tags.put("type", "document");

            // Create metadata for the object to upload. 
            ObjectMetadata metadata = new ObjectMetadata();
            metadata.setObjectTagging(tags);

            // Create a request to create the symbolic link. 
            CreateSymlinkRequest createSymlinkRequest = new CreateSymlinkRequest(bucketName, symLink, destinationObjectName);

            // Configure the metadata. 
            createSymlinkRequest.setMetadata(metadata);

            // Create the symbolic link. 
            ossClient.createSymlink(createSymlinkRequest);

            // View the tags added to the symbolic link. 
            TagSet tagSet = ossClient.getObjectTagging(bucketName, symLink);
            Map<String, String> getTags = tagSet.getAllTags();
            System.out.println("symLink tagging: "+ getTags.toString());
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

References

  • For more information about the complete sample code that is used to configure object tagging, visit GitHub.
  • For more information about the API operation that you can call to configure object tagging, see PutObjectTagging.