요청 트리거에서 HTTP 응답 생성 - Amazon CloudFront

요청 트리거에서 HTTP 응답 생성

CloudFront 요청을 수신할 때 Lambda 함수를 사용하여 CloudFront가 오리진에 응답을 전달하지 않고 최종 사용자에게 직접 반환하는 HTTP 응답을 생성할 수 있습니다. HTTP 응답을 생성하면 오리진에 대한 로드가 감소하고 일반적으로 최종 사용자에 대한 지연 시간 또한 감소합니다.

HTTP 응답 생성의 몇 가지 일반 시나리오는 다음을 포함합니다.

  • 최종 사용자에게 소규모 웹 페이지 반환

  • HTTP 301 또는 302 상태 코드를 반환하여 다른 웹 페이지로 사용자를 리디렉션

  • 사용자가 인증되지 않았을 때 최종 사용자에게 HTTP 401 상태 코드 반환

Lambda@Edge 함수는 다음 CloudFront 이벤트가 발생할 때 HTTP 응답을 생성할 수 있습니다.

최종 사용자 요청 이벤트

최종 사용자 요청 이벤트에 의해 함수가 트리거될 때 CloudFront는 최종 사용자에게 응답을 반환하고 이를 캐싱하지 않습니다.

오리진 요청 이벤트

오리진 요청 이벤트에 의해 함수가 트리거될 때 CloudFront는 함수에 의해 이전에 생성된 응답에 대한 엣지 캐시를 확인합니다.

  • 응답이 캐시에 있는 경우 함수는 실행되지 않고 CloudFront는 캐싱된 응답을 최종 사용자에게 반환합니다.

  • 응답이 캐시에 없는 경우 함수는 실행되고 CloudFront는 캐싱된 응답을 최종 사용자에게 반환하며 이를 캐싱합니다.

HTTP 응답을 생성하는 몇 가지 샘플 코드를 보려면 Lambda@Edge 함수 예제 단원을 참조하십시오. 응답 트리거에서 HTTP 응답을 바꿀 수도 있습니다. 자세한 내용은 오리진 응답 트리거에서 HTTP 응답 업데이트 단원을 참조하세요.

프로그래밍 모델

이 단원에서는 Lambda@Edge를 사용하여 HTTP 응답을 생성하기 위한 프로그래밍 모델을 설명합니다.

응답 객체

result 메서드의 callback파라미터로 반환한 응답은 다음 구조를 가져야 합니다(status 필드만이 필요함).

const response = { body: 'content', bodyEncoding: 'text' | 'base64', headers: { 'header name in lowercase': [{ key: 'header name in standard case', value: 'header value' }], ... }, status: 'HTTP status code', statusDescription: 'status description' };

응답 객체에는 다음 값이 포함될 수 있습니다.

body

CloudFront가 생성된 응답에서 반환하고자 하는 본문입니다.

bodyEncoding

body에서 지정한 값에 대한 인코딩입니다. 유일하게 유효한 인코딩은 textbase64입니다. response 객체에 body를 포함했지만 bodyEncoding을 누락한 경우 CloudFront는 본문을 텍스트로 처리합니다.

bodyEncodingbase64로 지정하지만 본문이 유효한 base64가 아닌 경우 CloudFront는 오류를 반환합니다.

headers

CloudFront가 생성된 응답에서 반환하고자 하는 헤더입니다. 다음을 참조하십시오.

  • headers 객체 내 키는 표준 HTTP 헤더 이름의 소문자 버전입니다. 소문자 키를 사용하여 대/소문자를 구분하지 않고 헤더 값에 액세스할 수 있습니다.

  • 각 헤더(예: headers["accept"] 또는 headers["host"])는 키-값 페어의 어레이입니다. 해당 헤더에 대해 어레이에는 생성된 응답의 각 값에 대한 하나의 키-값 페어를 포함합니다.

  • key(선택사항)는 HTTP 요청에 표시되는 헤더의 대/소문자 구분 이름입니다(예: accept 또는 host).

  • value를 헤더 값으로 지정합니다.

  • 키-값 페어의 헤더 키 부분을 포함시키지 않으면 Lambda@Edge는 사용자가 입력한 헤더 이름을 사용하여 헤더 키를 자동으로 삽입합니다. 헤더 이름의 형식을 어떻게 지정했든 상관없이, 자동으로 삽입된 헤더 키는 각 부분의 첫 문자가 대문자로 지정되고 각 부분이 하이픈(-)으로 구분됩니다.

    예를 들어 헤더를 다음과 같이 헤더 키 없이 추가할 수 있습니다. 'content-type': [{ value: 'text/html;charset=UTF-8' }]

    이 예제에서 Lambda@Edge는 다음과 같은 헤더 키를 생성합니다. Content-Type

헤더 사용 시 제한 사항에 대한 자세한 내용은 헤더 단원을 참조하십시오.

status

CloudFront가 다음에 대해 사용하고자 하는 HTTP 상태 코드입니다.

status 값이 200~599가 아닌 경우 CloudFront는 최종 사용자에게 오류를 반환합니다.

statusDescription

CloudFront가 응답에서 반환하고 HTTP 상태 코드를 포함하고자 하는 설명입니다. HTTP 상태 코드 200에 대해 OK와 같은 표준 설명을 사용할 필요는 없습니다.

오류

다음은 생성된 HTTP 응답에서 발생할 수 있는 오류입니다.

본문을 포함하고 상태에 대해 204(콘텐츠 없음)을 지정한 응답

최종 사용자 요청 이벤트에 의해 함수가 트리거될 때 CloudFront는 다음 두 가지가 모두 true일 경우 HTTP 502 상태 코드(잘못된 게이트웨이)를 반환합니다.

  • status의 기본값이 204(콘텐츠 없음)임

  • 응답에 body에 대한 값이 포함

이는 Lambda@Edge가 HTTP 204 응답에 메시지 본문이 포함될 필요가 없다고 명시한 RFC 2616의 선택적인 제한을 부과하기 때문입니다.

생성된 응답의 크기 제한

Lambda 함수가 생성하는 응답의 최대 크기는 함수를 트리거한 이벤트에 따라 다릅니다.

  • 최종 사용자 요청 이벤트 - 40KB

  • 오리진 요청 이벤트 - 1MB

응답이 허용된 크기보다 큰 경우 CloudFront는 최종 사용자에게 HTTP 502 상태 코드(잘못된 게이트웨이)를 반환합니다.

필수 필드

status 필드는 필수입니다.

다른 모든 필드는 선택 사항입니다.