Object Storage Service:Range download

Specify a valid range to download data

If the start and end values of the range that you specify are within the size of an object, the content within the specified range is downloaded. For example, if the object from which you want to download data is 1,000 bytes in size, the valid range is from byte 0 to byte 999.

The following sample code provides an example on how to specify a valid range to download:

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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the name of the bucket. 
  bucket: 'examplebucket'
});

async function main() {
  const start = 1, end = 900;
  // Specify the full path of the object. Do not include the bucket name in the full path. Example: destfolder/examplefile.txt. 
  // Obtain the data that is within the range from byte 0 to byte 900, which includes a total of 900 bytes. 
  // If the start or end value of the specified range is not within the valid range, the entire object is downloaded. 
  const result = await client.get("<yourObjectName>", {
    headers: {
      Range: `bytes=${start}-${end}`,
    },
  })
  console.log(result.content.toString())
};

main();

For more information about the naming conventions for buckets, see Bucket. For more information about the naming conventions for objects, see Object.

Specify standard behaviors to download data by range

You can add the x-oss-range-behavior:standard header to the request to modify the download behavior when the specified range is not within the valid range.

The following sample code provides an example on how to specify standard behaviors to download data by range:

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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the name of the bucket. 
  bucket: 'examplebucket'
});

async function main() {
  // Upload an object named exampleobject.txt, which is 10 bytes in size. 
  const buf = Buffer.from("abcdefghij");
  await client.put("exampleobject.txt", buf);
  const result = await client.get("exampleobject.txt", {
  // Set Range to bytes=5-15. In this case, the end value of the range is not within the valid range. Therefore, OSS returns HTTP status code 206 and the data from byte 6 to byte 10. 
    headers: {
      Range: "bytes=5-15",      
      "x-oss-range-behavior": "standard",
    },
  });
  console.log(result.content.toString() === 'fghij')
  console.log(result.res.status === 206)
  try{
    await client.get("exampleobject.txt", {
      // Set Range to bytes=15-25. In this case, the start value of the range is not within the valid range. Therefore, OSS returns HTTP status code 416 and the error code InvalidRange. 
      headers: {
        Range: "bytes=15-25",        
        "x-oss-range-behavior": "standard",
      },
    })
  }catch(e) {
    console.log(e.status === 416);
    console.log(e.name === 'InvalidRangeError')
  }
}

main();

References

For more information about the API operation that you can call to perform range download, see GetObject.