Manage file metadata using Browser.js SDK - Object Storage Service

Each object stored in OSS has an associated set of metadata that describes the object. Object metadata falls into two categories:

HTTP headers — standard headers such as Content-Type and Cache-Control that control caching and download behavior.
User metadata — custom key-value pairs you define to store additional attributes for an object (total size limit: 8 KB).

This page shows how to set user metadata when uploading an object, update it afterwards, and read it back—all from a browser using OSS SDK for Browser.js.

Prerequisites

Before you begin, make sure you have:

OSS SDK for Browser.js installed. If you use Webpack or Browserify, run npm install ali-oss.
CORS rules configured on your bucket. Without CORS rules, the browser blocks requests to OSS. See Installation for details.
Temporary credentials from Security Token Service (STS). Avoid hardcoding a permanent AccessKey pair in browser-side code. See Use STS for temporary access authorization to obtain an AccessKey ID, AccessKey secret, and security token.

Initialize the client

All examples on this page use the following client setup. Replace the placeholder values before running.

<!-- Import the SDK -->
<script type="text/javascript" src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script>
<script type="text/javascript">
  const client = new OSS({
    // Region where your bucket is located, for example: oss-cn-hangzhou
    region: '<your-region>',
    authorizationV4: true,
    // Temporary credentials from STS
    accessKeyId: '<your-access-key-id>',
    accessKeySecret: '<your-access-key-secret>',
    stsToken: '<your-security-token>',
    bucket: '<your-bucket-name>',
  });
</script>

Placeholder	Description	Example
`<your-region>`	Region where your bucket is located	`oss-cn-hangzhou`
`<your-access-key-id>`	AccessKey ID from STS temporary credentials	`STS.NUg...`
`<your-access-key-secret>`	AccessKey secret from STS temporary credentials	`xXxX...`
`<your-security-token>`	Security token from STS	`CAIS...`
`<your-bucket-name>`	Your bucket name	`examplebucket`

Set metadata on upload

Pass a meta object in the options argument of client.put(). Each key-value pair in meta becomes a custom metadata entry on the object.

const file = new Blob(['examplecontent']);
const objectKey = 'exampleobject.txt';

client.put(objectKey, file, {
  // Custom metadata — total size of all entries cannot exceed 8 KB
  meta: {
    year: 2020,
    people: 'eliot',
  },
}).then(result => console.log(result));

Update metadata

Call client.putMeta() to update the metadata on an existing object. Pass the object key and a meta object containing the entries you want to set.

client.putMeta('exampleobject.txt', {
  year: 2021,
  people: 'evan',
}).then(result => console.log(result));

Read metadata

Call client.head() to retrieve an object's metadata without downloading the object body.

client.head('exampleobject.txt').then(meta => console.log(meta));

To read custom metadata values in the browser console, add the corresponding metadata keys (for example, x-oss-meta-year) to the ExposeHeaders list in your bucket's CORS rules. Without this configuration, client.head() returns null for those fields.

What's next

PutObject — API reference for uploading objects and setting metadata
HeadObject — API reference for reading object metadata
GitHub example — complete sample code for managing object metadata