If-Range

使い方

クライアントは、部分的なダウンロードを再開する場合や、以前に取得したリソースから特定のバイト範囲を取得する場合に If-Range を使います。このヘッダーは検証子として ETag 値か Last-Modified の日付のいずれかを運びます。1 つのリクエストで許されるのはどちらか一方の形式だけです。

If-Match との決定的な違いは、条件が成立しなかったときの挙動です。If-Match の失敗は 412 Precondition Failed エラーを生み、リクエストは中断されます。If-Range の失敗は穏やかに成功します。サーバーは Range ヘッダーを無視し、リソース全体をステータス 200 で返します。これによりクライアントは常に利用可能なデータを受け取れるため、If-Range はダウンロード再開においてより安全です。

If-Range を使う条件付きリクエストには、同じリクエスト内に Range ヘッダーが必要です。Range ヘッダーがなければ、サーバーは If-Range を完全に無視します。

entity-tag

以前にサーバーから受け取った ETag 値です。値は引用符で囲まれた文字列であり、強い検証子でなければなりません。W/ を前置した弱い ETag は If-Range では許可されません。

If-Range: "abc123"

HTTP-date

標準的な HTTP の日付形式による Last-Modified のタイムスタンプです。サーバーはこの日付をリソースの現在の更新日時と比較します。

If-Range: Wed, 01 Jun 2022 08:00:00 GMT

注意

If-Range ヘッダーは ETag か日付のどちらかを運びます。同じリクエストで両方の形式を使うことはできません。

例

クライアントは以前に大きなファイルの一部をダウンロードし、最初のレスポンスで ETag を受け取っています。1048576 バイト目からダウンロードを再開するため、クライアントは Range ヘッダーと、保存しておいた ETag を含む If-Range ヘッダーの両方を送ります。ファイルが変更されていなければ、サーバーは 206 Partial Content で応答します。

GET /releases/archive.tar.gz HTTP/1.1
Host: cdn.example.re
Range: bytes=1048576-
If-Range: "a1b2c3d4e5"

最初のダウンロード以降にリソースが変更されていた場合、ETag はもう一致しません。サーバーは Range を破棄し、完全なファイルをステータス 200 で返します。

HTTP/1.1 200 OK
Content-Length: 52428800
ETag: "f6g7h8i9j0"

日付ベースの検証子も同じように動作します。次のリクエストは、指定したタイムスタンプ以降にファイルが変更されていない場合にのみダウンロードを再開します。

GET /data/export.csv HTTP/1.1
Host: api.example.re
Range: bytes=524288-
If-Range: Sat, 15 Feb 2025 12:00:00 GMT