Manage object metadata (Node.js SDK) - Object Storage Service

Objects in Object Storage Service (OSS) contain a key, data, and object metadata. Object metadata describes the properties of an object. It includes standard HTTP headers and user-defined metadata. You can set standard HTTP headers to customize HTTP request policies, such as the object cache policy or a forced download policy. You can also set user-defined metadata to identify the purpose or properties of an object.

Specify object metadata during an upload

When you use the put, putStream, or multipartUpload operation, you can specify the meta parameter to set the object metadata:

const OSS = require('ali-oss');
const path = require('path');

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set yourRegion to the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Use Signature V4.
  authorizationV4: true,
  // Set yourBucketName to the name of the bucket.
  bucket: 'yourBucketName',
  // Set yourEndpoint to the Internet endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
});

async function put() {
  try {
    // Set metadata as the meta property of the options object.
    let result = await client.put('object-name', path.normalize('D:\\localpath\\examplefile.txt'), {
      meta: {
        year: '2025',  // The metadata value must be a string.
        people: 'mary'
      }
    });
  console.log(result);
  } catch (e) {
    console.log(e);
  }
}

put();

Modify the metadata of an existing object

You can also use the putMeta operation to update object metadata:

const OSS = require('ali-oss');

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set yourRegion to the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Use Signature V4.
  authorizationV4: true,
  // Set yourBucketName to the name of the bucket.
  bucket: 'yourBucketName',
  // Set yourEndpoint to the Internet endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
});

async function putMeta() {
  try {
    let meta = { year: 2025, people: 'jack' };
    let result = await client.putMeta('object-name', meta);
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

putMeta();

Get object metadata

You can use the head operation to retrieve object metadata.

const OSS = require('ali-oss');

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set yourRegion to the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Use Signature V4.
  authorizationV4: true,
  // Set yourBucketName to the name of the bucket.
  bucket: 'yourBucketName',
  // Set yourEndpoint to the Internet endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
});

async function headInfo() {
  // Specify the full path of the object, for example, exampledir/exampleobject.txt. The full path cannot contain the bucket name.
  const result = await client.head("exampledir/exampleobject.txt");
  console.log(result);
}

headInfo();