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

    You can configure a custom policy in the Script configuration mode to grant the permissions to a specific RAM user. For more information, see Assign a custom RAM policy for a RAM user.

  • 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 it

  • Add tags to an object when you upload it in simple upload

    The following code provides an example on how to add tags to an object when you upload it 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 your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
      region: 'yourRegion',
      // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access Object Storage Service (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 operations and maintenance. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket in which the object you want to access is stored. Example: examplebucket. 
      bucket: 'examplebucket',
    });
    
    // Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain bucket names. 
    const objectName = 'exampledir/exampleobject.txt'
    // Specify the full path of the local file to upload. Example: D:\\localpath\\examplefile.txt. 
    // By default, if you set this parameter to the name of a local file such as examplefile.txt without specifying the local path, the local file is uploaded from the local 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 the value of the object tag. Example: the key is owner, and the value is John. 
      'x-oss-tagging': 'owner=John&type=document', 
    }
    
    client.put(objectName, localFilepath, {
      headers
    })
  • 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 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 your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
      region: 'yourRegion',
      // 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 operations and maintenance. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket in which the object you want to access is stored. Example: examplebucket. 
      bucket: 'examplebucket',
    });
    
    // Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain bucket names. 
    const objectName = 'exampledir/exampleobject.txt'
    // Specify the full path of the local file to upload. Example: D:\\localpath\\examplefile.txt. 
    // By default, if you set this parameter to the name of a local file such as examplefile.txt without specifying the local path, the local file is uploaded from the local 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 the value of the object tag. Example: the key is owner, and the value is 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 the last part must be 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 it 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 your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
      region: 'yourRegion',
      // 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 operations and maintenance. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket in which the object you want to access is stored. Example: examplebucket. 
      bucket: 'examplebucket',
    });
    // Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain bucket names. 
    const objectName = 'exampledir/exampleobject.txt'
    // Specify the full path of the local file to upload. Example: D:\\localpath\\examplefile.txt. 
    // By default, if you set this parameter to the name of a local file such as examplefile.txt without specifying the local path, the local file is uploaded from the local 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 the value of the object tag. Example: the key is owner, and the value is 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 the last part must be 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 it 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 your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
      region: 'yourRegion',
      // 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 operations and maintenance. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket in which the object you want to access is stored. Example: examplebucket. 
      bucket: 'examplebucket',
    });
    
    // Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain bucket names. 
    const objectName = 'exampledir/exampleobject.txt'
    // Specify the full path of the local file to upload. Example: D:\\localpath\\examplefile.txt. 
    // By default, if you set this parameter to the name of a local file such as examplefile.txt without specifying the local path, the local file is uploaded from the local 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 the value of the object tag. Example: the key is owner, and the value is 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 an uploaded object or modify the 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 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 your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
  region: 'yourRegion',
  // 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 operations and maintenance. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the name of the bucket in which the object you want to access is stored. Example: examplebucket. 
  bucket: 'examplebucket',
});

// Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain bucket names. 
const objectName = 'exampledir/exampleobject.txt'
// Specify the key and the value of the object tag. Example: the key is owner, and the value is 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 a specified version of an object or modify the tags of the object

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

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

Note For more information about how to obtain the version ID of the 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 your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
  region: 'yourRegion',
  // 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 operations and maintenance. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the name of the bucket in which the object you want to access is stored. Example: examplebucket. 
  bucket: 'examplebucket',
});

// Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain bucket names. 
const objectName = 'exampledir/exampleobject.txt'
// Specify the key and the value of the object tag. Example: the key is owner, and the value is John. 
const tag = { owner: 'John', type: 'document' };
// Specify the version ID of the source 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 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:

    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 your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
      region: 'yourRegion',
      // 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 operations and maintenance. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket in which the object you want to access is stored. Example: examplebucket. 
      bucket: 'examplebucket',
    });
    
    // Specify the full path of the source object. Example: srcexampledir/exampleobject.txt. 
    const sourceObjectName = 'srcexampledir/exampleobject.txt';
    // Specify the full path of the destination object. Example: destexampledir/exampleobject.txt.  
    const targetObjectName = 'destexampledir/exampleobject.txt';
    
    // Configure request headers. 
    const headers = {
      // Specify the key and the value of the object tag. Example: the key is owner, and the value is 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 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:

    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 your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
      region: 'yourRegion',
      // 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 operations and maintenance. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the bucket in which the object you want to access is stored. Example: examplebucket. 
      bucket: 'examplebucket'
    });
    
    
    // Specify the full path of the source object. Example: srcexampledir/exampleobject.txt. 
    const sourceObjectName = 'srcexampledir/exampleobject.txt'
    // Specify the full path of the destination object. Example: destexampledir/exampleobject.txt.  
    const targetObjectName = 'destexampledir/exampleobject.txt'
    
    // Configure request headers. 
    const headers = {
      // Specify the key and the value of the object tag. Example: the key is owner, and the value is 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 the last part must be 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 object

The following code provides an example on how to add tags to a symbolic link 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 your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
  region: 'yourRegion',
  // 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 operations and maintenance. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the name of the bucket in which the object you want to access is stored. Example: examplebucket. 
  bucket: 'examplebucket',
});
// Specify the full path of the symbolic link object. Example: shortcut/myobject.txt. 
const symLink = "shortcut/myobject.txt";
// Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain bucket names. 
const targetObjectName = 'exampledir/exampleobject.txt'
                
// Configure request headers. 
const headers = {
  // Specify the key and the value of the object tag. Example: the key is owner, and the value is 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()