Range 및 partNumber 헤더 사용

Range 및 partNumber 헤더 사용 (Working with Range and partNumber headers)

S3 Object Lambda에서 큰 객체를 다룰 때 Range HTTP 헤더를 사용해 객체에서 지정한 바이트 범위를 내려받을 수 있어요. 같은 객체 안에서 서로 다른 바이트 범위를 가져오려면 Amazon S3에 동시 연결을 사용하면 돼요. 또한 partNumber 파라미터(1~10,000 사이의 정수)를 지정해 객체의 지정된 부분에 대한 범위 요청을 수행할 수도 있어요.

참고 2025년 11월 7일부터 S3 Object Lambda는 현재 이 서비스를 사용 중인 기존 고객과 일부 AWS 파트너 네트워크(APN) 파트너만 이용할 수 있어요. S3 Object Lambda와 비슷한 기능이 필요하다면 Amazon S3 Object Lambda 가용성 변경 문서를 확인해 주세요.

출처: 문서

본문

Range나 partNumber 파라미터를 포함한 요청을 처리하는 방법은 여러 가지가 있을 수 있기 때문에, S3 Object Lambda는 이 파라미터들을 변환된 객체에 적용하지 않아요. 대신 여러분의 AWS Lambda 함수가 애플리케이션에 필요한 대로 이 기능을 구현해야 해요.

S3 Object Lambda에서 Range 및 partNumber 파라미터를 사용하려면 다음을 수행해요.

1. Object Lambda 접근 지점 구성에서 이 파라미터들을 활성화해요.
2. 이 파라미터들을 포함하는 요청을 처리할 수 있는 Lambda 함수를 작성해요.

다음 단계에서 그 방법을 설명할게요.

1단계: Object Lambda 접근 지점 구성

기본적으로 Object Lambda 접근 지점은 헤더나 쿼리 파라미터에 Range 또는 partNumber 파라미터가 포함된 GetObject 또는 HeadObject 요청에 HTTP 상태 코드 501(Not Implemented) 오류로 응답해요.

Object Lambda 접근 지점이 이러한 요청을 수락하도록 하려면 Object Lambda 접근 지점 구성의 AllowedFeatures 섹션에 GetObject-Range, GetObject-PartNumber, HeadObject-Range 또는 HeadObject-PartNumber를 포함해야 해요. Object Lambda 접근 지점 구성 업데이트에 대한 자세한 내용은 Object Lambda 접근 지점 만들기를 참고하세요.

2단계: Lambda 함수에 Range 또는 partNumber 처리 구현

Object Lambda 접근 지점이 범위 요청인 GetObject 또는 HeadObject로 Lambda 함수를 호출하면 Range 또는 partNumber 파라미터가 이벤트 컨텍스트에 포함돼요. 파라미터가 이벤트 컨텍스트의 어디에 위치하는지는 어떤 파라미터를 사용했는지, 그리고 Object Lambda 접근 지점에 대한 원래 요청에 어떻게 포함되었는지에 따라 달라지는데, 다음 표와 같아요.

중요 Object Lambda 접근 지점에 대해 제공되는 사전 서명 URL에는 원래 요청의 Range 또는 partNumber 파라미터가 포함되지 않아요. 이러한 파라미터를 Lambda 함수에서 처리하는 방법에 대한 옵션은 아래를 참고하세요.

Range 또는 partNumber 값을 추출한 뒤에는 애플리케이션의 필요에 따라 다음 접근 방식 중 하나를 사용할 수 있어요.

요청된 Range 또는 partNumber를 변환된 객체에 매핑(권장)

Range 또는 partNumber 요청을 처리하는 가장 확실한 방법은 다음을 수행하는 거예요.

1. Amazon S3에서 전체 객체를 검색해요.
2. 객체를 변환해요.
3. 요청된 Range 또는 partNumber 파라미터를 변환된 객체에 적용해요.

