Set object tags with Node.js SDK - Object Storage Service

Object tagging lets you classify objects in a bucket by attaching key-value pairs to them. Once tagged, you can apply lifecycle rules, access permissions, and other configurations to all objects that share the same tags.

Prerequisites

Before you begin, make sure you have:

Read the Object tagging overview
The oss:PutObjectTagging permission on the target bucket. For details, see Attach a custom policy to a RAM user
The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables configured with your access credentials

Usage notes

Examples in this topic use the public endpoint for the China (Hangzhou) region. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint instead. For supported regions and endpoints, see Regions and endpoints.
To create an OSSClient instance using a custom domain name or Security Token Service (STS), see Configuration examples for common scenarios.

Tag format

Tags are specified differently depending on when you set them:

When	Format	Example
During upload (via request header)	URL-encoded string in `x-oss-tagging`	`'owner=John&type=document'`
After upload (via `putObjectTagging`)	JavaScript object	`{ owner: 'John', type: 'document' }`

Set tags during upload

All upload methods accept an x-oss-tagging request header. Set it to a URL-encoded string of key=value pairs separated by &.

Simple upload

const OSS = require('ali-oss')

const client = new OSS({
  // Set region to the region where the bucket is located, for example oss-cn-hangzhou for China (Hangzhou).
  region: 'yourregion',           // required
  // Obtain access credentials from environment variables.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,      // required
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET, // required
  authorizationV4: true,
  bucket: 'yourbucketname'        // required
});

// Full path of the object, excluding the bucket name. For example, exampledir/exampleobject.txt.
const objectName = 'exampledir/exampleobject.txt'
// Full path of the local file. For example, D:\\localpath\\examplefile.txt.
const localFilepath = 'D:\\localpath\\examplefile.txt'

const headers = {
  'x-oss-tagging': 'owner=John&type=document',
}

client.put(objectName, localFilepath, { headers })

Multipart upload

const OSS = require('ali-oss')

const client = new OSS({
  region: 'yourregion',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname'
});

const objectName = 'exampledir/exampleobject.txt'
const localFilepath = 'D:\\localpath\\examplefile.txt'

const headers = {
  'x-oss-tagging': 'owner=John&type=document',
}

async function setTag() {
  await client.multipartUpload(objectName, localFilepath, {
    partSize: 100 * 1024,   // Minimum part size is 100 KB; last part has no minimum.
    headers
  });
  const tag = await client.getObjectTagging(objectName);
  console.log(tag);
}

setTag()

Append upload

Only the tags set in the first append operation take effect. Tags specified in subsequent append operations are ignored.

const OSS = require('ali-oss')

const client = new OSS({
  region: 'yourregion',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname'
});

const objectName = 'exampledir/exampleobject.txt'
const localFilepath = 'D:\\localpath\\examplefile.txt'

const headers = {
  'x-oss-tagging': 'owner=John&type=document',
}

async function setTag() {
  await client.append(objectName, localFilepath, {
    partSize: 100 * 1024,   // Minimum part size is 100 KB; last part has no minimum.
    headers
  });
  const tag = await client.getObjectTagging(objectName);
  console.log(tag);
}

setTag()

Resumable upload

Resumable upload uses multipartUpload with a checkpoint to resume interrupted transfers.

const OSS = require('ali-oss')

const client = new OSS({
  region: 'yourregion',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname'
});

const objectName = 'exampledir/exampleobject.txt'
const localFilepath = 'D:\\localpath\\examplefile.txt'
let checkpoint;

const headers = {
  'x-oss-tagging': 'owner=John&type=document',
}

async function setTag() {
  await client.multipartUpload(objectName, localFilepath, {
    checkpoint,
    async progress(percentage, cpt) {
      checkpoint = cpt;
    },
    headers
  });
  const tag = await client.getObjectTagging(objectName);
  console.log(tag);
}

setTag()

Add or change tags on an existing object

Use putObjectTagging to set tags on an object that is already uploaded. Pass tags as a JavaScript object with string keys and values.

const OSS = require('ali-oss')

const client = new OSS({
  region: 'yourregion',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname'
});

const objectName = 'exampledir/exampleobject.txt'
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 or change tags on a specific object version

In a versioning-enabled bucket, pass the version ID in the options to target a specific object version.

To get version IDs, see List objects (Node.js SDK).

const OSS = require('ali-oss')

const client = new OSS({
  region: 'yourregion',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname'
});

const objectName = 'exampledir/exampleobject.txt'
const tag = { owner: 'John', type: 'document' };
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)

Set tags when copying an object

When you copy an object, control how tags are handled on the destination object using the x-oss-tagging-directive header:

Value	Behavior	Default
`Copy`	Copy tags from the source object to the destination object	Yes
`Replace`	Ignore source tags; use the tags specified in the request	No

Simple copy (objects smaller than 1 GB)

const OSS = require('ali-oss')

const client = new OSS({
  region: 'yourregion',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname'
});

const sourceObjectName = 'srcexampledir/exampleobject.txt';
const targetObjectName = 'destexampledir/exampleobject.txt';

const headers = {
  'x-oss-tagging': 'owner=John&type=document',
  // Replace: ignore source tags; use the tags specified here.
  // Copy (default): copy tags from the source 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()

Multipart copy (objects larger than 1 GB)

const OSS = require('ali-oss')

const client = new OSS({
  region: 'yourregion',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname'
});

const sourceObjectName = 'srcexampledir/exampleobject.txt'
const targetObjectName = 'destexampledir/exampleobject.txt'

const headers = {
  'x-oss-tagging': 'owner=John&type=document',
}

async function setTag() {
  await client.multipartUploadCopy(targetObjectName, {
    sourceKey: sourceObjectName,
    sourceBucketName: 'examplebucket'
  }, {
    partSize: 256 * 1024,   // Minimum part size is 100 KB; last part has no minimum.
    headers
  });
  const tag = await client.getObjectTagging(targetObjectName)
  console.log(tag)
}

setTag()

Set tags for a symbolic link

const OSS = require('ali-oss')

const client = new OSS({
  region: 'yourregion',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname'
});

const symLink = 'shortcut/myobject.txt';
const targetObjectName = 'exampledir/exampleobject.txt'

const headers = {
  '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()

What's next

Get object tags: client.getObjectTagging(objectName)
Delete object tags: client.deleteObjectTagging(objectName)
For the complete sample code, see GitHub
For API details, see PutObjectTagging