9.3. ファイルのダウンロード

GET /1/(tenantId)/files/(bucketName)/(fileName)

ファイルをダウンロードする。

Range 指定による部分ダウンロードをサポートする。

Request Headers:
 
  • X-Application-Id -- アプリケーションID(必須)
  • X-Application-Key -- アプリケーションキー(必須)
  • X-Session-Token -- セッショントークン(オプション)
  • Range -- Range指定(オプション)
  • If-Match -- 前提条件指定 (オプション)
  • If-Range -- 前提条件指定(オプション。Range ヘッダ指定時にのみ指定可能)
Parameters:
  • bucketName (string) -- バケット名
  • fileName (string) -- ファイル名
Status Codes:
Response Headers:
 
  • Content-Disposition -- attachment; filename='ファイル名'
  • X-Content-Length -- ファイルサイズ(バイト数)
  • Content-Length -- 206応答時は指定レンジのバイト数。200応答時はファイル全体のバイト数。
  • ETag -- ファイルのETag（fileETag）。ETag値はダブルクオーテーションで囲む形式。
  • Accept-Ranges -- "bytes" (Range 転送のサポート可能通知)
  • Content-Range -- 206 応答時はレンジ表記。416 応答時は不正レンジ表記。

レスポンス

正常時はファイルデータがレスポンスボディに返却される。

409 Conflict 時は原因をJSONテキスト形式で返す。

レスポンスは、Content-Length ヘッダ付きで返される場合と、Chunked エンコーディング(Content-Length ヘッダなし、Transfer-Encoding: Chunked)で返される場合がある。

  • いずれの場合も、ダウンロードされるファイルサイズは X-Content-Length ヘッダで取得できる。
  • Content-Length ヘッダが指定された場合
    • ファイルの部分ダウンロードの場合は、Content-Length ヘッダの値は指定Rangeのデータのバイト数となる
    • ファイルの全体ダウンロードの場合は、X-Content-Length ヘッダの値は Content-Length ヘッダの値と同一となる。

Chunked エンコーディングを使用中に、サーバ側異常でファイルがダウンロード中に削除された場合:

  • ダウンロードは途中で中断される(エラーにはならない)。
  • この場合は、ダウンロードされたデータサイズと X-Content-Length を比較し、一致していない場合はクライアント側でエラーとすること。

部分ダウンロード(Range)

RFC 7233の規定に従い、Rangeヘッダに指定する範囲にはデータのバイト開始位置と終了位置を指定する(0オリジン)。

  • 例えば、ファイル全ての範囲の指定には、"0-" または "0-(ファイルサイズ-1)" を使用する。
  • Rangeヘッダは単一Range指定のみをサポートする。複数Range指定があった場合はヘッダ指定不正とみなし、400 Bad Requestを返す。

以下に例を示す。:

# 開始位置と終了位置の指定（指定位置間のデータ）
Range: bytes=101-200
# 開始位置のみ指定（指定位置から、データの終了位置までのデータ）
Range: bytes=101-
#　最後のバイト数指定（データの終了位置から、指定バイトまでのデータ）
Range: bytes=-200
# 複数Range範囲の指定は不可
Range: bytes=101-200,300-500

If-Match ヘッダの値は、ETag（ファイルのETag）のみをサポートする。

  • 単一指定のみをサポートする。複数指定と全指定（*）をサポートしない。
  • 強い形式の比較のみをサポートする。弱い(W/"…")形式の比較をサポートしない。
  • RFCに従い、ETag値の形式はダブルクオーテーションで囲む。
  • ただし、ダブルクオーテーションが無くても、設定可能

例:

If-Match: “123456789”
If-Match: 123456789

ETag 値と不一致の場合は、412 Precondition Failedで応答する。If-MatchはIf-Rangeより先に評価される。

If-RangeヘッダはRangeヘッダが存在する場合に限り設定が可能。

  • Rangeヘッダが存在しない場合は無視される。
  • If-Range ヘッダの値は、ETagのみをサポートする。ETag値の形式と設定方法はIf-Matchと同様。
  • ETag 値と一致する場合は、206で応答する。ETtag 値と不一致の場合は200で応答し、Rangeヘッダを無視し、ファイルの全データを返却する。

Content-Range レスポンスヘッダには、返却データのRangeが通知される。:

# 206 Partial Content 応答の場合、返却データの「開始位置-終了位置/データ長」を通知する
Content-Range: bytes 0-100/500

# 指定Range不正（416 Range Not Satisfiable の応答）の場合、
# Range不正を示す「アスタリスク （ "*" ）/データ長」で通知する
Content-Range: bytes */500

注意事項

  • バケットcontentACLと対象ファイルの read 権限が必要。