If-Range

사용법

클라이언트는 부분 다운로드를 재개하거나 앞서 받은 리소스에서 특정 바이트 범위를 가져올 때 If-Range를 사용합니다. 이 헤더는 검증자로 ETag 값이나 Last-Modified 날짜 중 하나를 담습니다. 요청당 한 가지 형태만 허용됩니다.

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