Configure object tagging - Object Storage Service - Alibaba Cloud Documentation Center

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.

Usage notes

Before you configure object tagging, make sure that you are familiar with the feature. For more information, see Object tagging.

In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about OSS regions and endpoints, see Regions, endpoints and open ports.
In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.
In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Create an OSSClient instance.
Only OSS SDK for Java 3.5.0 and later support object tagging.
To add a tag to an object, you must have the oss:PutObjectTagging permission. For more information, see Attach a custom policy to a RAM user.

Add tags to an object when you upload the object

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

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

const OSS = require('ali-oss')

const client = new OSS({
  // Specify 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Specify the full path of the object. Do not include the bucket name in the full path. 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 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 using multipart upload:

const OSS = require('ali-oss')

const client = new OSS({
  // Specify 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Specify the full path of the object. Do not include the bucket name in the full path. 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 value to John. 
  'x-oss-tagging': 'owner=John&type=document', 
}


async function setTag() {
  await client.multipartUpload(objectName, localFilepath, {
    // Specify the part size. Unit: bytes. Each part except the last part must be greater than or equal to 100 KB. 
    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 the object by using append upload:

const OSS = require('ali-oss')

const client = new OSS({
  // Specify 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Specify the full path of the object. Do not include the bucket name in the full path. 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 value to John. 
  'x-oss-tagging': 'owner=John&type=document',
}


// Specify the headers when you call the AppendObject operation to add the tags to the object. 
// Only the tags specified 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: bytes. Each part except the last part must be greater than or equal to 100 KB. 
    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 the object by using resumable upload:

const OSS = require('ali-oss')

const client = new OSS({
  // Specify 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Specify the full path of the object. Do not include the bucket name in the full path. 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. 
letcheckpoint;

// Configure request headers. 
const headers = {
  // Specify the key and value of the object tag. For example, set the key to owner and 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 tags of the object do not meet your requirements, you can add tags to or modify the tags of the 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({
  // Specify 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Specify the full path of the object. Do not include the bucket name in the full path. 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 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 specific version of an object

If versioning is enabled for a bucket, you can add tags to or modify the tags of a specific version of an object in the bucket 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 specific version of an object.

Note

For more information about how to obtain the version ID, see List objects.

const OSS = require('ali-oss')

const client = new OSS({
  // Specify 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Specify the full path of the object. Do not include the bucket name in the full path. 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 value to John. 
const tag = { owner: 'John', type: 'document' };
// Specify the version ID of the object. 
constversionId='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 object tagging when you copy an object:

Copy: The tag of the source object is copied to the destination object.
Replace: The destination object has 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 the object by using simple copy:

const OSS = require('ali-oss')

const client = new OSS({
  // Specify 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Specify the full path of the source object. Do not include the bucket name in the full path. Example: srcexampledir/exampleobject.txt. 
const sourceObjectName = 'srcexampledir/exampleobject.txt';
// Specify the full path of the destination object. Do not include the bucket name in the full path. 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 value to John. 
  'x-oss-tagging': 'owner=John&type=document',
  // Specify the method that is used to add tags to 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 greater than 1 GB when you copy the object by using multipart copy:

const OSS = require('ali-oss')

const client = new OSS({
  // Specify 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Specify the full path of the source object. Do not include the bucket name in the full path. Example: srcexampledir/exampleobject.txt. 
const sourceObjectName = 'srcexampledir/exampleobject.txt'
// Specify the full path of the destination object. Do not include the bucket name in the full path. 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 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: bytes. Each part except the last part must be greater than or equal to 100 KB. 
    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({
  // Specify 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Specify the full path of the symbolic link. Example: shortcut/myobject.txt. 
const symLink = "shortcut/myobject.txt";
// Specify the full path of the object. Do not include the bucket name in the full path. 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 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 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.