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();