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

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({
  // Set yourRegion to the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Region to oss-cn-hangzhou.
  region: 'yourRegion',
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the bucket name.
  bucket: 'examplebucket'
});

async function main() {
  const start = 1, end = 900;
  // yourObjectName specifies the full path of the object without the bucket name, for example, destfolder/examplefile.txt.
  // Get data from byte 1 to 900 of the target object. This includes bytes 1 and 900, for a total of 900 bytes.
  // If the start or end of the specified range is outside the valid range, the entire file is downloaded and the HTTP code 200 is returned.
  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.

Standard behavior range download

You can add the x-oss-range-behavior:standard request header to change the OSS download behavior if the specified range is outside 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({
  // Set yourRegion to the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Region to oss-cn-hangzhou.
  region: 'yourRegion',
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the bucket name.
  bucket: 'examplebucket'
});

async function main() {
  // Upload a 10-byte file named exampleobject.txt.
  const buf = Buffer.from("abcdefghij");
  await client.put("exampleobject.txt", buf);
  const result = await client.get("exampleobject.txt", {
  // Specify Range: bytes=5-15. The end of the range is outside the valid range. The content from byte 6 to 10 is returned, and the HTTP code is 206.
    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", {
      // Specify Range: bytes=15-25. The start of the range is outside the valid range. The HTTP code 416 is returned with the InvalidRange error code.
      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.