通过HTTP Range请求分段获取KS3资源

本文主要介绍KS3的Range Get方法及其示例。

详细信息

上传或者下载KS3中的大文件（超过100M）时，如果传输过程中受到网络环境影响，则会传输失败。在上传过程中，可以调用MultipartUpload接口进行分片上传。而下载资源时，可以通过HTTP Range请求获取大文件的部分内容。

请求语法：

GET /{ObjectKey} HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}
Range:bytes=byte_range

说明： byte_range：指请求资源的范围
此处假设Object资源大小为1024字节，Range有效区间为0-1023。示例如下：

• Range: bytes=500-999 表示第500~999字节范围的内容。
• Range: bytes=-500 表示第0~500字节范围的内容。
• Range: bytes=500- 表示从第500~1023字节范围的内容。
• Range: bytes=0- 表示第0~1023字节范围的内容，即完整的文件内容。
• KS3不支持多Range参数，即不支持指定多个范围。如果指定多个范围，KS3会报错InvalidRange，返回416 Requested Range Not Satisfiable。

如果HTTP Range请求合法，响应返回值为206 Partial Content并在响应头中包含Content-Range。
如果HTTP Range请求格式错误或首字节超出有效范围，响应返回值为416 Requested Range Not Satisfiable，如下为HTTP Range请求KS3错误说明：

• 格式错误示例：
  • Range: byte=0-499 格式错误，byte应为bytes，返回416 Requested Range Not Satisfiable
  • Range: bytes=999-500 格式错误，首字节比末字节大，返回416 Requested Range Not Satisfiable
  • Range: bytes=-1-300 格式错误，首字节为负数，返回206 Partial Content，返回第0~300字节范围的内容
  • Range: bytes= 格式错误，不填写数字，返回200 OK，并返回文件的全部内容
• 首字节超出有效范围示例：
  • Range: bytes=1024-2000 首字节超出有效区间，返回416 Requested Range Not Satisfiable
  • Range: bytes=1024- 首字节超出有效区间，无末字节，返回416 Requested Range Not Satisfiable
• 末字节超出有效范围示例：
  • Range: bytes=0-2000 ：末字节超出有效区间，首字节为0，返回206 Partial Content，返回文件的全部内容
  • Range: bytes=500-2000 ：末字节超出有效区间，首字节为中间值，返回206 Partial Content，返回文件第500-2000字节范围的内容
  • Range: bytes=-2000 ：末字节超出有效区间，无首字节，返回206 Partial Content，返回文件的全部内容

兼容版本

使用HTTP Range时，增加请求头x-kss-range-behavior:standard，可以指定最新版本KS3的HTTP Range Get方法。

请求语法

GET /{ObjectKey} HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}
Range:bytes=byte_range  
x-kss-range-behavior:standard

最新兼容版本相比旧版本行为改变内容如下：

• Range: bytes=-500 返回最后500字节的内容。
• 如果指定多个范围，KS3只返回第一个Range的内容，例如：Range:bytes=0-499,500-999，KS3只返回0-499字节范围的内容。
• Range: byte=0-499 格式错误，byte应为bytes，返回200 OK，完整的文件内容。
• Range: bytes=999-500 格式错误，首字节比末字节大，返回200 OK，完整的文件内容。
• Range: bytes=-1-300 格式错误，首字节为负数，返回200 OK，完整的文件内容。

注：除以上改变内容外，其他内容与旧版本保持一致。

示例

正常请求示例

请求Object资源0-499字节范围的内容。

GET /object HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.ks3-cn-beijing.ksyuncs.com
Accept: */*
Date: Mon, 14 Feb 2023 10:02:43 GMT
Range:bytes=0-499
Authorization: authorization string

响应示例

HTTP/1.1 206 Partial Content
Server: KS3
x-kss-request-id: f42rkt80h9oobs6l75ib5nkplngtmckl
Accept-Ranges: bytes
Content-Range: bytes 0-499/1024
ETag: "3aa6612bab7d3d0cf959ac0d8046****"
Last-Modified: Mon, 05 Dec 2022 05:12:40 GMT
Date: Mon, 14 Feb 2023 10:02:43 GMT
Content-Length: 500

兼容行为示例

• 增加x-kss-range-behavior:standard请求头，bytes=-500时返回最后500字节的内容。

GET /object HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.ks3-cn-beijing.ksyuncs.com
Accept: */*
Date: Mon, 14 Feb 2023 10:02:43 GMT
Range:bytes=-500
x-kss-range-behavior:standard
Authorization: authorization string

• 响应示例

HTTP/1.1 206 Partial Content
Server: KS3
x-kss-request-id: f42rkt80h9oobs6l75ib5nkplngtmckl
Accept-Ranges: bytes
Content-range: bytes 524-1024/1024
ETag: "3aa6612bab7d3d0cf959ac0d8046****"
Last-Modified: Mon, 05 Dec 2022 05:12:40 GMT
Date: Mon, 14 Feb 2023 10:02:43 GMT
Content-Length: 500

• 增加x-kss-range-behavior:standard请求头，首字节值大于末字节值导致Range不生效，响应200 OK，并返回整个文件内容。

GET /object HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.ks3-cn-beijing.ksyuncs.com
Accept: */*
Date: Mon, 14 Feb 2023 10:02:43 GMT
Range:bytes=999-500
Authorization: authorization string

• 响应示例

HTTP/1.1 200 OK
Server: KS3
x-kss-request-id: f42rkt80h9oobs6l75ib5nkplngtmckl
Accept-Ranges: bytes
ETag: "3aa6612bab7d3d0cf959ac0d8046****"
Last-Modified: Mon, 05 Dec 2022 05:12:40 GMT
Date: Mon, 14 Feb 2023 10:02:43 GMT
Content-Length: 1024