이렇게 하려면 제공된 사전 서명 URL을 사용해 Amazon S3에서 전체 객체를 가져온 다음 필요에 따라 객체를 처리하면 돼요. 이 방식으로 Range 파라미터를 처리하는 Lambda 함수 예제는 AWS Samples GitHub 리포지토리의 이 샘플을 참고하세요.

요청된 Range를 사전 서명 URL에 매핑

경우에 따라 Lambda 함수는 요청된 Range를 사전 서명 URL에 직접 매핑해 Amazon S3에서 객체의 일부분만 검색할 수 있어요. 이 접근 방식은 여러분의 변환이 다음 두 기준을 모두 충족할 때만 적절해요.

• 변환 함수가 부분 객체 범위에 적용될 수 있어야 해요.
• 변환 함수 전후에 Range 파라미터를 적용해도 결과가 같은 변환 객체가 되어야 해요.

예를 들어 ASCII로 인코딩된 객체의 모든 문자를 대문자로 변환하는 변환 함수는 위 두 기준을 모두 충족해요. 변환을 객체 일부에 적용할 수 있고, 변환 전에 Range 파라미터를 적용하는 것이 변환 후에 적용하는 것과 같은 결과를 내니까요.

반면 ASCII로 인코딩된 객체의 문자를 뒤집는 함수는 이 기준을 충족하지 못해요. 이런 함수는 부분 객체 범위에 적용할 수 있으므로 기준 1은 충족하지만, 변환 전에 Range 파라미터를 적용하는 것과 변환 후에 적용하는 것이 서로 다른 결과를 내므로 기준 2는 충족하지 못해요.

abcdefg라는 내용을 가진 객체의 처음 세 문자에 함수를 적용하는 요청을 생각해 볼게요. 변환 전에 Range 파라미터를 적용하면 abc만 검색한 뒤 데이터를 뒤집어 cba를 반환해요. 하지만 변환 후에 파라미터를 적용하면 함수가 전체 객체를 검색해 뒤집은 다음 Range 파라미터를 적용해 gfe를 반환해요. 결과가 다르기 때문에 이 함수는 Amazon S3에서 객체를 검색할 때 Range 파라미터를 적용하면 안 돼요. 대신 전체 객체를 검색해 변환을 수행하고 그다음에만 Range 파라미터를 적용해야 해요.

경고 대부분의 경우 Range 파라미터를 사전 서명 URL에 적용하면 Lambda 함수나 요청 클라이언트가 예상치 못한 동작을 보일 수 있어요. Amazon S3에서 부분 객체만 검색할 때 애플리케이션이 제대로 작동한다고 확신하지 않는다면, 앞서 접근 방식 A에서 설명한 대로 전체 객체를 검색하고 변환하는 것을 권장해요.

애플리케이션이 앞서 설명한 접근 방식 B의 기준을 충족하면, 요청된 객체 범위만 가져온 다음 그 범위에 변환을 실행해 Lambda 함수를 단순화할 수 있어요.

다음 Java 코드 예제는 다음을 수행하는 방법을 보여줘요.

• GetObject 요청에서 Range 헤더를 검색해요.
• Lambda가 Amazon S3에서 요청된 범위를 검색하는 데 사용할 수 있는 사전 서명 URL에 Range 헤더를 추가해요.

private HttpRequest.Builder applyRangeHeader(ObjectLambdaEvent event, HttpRequest.Builder presignedRequest)
{
    var header = event.getUserRequest().getHeaders().entrySet().stream()
            .filter(e -> e.getKey().toLowerCase(Locale.ROOT).equals("range"))
            .findFirst();

    // Add check in the query string itself.
    header.ifPresent(entry -> presignedRequest.header(entry.getKey(), entry.getValue()));
    return presignedRequest;
}

더 알아보기 (Learn more)

• 이벤트 컨텍스트 형식 및 사용법
• AWS 내장 함수 사용