メインコンテンツへスキップ

​
Range を指定して部分コンテンツをダウンロード

​
HTTP Range を指定したコンテンツダウンロードとは

OSS 内の大容量ファイル（100M を超えるもの）をダウンロードする際、転送中にネットワーク環境の影響を受けると、転送が失敗することがあります。この場合、HTTP Range リクエストを利用して大容量ファイルの一部コンテンツを取得できます。例は以下のとおりです。
[$ByteRange] はリクエストするリソースの範囲を示し、単位は「Byte（バイト）」です。例は以下のとおりです。
  • Range: bytes=0-499 は第 0〜499 バイトの範囲のコンテンツを示します。
  • Range: bytes=500-999 は第 500〜999 バイトの範囲のコンテンツを示します。
  • Range: bytes=-500 は末尾 500 バイトのコンテンツを示します。
  • Range: bytes=500- は第 500 バイトからファイル終端までのコンテンツを示します。
  • Range: bytes=0- は最初のバイトから最後のバイトまで、つまりファイル全体のコンテンツを示します。
  • OSS は複数の Range パラメータをサポートしていません。つまり、複数の範囲指定はサポートされていません。複数の範囲を指定した場合、OSS は最初の Range のデータのみを返します。例えば、Range:bytes=0-499,500-999 の場合、OSS は 0〜499 バイトの範囲のコンテンツのみを返します。
  • [$ByteRange] の有効区間は 0 から content-length - 1 までの範囲内です。
HTTP Range リクエストが正当な場合、レスポンスの戻り値は 206 となり、レスポンスヘッダーに Content-Range が含まれます。HTTP Range リクエストが不正な場合、または指定範囲が有効区間外の場合、Range は適用されず、レスポンスの戻り値は 200 となり、Object 全体のコンテンツが転送されます。HTTP Range リクエストが不正な例とエラー説明は以下のとおりです。
ここでは Object リソースのサイズが 1000 バイト、Range 有効区間が 0〜999 と仮定します。
  • Range: byte=0-499：フォーマットエラー。byte は bytes であるべきです。
  • Range: bytes=0-1000：末尾バイト 1000 が有効区間を超えています。
  • Range: bytes=1000-2000：指定範囲が有効区間を超えています。
  • Range: bytes=1000-：先頭バイトが有効区間を超えています。
  • Range: bytes=-2000：指定範囲が有効区間を超えています。

​
互換動作

HTTP Range を使用する際にリクエストヘッダー x-oss-range-behavior:standard を追加すると、指定範囲が有効区間外の場合の OSS の動作を変更できます。動作変更の例は以下のとおりです。
ここでは Object リソースのサイズが 1000 バイト、Range 有効区間が 0-999 と仮定します。HTTP Range リクエストで大容量ファイルの一部コンテンツを取得する際、無効な範囲を選択したことで OSS が InvalidRange エラーコードを返します。詳細なエラーメッセージは以下のとおりです：The requested range cannot be satisfied
  • Range: bytes=500-2000：末尾バイトが有効区間を超えています。500-999 バイトの範囲のコンテンツを返します。
  • Range: bytes=1000-2000：先頭バイトが有効区間を超えています。エラー 416 (InvalidRange) を返します。
  • Range: bytes=1000-：先頭バイトが有効区間を超えています。エラー 416 (InvalidRange) を返します。
  • Range: bytes=-2000：指定範囲が有効区間を超えています。0-999 バイト、つまりファイル全体のコンテンツを返します。

​
例

上記の内容に対して、本記事では以下の HTTP Range リクエスト例を提供します。
ここでは Object リソースのサイズが 1000 バイト、Range 有効区間が 0-999 と仮定します。

​
正常リクエスト例

  • Object リソースの 0-499 バイト範囲のコンテンツをリクエストします。
  • Object リソースの第 500 バイトからファイル終端までのコンテンツをリクエストします。
  • Object リソースの末尾 500 バイトのコンテンツをリクエストします。

​
範囲超過リクエスト例

  • 末尾バイト 1000 が有効区間を超えているため、Range は適用されません。レスポンスの戻り値は 200 となり、Object 全体のコンテンツが転送されます。
  • 指定範囲が有効区間を超えているため、Range は適用されません。レスポンスの戻り値は 200 となり、Object 全体のコンテンツが転送されます。

​
互換動作リクエスト例

  • x-oss-range-behavior:standard リクエストヘッダーを追加した場合、末尾バイトが有効区間を超えているため、500-999 バイト範囲のコンテンツを返します。
  • x-oss-range-behavior:standard リクエストヘッダーを追加した場合、先頭バイトが有効区間を超えているため、416 エラーを返します。
  • x-oss-range-behavior:standard リクエストヘッダーを追加した場合、指定範囲が有効区間を超えているため、0-999 バイト、つまりファイル全体のコンテンツを返します。