요청 및 응답 작업 수행 - Amazon CloudFront

요청 및 응답 작업 수행

Lambda@Edge 요청 및 응답을 사용하려면 다음 주제를 참조하세요.

오리진 장애 조치와 함께 Lambda@Edge 함수 사용

예를 들어 고가용성 확보를 위해 구성하는 오리진 장애 조치에 대하여 오리진 그룹과 함께 설정한 CloudFront 배포와 함께 Lambda@Edge 함수를 사용할 수 있습니다. 오리진 그룹과 함께 Lambda 함수를 사용하려면, 캐시 동작을 생성할 때 오리진 그룹에 대한 오리진 요청 또는 오리진 응답 트리거에 함수를 지정합니다.

자세한 내용은 다음 자료를 참조하세요.

요청 트리거에서 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 (string)', 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

HTTP 상태 코드 . 상태 코드를 문자열로 제공합니다. CloudFront는 다음에 대해 제공된 상태 코드를 사용합니다.

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

statusDescription

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

Errors

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

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

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

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

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

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

생성된 응답의 크기 제한

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

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

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

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

필수 필드

status 필드는 필수 사항입니다.

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

오리진 응답 트리거에서 HTTP 응답 업데이트

CloudFront가 오리진 서버에서 HTTP 응답을 수신할 때 오리진 응답 트리거가 캐시 동작과 연결된 경우 HTTP 응답을 수정하여 오리진에서 반환된 것을 재정의할 수 있습니다.

HTTP 응답 업데이트의 몇 가지 일반 시나리오는 다음을 포함합니다.

참고

함수는 200~599(경계값 포함) 사이의 상태 값을 반환해야 합니다. 그렇지 않으면 CloudFront가 최종 사용자에게 오류를 반환합니다.

최종 사용자 및 오리진 요청 이벤트에서 HTTP 응답을 바꿀 수도 있습니다. 자세한 내용은 요청 트리거에서 HTTP 응답 생성 단원을 참조하십시오.

HTTP 응답을 사용하여 작업 중일 때 Lambda@Edge는 오리진 서버에 의해 오리진 응답 트리거로 반환되는 본문을 공개하지 않습니다. 원하는 값으로 설정하여 정적 콘텐츠 본문을 생성하거나 값을 비어 있음으로 설정하여 함수 내부의 본문을 제거할 수 있습니다. 함수의 본문 필드를 업데이트하지 않은 경우 오리진 서버에서 반환된 원래 본문이 최종 사용자에게 반환됩니다.

본문 포함 옵션을 선택해 요청 본문에 액세스

Lambda 함수에서 액세스할 수 있도록 Lambda@Edge가 본문에 쓰기 가능한 HTTP 메서드(POST, PUT, DELETE 등)에 대한 요청을 노출하도록 선택할 수 있습니다. 읽기 전용 액세스 권한을 선택하거나 본문을 바꾸도록 지정할 수 있습니다.

이 옵션을 활성화하려면 함수에 대해 최종 사용자 요청 또는 오리진 요청 이벤트에 대해 실행되는 CloudFront 트리거를 생성할 때 본문 포함을 선택합니다. 자세한 내용은 Lambda@Edge 함수에 대한 트리거 추가 단원을 참조하고, 함수에서 본문 포함을 사용하는 방법을 알아보려면 Lambda@Edge 이벤트 구조 단원을 참조하세요.

이 기능을 사용하려는 시나리오는 다음과 같을 수 있습니다.

  • 오리진 서버로 고객 입력 데이터를 다시 보내지 않는 웹 양식(예: "문의처") 처리

  • 최종 사용자의 브라우저가 보낸 웹 비콘 데이터를 수집해 엣지에서 처리

샘플 코드에 대한 내용은 Lambda@Edge 예제 함수 섹션을 참조하십시오.

참고

요청 본문이 크면 Lambda@Edge가 자릅니다. 최대 크기 및 잘림에 대한 자세한 내용은 본문 포함 옵션이 적용된 요청 본문에 대한 제한 사항 단원을 참조하세요.