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

  • 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 calling PutObject:

    const OSS = require('ali-oss')
    
    const client = new OSS({
      // Set yourRegion 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 the region to oss-cn-hangzhou. 
      region: 'yourRegion',
      // 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 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. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket. Example: examplebucket. 
      bucket: 'examplebucket',
    });
    
    // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
    const objectName = 'exampledir/exampleobject.txt'
    // Specify the full path of the local file. 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. 
    const localFilepath = 'D:\\localpath\\examplefile.txt'
    
    // Configure request headers. 
    const headers = {
      // Specify the key and value of the object tag. For example, set the key to owner and the value to John. 
      'x-oss-tagging': 'owner=John&type=document', 
    }
    
    client.put(objectName, localFilepath, {
      headers
    })
  • 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 MultipartUpload:

    const OSS = require('ali-oss')
    
    const client = new OSS({
      // Set yourRegion 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 the region to oss-cn-hangzhou. 
      region: 'yourRegion',
      // 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. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket. Example: examplebucket. 
      bucket: 'examplebucket',
    });
    
    // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
    const objectName = 'exampledir/exampleobject.txt'
    // Specify the full path of the local file. 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. 
    const localFilepath = 'D:\\localpath\\examplefile.txt'
    
    // Configure request headers. 
    const headers = {
      // Specify the key and value of the object tag. For example, set the key to owner and the value to John. 
      'x-oss-tagging': 'owner=John&type=document', 
    }
    
    
    async function setTag() {
      await client.multipartUpload(objectName, localFilepath, {
        // Specify the part size. Unit: byte. Each part except for the last part must be equal to or larger than 100 KB in size. 
        partSize: 100 * 1024,
        headers
      });
      const tag = await client.getObjectTagging(objectName);
      console.log(tag);
    }
    
    setTag()
  • 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 it by calling AppendObject:

    const OSS = require('ali-oss')
    
    const client = new OSS({
      // Set yourRegion 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 the region to oss-cn-hangzhou. 
      region: 'yourRegion',
      // 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. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket. Example: examplebucket. 
      bucket: 'examplebucket',
    });
    // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
    const objectName = 'exampledir/exampleobject.txt'
    // Specify the full path of the local file. 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. 
    const localFilepath = 'D:\\localpath\\examplefile.txt'
    
    // Configure request headers. 
    const headers = {
      // Specify the key and value of the object tag. For example, set the key to owner and the value to John. 
      'x-oss-tagging': 'owner=John&type=document',
    }
    
    
    // Upload the object. Tags are added to the object when you call AppendObject and specify the x-oss-tagging header. 
    // Only the tags set when the object is appended for the first time are added to the object. 
    async function setTag() {
      await client.append(objectName, localFilepath, {
        // Specify the part size. Unit: byte. Each part except for the last part must be equal to or larger than 100 KB in size. 
        partSize: 100 * 1024,
        headers
      });
      const tag = await client.getObjectTagging(objectName);
      console.log(tag);
    }
    
    
    setTag()
  • 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 it by calling MultipartUpload:

    const OSS = require('ali-oss')
    
    const client = new OSS({
      // Set yourRegion 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 the region to oss-cn-hangzhou. 
      region: 'yourRegion',
      // 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. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket. Example: examplebucket. 
      bucket: 'examplebucket',
    });
    
    // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
    const objectName = 'exampledir/exampleobject.txt'
    // Specify the full path of the local file. 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. 
    const localFilepath = 'D:\\localpath\\examplefile.txt'
    // Configure the checkpoint information. 
    let checkpoint;
    
    // Configure request headers. 
    const headers = {
      // Specify the key and value of the object tag. For example, set the key to owner and the value to John. 
      'x-oss-tagging': 'owner=John&type=document',
    }
    
    
    async function setTag() {
      await client.multipartUpload(objectName, localFilepath, {
        checkponit,
        async progress(percentage, cpt) {
          checkpoint = cpt;
        },
        headers
      });
      const tag = await client.getObjectTagging(objectName);
      console.log(tag);
    }
    
    setTag()

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:

const OSS = require('ali-oss')

const client = new OSS({
  // Set yourRegion 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 the region to oss-cn-hangzhou. 
  region: 'yourRegion',
  // 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. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the name of the bucket. Example: examplebucket. 
  bucket: 'examplebucket',
});

// Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
const objectName = 'exampledir/exampleobject.txt'
// Specify the key and value of the object tag. For example, set the key to owner and the value to John. 
const tag = { owner: 'John', type: 'document' };

