Object metadata includes HTTP headers and user metadata. You can configure the metadata of an object when you upload the object to Object Storage Service (OSS). The metadata of an object is uploaded and downloaded together with the object.

Usage notes

  • When you use packaging tools such as Webpack and Browserify, install OSS SDK for Browser.js by running the npm install ali-oss command.
  • In most cases, OSS SDK for Browser.js is used in browsers. To prevent your AccessKey pair from being exposed, we recommend that you use temporary access credentials obtained from Security Token Service (STS) to access OSS.

    For more information about how to use STS, see Use temporary credentials provided by STS to access OSS in OSS Developer Guide. You can call the AssumeRole operation or use STS SDKs for various programming languages to obtain temporary access credentials. Temporary access credentials include a security token and a temporary AccessKey pair that consists of an AccessKey ID and an AccessKey secret.

Sample code

The following sample code provides an example on how to specify object metadata during uploads and how to update and view object metadata after uploads:

<!DOCTYPE html>
<html lang="en">

  <meta charset="UTF-8" />

  <button id='upload'>Upload</button>
  <button id='update'>Modify Object Metadata</button>
  <button id='check'>View Object Metadata</button>
    <!-- Import the SDK file -->
  <script type="text/javascript" src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.16.0.min.js"></script>
  <script type="text/javascript">
    const client = new OSS({
       // 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: 'yourRegion',
       // Specify the temporary AccessKey pair obtained from STS. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
       accessKeyId: 'yourAccessKeyId',
       accessKeySecret: 'yourAccessKeySecret',
       // Specify the security token that you obtained from STS. 
       stsToken: 'yourSecurityToken',
       // Specify the name of the bucket. Example: examplebucket. 
       bucket: "examplebucket",

    const upload = document.getElementById('upload')
    const update = document.getElementById('update')
    const check = document.getElementById('check')

    // Specify the content of the object to upload. 
    const file = new Blob(['examplecontent'])
    // Specify the name of the object to upload to the bucket. 
    const fileName = 'exampleobject.txt'

    // Upload the local file. 
    upload.addEventListener('click', () => {
     client.put(fileName, file, {
        // Configure the user metadata of the object. You can configure multiple metadata attributes for an object. However, the total size of the object metadata cannot exceed 8 KB. 
        meta: {
          year: 2020,
          people: 'eliot'
      }).then(r => console.log(r))

    // Modify the object metadata. 
    update.addEventListener('click', () => {
      client.putMeta(fileName, {
        year: 2021,
        people: 'evan'
      ).then(r => {
    // View the object metadata. 
    check.addEventListener('click', () => {
      client.head(fileName).then(m => console.log(m))




  • For more information about the complete sample code for object metadata management, visit GitHub.
  • For more information about the operation that you can call to configure or modify object metadata during uploads, see PutObject.
  • For more information about the API operation that you can call to view object metadata, see HeadObject.