All Products
Search

This Product

    Object Storage Service:Range download (Browser.js SDK)

    Document Center

    Object Storage Service:Range download (Browser.js SDK)

    Last Updated:Mar 20, 2026

    Use range downloads to retrieve a specific byte range from an object instead of downloading the entire object. This is useful when you only need a portion of a large file, such as reading a segment of a log file or streaming a section of video.

    Prerequisites

    Before you begin, make sure you have:

    • OSS SDK for Browser.js installed or imported

      • npm (Webpack or Browserify): run npm install ali-oss

      • CDN: add <script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script> to your HTML

    • CORS rules configured for your bucket. Without CORS rules, browsers reject cross-origin requests. See Installation for setup instructions.

    • Temporary access credentials from Security Token Service (STS). Use STS temporary credentials instead of a long-lived AccessKey pair to avoid exposing credentials in client-side code. The credentials consist of a temporary AccessKey ID, AccessKey secret, and security token. See Use STS for temporary access authorization.

    Download a byte range

    The following example downloads bytes 0–999 from example.txt and triggers a file save in the browser.

    Note: The byte range is specified using the Range: bytes=<start>-<end> header, where both values are inclusive and 0-based. For a 1,000-byte object, valid values are 0 to 999. If the range is invalid—for example, if the start or end position is negative or exceeds the object size—OSS returns the entire object.
    <!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Range download</title>
</head>
<body>
  <button id="download">Download</button>

  <!-- 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">

    // Initialize the OSS client with STS temporary credentials.
    // stsToken, accessKeyId, and accessKeySecret are obtained from your STS endpoint.
    const client = new OSS({
      // Set region to the region where your bucket is located.
      // For example, if your bucket is in the China (Hangzhou) region, set region to oss-cn-hangzhou.
      region: 'yourRegion',
      authorizationV4: true,
      accessKeyId: 'yourAccessKeyId',       // Temporary AccessKey ID from STS
      accessKeySecret: 'yourAccessKeySecret', // Temporary AccessKey secret from STS
      stsToken: 'yourSecurityToken',         // Security token from STS
      bucket: 'examplebucket',
    });

    const download = document.getElementById('download');

    // Specify the byte range to download (inclusive, 0-based).
    // This example downloads the first 1,000 bytes of the object.
    const start = 0;
    const end = 999;

    download.addEventListener('click', () => {
      client.get('example.txt', {
        headers: {
          Range: `bytes=${start}-${end}`,
        },
      }).then(r => {
        // Convert the returned data to a Blob and trigger a browser download.
        const blob = new Blob([r.content], { type: r.res.headers['content-type'] });
        const link = document.createElement('a');
        link.href = window.URL.createObjectURL(blob);
        link.download = 'example.txt';
        link.click();
        window.URL.revokeObjectURL(link.href);
      });
    });

  </script>
</body>
</html>

    References