All Products
Search
Document Center

Object Storage Service:Node.js manage object metadata

Last Updated:Jun 15, 2025

Objects that are stored in Object Storage Service (OSS) consist of keys, data, and metadata. Object metadata describes object attributes. Object metadata includes standard HTTP headers and user metadata. You can create custom HTTP request policies such as object cache policies and forced object download policies by configuring standard HTTP headers. You can configure user metadata for an object to identify the purposes or attributes of the object.

Specify object metadata when you upload an object

When you call put, putStream, or multipartUpload, you can configure the meta parameter to specify 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 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,
  // 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: 'oss-cn-hangzhou',
  // Use V4 signature algorithm
  authorizationV4: true,
  // Specify the name of the bucket.
  bucket: 'yourBucketName',
  // Specify the public endpoint of the region in which the bucket is located. For example, if the bucket is located 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',  // Metadata values should be strings
        people: 'mary'
      }
    });
  console.log(result);
  } catch (e) {
    console.log(e);
  }
}

put();

Modify existing object metadata

You can call putMeta to modify the metadata of an existing object.

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

const client = new OSS({
  // 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,
  // 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: 'oss-cn-hangzhou',
  // Use V4 signature algorithm
  authorizationV4: true,
  // Specify the name of the bucket.
  bucket: 'yourBucketName',
  // Specify the public endpoint of the region in which the bucket is located. For example, if the bucket is located 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();

Obtain object metadata

You can call head to obtain object metadata.

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

const client = new OSS({
  // 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,
  // 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: 'oss-cn-hangzhou',
  // Use V4 signature algorithm
  authorizationV4: true,
  // Specify the name of the bucket.
  bucket: 'yourBucketName',
  // Specify the public endpoint of the region in which the bucket is located. For example, if the bucket is located 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. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path.
  const result = await client.head("exampledir/exampleobject.txt");
  console.log(result);
}

headInfo();