Skip to main content

​
Download partial content by specifying Range

​
What is HTTP Range download

When downloading a large file (over 100 MB) from OSS, the transfer may fail due to network conditions. In this case, use an HTTP Range request to retrieve partial content of the large file, as shown in the following example.
[$ByteRange] indicates the range of the requested resource, in bytes. Examples are shown below.
  • Range: bytes=0-499 indicates the content from byte 0 to byte 499.
  • Range: bytes=500-999 indicates the content from byte 500 to byte 999.
  • Range: bytes=-500 indicates the last 500 bytes.
  • Range: bytes=500- indicates the content from byte 500 to the end of the file.
  • Range: bytes=0- indicates the content from the first byte to the last byte, that is, the entire file.
  • OSS does not support multiple Range parameters, that is, you cannot specify multiple ranges. If multiple ranges are specified, OSS returns only the data of the first Range. For example, for Range:bytes=0-499,500-999, OSS returns only the content from byte 0 to byte 499.
  • The valid interval of [$ByteRange] is from 0 to content-length - 1.
If the HTTP Range request is valid, the response returns 206 and includes Content-Range in the response header. If the HTTP Range request is invalid, or the specified range is outside the valid interval, the Range does not take effect, the response returns 200, and the entire Object content is transferred. The following are examples of invalid HTTP Range requests and the corresponding error descriptions.
Assume that the Object resource size is 1000 bytes, and the valid Range interval is from 0 to 999.
  • Range: byte=0-499: Format error. byte should be bytes.
  • Range: bytes=0-1000: The last byte 1000 exceeds the valid interval.
  • Range: bytes=1000-2000: The specified range exceeds the valid interval.
  • Range: bytes=1000-: The first byte exceeds the valid interval.
  • Range: bytes=-2000: The specified range exceeds the valid interval.

​
Compatible behavior

When using HTTP Range, add the request header x-oss-range-behavior:standard to change the OSS behavior when the specified range is outside the valid interval. The following examples illustrate the changed behavior:
Assume that the Object resource size is 1000 bytes, and the valid Range interval is from 0 to 999. When retrieving partial content of a large file by HTTP Range request, if an invalid range is selected, OSS returns the InvalidRange error code. The detailed error message is as follows: The requested range cannot be satisfied
  • Range: bytes=500-2000: The last byte exceeds the valid interval. Returns the content from byte 500 to byte 999.
  • Range: bytes=1000-2000: The first byte exceeds the valid interval. Returns the error 416 (InvalidRange).
  • Range: bytes=1000-: The first byte exceeds the valid interval. Returns the error 416 (InvalidRange).
  • Range: bytes=-2000: The specified range exceeds the valid interval. Returns bytes 0 to 999, that is, the entire file.

​
Examples

Based on the above content, this topic provides the following HTTP Range request examples.
Assume that the Object resource size is 1000 bytes, and the valid Range interval is from 0 to 999.

​
Normal request examples

  • Request the content from byte 0 to byte 499 of the Object resource.
  • Request the content from byte 500 to the end of the Object resource.
  • Request the last 500 bytes of the Object resource.

​
Out-of-range request examples

  • The last byte 1000 exceeds the valid interval, so Range does not take effect. The response returns 200 and transfers the entire Object content.
  • The specified range exceeds the valid interval, so Range does not take effect. The response returns 200 and transfers the entire Object content.

​
Compatible behavior request examples

  • Add the x-oss-range-behavior:standard request header. The last byte exceeds the valid interval, so the content from byte 500 to byte 999 is returned.
  • Add the x-oss-range-behavior:standard request header. The first byte exceeds the valid interval, so the 416 error is returned.
  • Add the x-oss-range-behavior:standard request header. The specified range exceeds the valid interval, so bytes 0 to 999 are returned, that is, the entire file.