Object Storage Service:Install OSS SDK for Browser.js

Prerequisites

• A Resource Access Management (RAM) user or temporary access credentials are created in Security Token Service (STS) to access OSS.

  Never use your root Alibaba Cloud account's AccessKey pair directly in client-side code. Doing so will expose your credentials to the public. Always use temporary credentials (STS tokens) for browser-based access. For more information, see Permissions and access control.

• Cross-origin resource sharing (CORS) rules are configured.

  To allow your web application to access OSS, you must configure CORS rules on your bucket with the following settings:

  • Source: Specify a complete origin URL (example: https://www.aliyun.com) or specify a URL that contains an asterisk (*) wildcard character (example: https://*.aliyun.com).

  • Allowed Methods: Select the methods based on your requirements. For example, select PUT to perform multipart upload and select DELETE to delete objects.

  • Allowed Headers: Set the value to *.

  • Exposed Headers: Set the values to ETag, x-oss-request-id, or x-oss-version-id based on your specific requirements.

  

  For more information, see Configure CORS.

Limits

OSS SDK for Browser.js uses Browserify and Babel to generate and compile code for your browser. However, the following features are not supported in browsers because of the limits of the browser environment:

• Streaming upload: Chunked encoding cannot be configured in browsers. Use multipart upload instead of streaming upload.

• Local file management: Local file systems cannot be managed in browsers. Use signed URLs to download objects.

• OSS does not support bucket-related requests across origins. Perform bucket-related operations in the OSS console.

Download OSS SDK for Browser.js

This documentation is based on SDK v6.x. For older versions (v5.x), refer to GitHub. To upgrade from v5.x to v6.x, see the upgrade documents.

• GitHub

• API operations

• ChangeLog

Install OSS SDK for Browser.js

• OSS SDK for Browser.js supports the following browsers:

  • Internet Explorer V10 or later

  • Edge

  • Major versions of Google Chrome, Firefox, and Safari

  • Default browsers of Android, iOS, and Windows Phone of major versions

• Installation methods

  Install OSS SDK for Browser.js by using one of the following methods:

  Use a browser to import OSS SDK for Browser.js

  Important

  Some browsers do not provide native support for promises. You need to import a promise library. For example, import promise-polyfill to Internet Explorer 10 and 11.

  <!-- Import online -->
  <script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.20.0.min.js"></script>     
  <!-- Import locally -->
  <script src="./aliyun-oss-sdk-6.20.0.min.js"></script>

  Note

  • If you import the SDK online, the speed depends on the stability of Alibaba Cloud CDN servers. Import the SDK locally or by using your own implementation.

  • If you import the SDK from a local resource in a sample program, set src to the path of the local resource relative to the path of the sample program.

  • In this example, OSS SDK 6.20.0 is used. For information about more versions, visit ali-oss.

  The following code provides an example on how to use an OSS object:

  Important

  For security, you must use temporary credentials from STS (which include an AccessKey ID, AccessKey secret, and a security token) to access OSS from a browser. Call the AssumeRole operation or use STS SDKs for various programming languages to obtain temporary credentials. For more information, see Use temporary credentials provided by STS to access OSS.

  <script type="text/Browser.jsscript">
    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',
      // Use the V4 signature.
      authorizationV4: true,
      // Specify the temporary AccessKey pair obtained from STS. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the security token obtained from STS. 
      stsToken: 'yourSecurityToken',
      refreshSTSToken: async () => {
      // Obtain temporary access credentials from STS. 
        const info = await fetch('your_sts_server');
        return {
          accessKeyId: info.accessKeyId,
          accessKeySecret: info.accessKeySecret,
          stsToken: info.stsToken
        }
      },
      // Set the time interval of refreshing temporary access credentials. Unit: milliseconds. 
      refreshSTSTokenInterval: 300000,
      // Specify the name of the bucket. 
      bucket: 'examplebucket'
    });
  </script>                           

  Use npm to install the package of OSS SDK for Browser.js

  npm install ali-oss

  After the installation is complete, use the import or require syntax to use OSS SDK for Browser.js. Browsers do not provide native support for the require syntax. Therefore, you need to use a packaging tool such as webpack or browserify in the development environment.

  const OSS = require('ali-oss');
  
  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',
      // Use the V4 signature.
      authorizationV4: true,
      // Specify the temporary AccessKey pair obtained from STS. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the security token obtained from STS. 
      stsToken: 'yourSecurityToken',
      refreshSTSToken: async () => {
      // Obtain temporary access credentials from the STS that you set up. 
        const info = await fetch('your_sts_server');
        return {
          accessKeyId: info.accessKeyId,
          accessKeySecret: info.accessKeySecret,
          stsToken: info.stsToken
        }
      },
      // Set the time interval at which to refresh the temporary access credentials. Unit: milliseconds. 
      refreshSTSTokenInterval: 300000,
      // Specify the name of the bucket. 
      bucket: 'examplebucket'
  });

Usage modes

Use the synchronous or asynchronous mode when you use OSS SDK for Browser.js. new OSS() is used to create OSS clients when the synchronous or asynchronous mode is used.

// Create an OSSClient instance. 
const client = new OSS(...);

async function put () {
  try {
    // object specifies the name of the uploaded object. 
    // file specifies the name of the file that you want to upload from the browser. Files of the HTML5 and Blob types are supported. 
    const r1 = await client.put('object', file);
    console.log('put success: %j', r1);
    const r2 = await client.get('object');
    console.log('get success: %j', r2);
  } catch (e) {
    console.error('error: %j', e);
  }
}

put();                    

// Create an OSSClient instance. 
const client = new OSS(...);

// object specifies the name of the uploaded object. 
// file specifies the name of the file that you want to upload from the browser. Files of the HTML5 and Blob types are supported. 
client.put('object', file).then(function (r1) {
  console.log('put success: %j', r1);
  return client.get('object');
}).then(function (r2) {
  console.log('get success: %j', r2);
}).catch(function (err) {
  console.error('error: %j', err);
});