async function putObjectTagging(objectName, tag) {
  try {
    const result = await client.putObjectTagging(objectName, tag);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

putObjectTagging(objectName, tag)

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.
const OSS = require('ali-oss')

const client = new OSS({
  // Set yourRegion 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 the region to oss-cn-hangzhou. 
  region: 'yourRegion',
  // 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. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the name of the bucket. Example: examplebucket. 
  bucket: 'examplebucket',
});

// Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
const objectName = 'exampledir/exampleobject.txt'
// Specify the key and value of the object tag. For example, set the key to owner and the value to John. 
const tag = { owner: 'John', type: 'document' };
// Specify the version ID of the object. 
const versionId = 'CAEQIRiBgMDqvPqA3BciIDJhMjE4MWZkN2ViYTRmYzJhZjkxMzk2YWM2NjJk****'

async function putObjectTagging(objectName, tag) {
  try {
    const options = {
      versionId
    };
    const result = await client.putObjectTagging(objectName, tag, options);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

putObjectTagging(objectName, tag)

Add tags to an object when you copy the object

You can use the one of following methods to configure the object tagging when you copy an object:
  • 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 by using simple copy

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

    const OSS = require('ali-oss')
    
    const client = new OSS({
      // Set yourRegion 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 the region to oss-cn-hangzhou. 
      region: 'yourRegion',
      // 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. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket. Example: examplebucket. 
      bucket: 'examplebucket',
    });
    
    // Specify the full path of the source object. The full path of the object cannot contain the bucket name. Example: srcexampledir/exampleobject.txt. 
    const sourceObjectName = 'srcexampledir/exampleobject.txt';
    // Specify the full path of the destination object. The full path of the object cannot contain the bucket name. Example: destexampledir/exampleobject.txt. 
    const targetObjectName = 'destexampledir/exampleobject.txt';
    
    // Configure request headers. 
    const headers = {
      // Specify the key and value of the object tag. For example, set the key to owner and the value to John. 
      'x-oss-tagging': 'owner=John&type=document',
      // Specifies how to set tags for the destination object. Valid values: Copy and Replace. Copy is the default value and indicates that the tags of the source object are copied to the destination object. Replace indicates that the tags specified in the request are added to the destination object. 
      'x-oss-tagging-directive': 'Replace' 
    }
    
    async function setTag() {
      const result = await client.copy(targetObjectName, sourceObjectName, {
        headers
      });
      const tag = await client.getObjectTagging(targetObjectName)
      console.log(tag)
    }
    
    setTag()
  • Add tags to an object when you copy the object by using multipart copy

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

    const OSS = require('ali-oss')
    
    const client = new OSS({
      // Set yourRegion 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 the region to oss-cn-hangzhou. 
      region: 'yourRegion',
      // 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. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket. Example: examplebucket. 
      bucket: 'examplebucket'
    });
    
    
    // Specify the full path of the source object. The full path of the object cannot contain the bucket name. Example: srcexampledir/exampleobject.txt. 
    const sourceObjectName = 'srcexampledir/exampleobject.txt'
    // Specify the full path of the destination object. The full path of the object cannot contain the bucket name. Example: destexampledir/exampleobject.txt. 
    const targetObjectName = 'destexampledir/exampleobject.txt'
    
    // Configure request headers. 
    const headers = {
      // Specify the key and value of the object tag. For example, set the key to owner and the value to John. 
      'x-oss-tagging': 'owner=John&type=document',
    }
    
    async function setTag() {
      await client.multipartUploadCopy(targetObjectName, {
        sourceKey: sourceObjectName,
        sourceBucketName: 'examplebucket'
      }, {
        // Specify the part size. Unit: byte. Each part except for the last part must be equal to or larger than 100 KB in size. 
        partSize: 256 * 1024,
        headers
      });
      const tag = await client.getObjectTagging(targetObjectName)
      console.log(tag)
    }
    
    setTag()

Add tags to a symbolic link

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

const OSS = require('ali-oss')

const client = new OSS({
  // Set yourRegion 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 the region to oss-cn-hangzhou. 
  region: 'yourRegion',
  // 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. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the name of the bucket. Example: examplebucket. 
  bucket: 'examplebucket',
});
// Specify the full path of the symbolic link. Example: shortcut/myobject.txt. 
const symLink = "shortcut/myobject.txt";
// Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
const targetObjectName = 'exampledir/exampleobject.txt'
                
// Configure request headers. 
const headers = {
  // Specify the key and value of the object tag. For example, set the key to owner and the value to John. 
  'x-oss-tagging': 'owner=John&type=document',
}

async function setTag() {
  await client.putSymlink(symLink, targetObjectName, {
    storageClass: 'IA',
    meta: {
      uid: '1',
      slus: 'test.html'
    },
    headers
  });
  const tag = await client.getObjectTagging(targetObjectName)
  console.log(tag)
}

setTag()

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.