This topic describes how to configure object tagging.

The object tagging function uses a key-value pair to tag an object. For more information about the object tagging function, see Configure object tagging.

Note
  • You can add tags to an object when uploading it or add tags for an uploaded object. If add tags to an object that already has tags, the original tags are overwritten. For more information about adding tags, see PutObjectTagging.
  • To add tags to an object, you must have the permission to call PutObjectTagging.
  • The Last-Modified value of an object is not updated when its tags are changed.
  • A tag can contain letters, numbers, spaces, and the following symbols: + ‑ = . _ : /

Add tags to an object when uploading it

  • Add tags to an object when uploading it by calling PutObject.

    The following code provides an example on how to add tags to an object when uploading it by calling PutObject:

    const OSS = require('ali-oss')
    
    const client = new OSS({
      bucket: '<Your BucketName>',
    
      //This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
      region: '<Your Region>',
      // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
    });
    
    
    // Configure request headers.
    const headers = {
      'x-oss-tagging': 'TagA=A&TagB=B',
    }
    
    client.put('fileName', 'file', {
      headers
    })
  • Add tags to an object when uploading it by using multipart upload.

    The following code provides an example on how to add tags to an object when uploading it by calling MultipartUpload:

    const OSS = require('ali-oss')
    
    const client = new OSS({
      bucket: '<Your BucketName>',
      // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
      region: '<Your Region>',
      // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
    });
    
    // Configure request headers.
    const headers = {
      'x-oss-tagging': 'TagA=A&TagB=B',
    }
    
    async function setTag() {
      await store.multipartUpload('<file name>', '<upload file>', {
        partSize: 100 * 1024,
        headers
      });
      const tag = await store.getObjectTagging(name);
      console.log(tag);
    }
    
    
    setTag()
  • Add tags to an object when uploading it by using append upload.

    The following code provides an example on how to add tags to an object when uploading it by calling AppendObject:

    const OSS = require('ali-oss')
    
    const client = new OSS({
      bucket: '<Your BucketName>',
      // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.  region: '<Your Region>',
      // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create your RAM user, log on to https://ram.console.aliyun.com.
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
    });
    
    // Configure request headers.
    const headers = {
      'x-oss-tagging': 'TagA=A&TagB=B'
    }
    
    // Upload the object. Tags are added to the object when you specify the x-oss-tagging header when calling AppendObject.
    // Only the tags set when the object is appended for the first time are added to the object.
    async function setTag() {
      await store.append('<file name>', '<upload file>', {
        partSize: 100 * 1024,
        headers
      });
      const tag = await store.getObjectTagging(name);
      console.log(tag);
    }
    
    
    setTag()
  • Add tags to an object when uploading it by using resumable upload.

    The following code provides an example on how to add tags to an object when uploading it by calling MultipartUpload:

    const OSS = require('ali-oss')
    
    const client = new OSS({
      bucket: '<Your BucketName>',
      //This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
      region: '<Your Region>',
      // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create your RAM user, log on to https://ram.console.aliyun.com.
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
    });
    
    // Configure request headers.
    const headers = {
      'x-oss-tagging': 'TagA=A&TagB=B'
    }
    
    // Configure the checkpoint information.
    const checkponit = {
      file,
      name,
      fileSize,
      partSize,
      uploadId,
      doneParts: []
    }
    
    async function setTag() {
      await store.multipartUpload('<file name>', '<upload file>', {
        checkponit,
        headers
      });
      const tag = await store.getObjectTagging(name);
      console.log(tag);
    }
    
    
    setTag()

Add tags to an uploaded object or modify the tags added to an object

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

const OSS = require('ali-oss')

const client = new OSS({
  bucket: '<Your BucketName>',
  // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.  region: '<Your Region>',
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
});

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

const tag = { a: '1', b: '2' };
putObjectTagging('objectName', tag)

Add tags to an object when copying it

You can specify one of the following tagging rules when copying an object:
  • Copy (default): Copy the tags of the source object to the destination object.
  • Replace: Add the tags specified in the request to the destination object.

Examples of adding tags to objects of different sizes when copying them are described as follows:

  • The following code provides an example on how to add tags to an object smaller than 1 GB when directyly copying it:
    const OSS = require('ali-oss')
    
    const client = new OSS({
      bucket: '<Your BucketName>',
      // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
      region: '<Your Region>',
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
    });
    
    // Configure request headers. const headers = {
      'x-oss-tagging': 'TagA=A&TagB=B',
      // 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 is copied to the destination object. Replace indicates that the tags specified in the request is added to the destination object.
      'x-oss-tagging-directive': 'Replace' 
    }
    
    async function setTag() {
      const targetObjectName = `${prefix}ali-sdk/oss/copy-tag.js`;
      const result = await store.copy(targetObjectName, sourceObjectName, {
        headers
      });
      const tag = await store.getObjectTagging(targetObjectName)
      console.log(tag)
    }
    
    setTag()
  • The following code provides an example on how to add tags to an object larger than 1 GB when copying it by calling MultipartUpload:
    const OSS = require('ali-oss')
    
    const client = new OSS({
      bucket: '<Your BucketName>',
      // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.  region: '<Your Region>',
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS, because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to https://ram.console.aliyun.com.
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
    });
    
    // Configure request headers.
    const headers = {
      'x-oss-tagging': 'TagA=A&TagB=B',
    }
    
    async function setTag() {
      await client.multipartUploadCopy(copyName, {
        sourceKey: name,
        sourceBucketName: bucket
      }, {
        partSize: 256 * 1024,
        headers
      });
      const tag = await store.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({
  bucket: '<Your BucketName>',
  region: '<Your Region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
});

// Configure request headers.
const headers = {
  'x-oss-tagging': 'TagA=A&TagB=B'
}

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

setTag()