REST API에서 API Gateway 통합에 대한 응답 상태 코드를 매핑하려면 어떻게 해야 하나요?

해결 방법

백엔드 응답 상태 코드를 재정의하려면 API Gateway 매핑 템플릿 또는 정규 표현식을 사용하여 상태 코드를 매핑합니다. REST API와의 프록시 및 비프록시 통합에서 이 작업을 수행할 수 있습니다.

프록시 및 비프록시 통합은 REST API에서 응답 상태 코드를 매핑하는 데 사용됩니다. 프록시 응답이 있는 경우 API Gateway는 백엔드에서 전송된 상태 코드를 수신합니다. Lambda 프록시 통합에서 API Gateway는 백엔드 Lambda 함수가 다음 출력을 JSON 형식으로 반환하도록 요구합니다.

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode, 
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": “…”65411
}

Lambda 함수와의 프록시 통합에서 상태 코드는 백엔드 Lambda 함수에서 API Gateway로 직접 전달됩니다. 비프록시 통합에서는 Lambda 함수에서 상태 코드를 직접 전달할 수 없습니다.

API Gateway가 Lambda 함수를 성공적으로 호출하는 경우 기본 응답 상태 코드는 200입니다. Lambda에 오류가 발생하는 경우에도 상태 코드가 반환됩니다. API Gateway 응답 코드를 사용자 지정할 수 있습니다. 사용자 지정 응답 코드를 생성해야 하는 경우 비프록시 통합 및 매핑 템플릿을 사용합니다.

사용자 지정 코드로 응답 메서드 구성

API Gateway의 사용자 지정 응답 코드로 응답하도록 메서드를 구성하려면 다음 단계를 따르세요.

1.    API Gateway 콘솔에서 퍼블릭 REST API를 생성합니다.

2.    리소스와 리소스에 대한 메서드를 생성합니다.

3.    API Gateway에서 반환하려는 상태 코드가 포함된 메서드 응답을 설정합니다.

4.    Lambda 통합 응답을 구성합니다.

• Lambda Error Regex(Lambda 오류 Regex)에 Lambda 함수가 반환하는 오류 메시지의 정규 표현식 패턴을 제공합니다.
  참고: HTTP 응답에 대한 HTTP 오류 정규식도 찾을 수 있습니다.
• 메서드 응답 상태를 보려면 API Gateway에서 반환해야 하는 상태 코드를 제공합니다.
• Content Handling(콘텐츠 처리) 옵션을 선택하여 응답이 클라이언트에 전송되기 전에 응답 본문이 처리되는 방식을 설정합니다.
• 상태 코드의 기본 패턴이 200으로 설정되어 있는지 확인합니다.

5.    통합 응답 구성을 완료한 후 변경 사항을 저장, 테스트 및 배포합니다.

정적 값에 상태 코드 매핑

API Gateway가 백엔드에서 반환된 상태 코드 그룹을 캡처하도록 하려면 정적 값에 상태 코드를 매핑합니다.

1.    변경하려는 상태 코드가 있는 리소스로 이동합니다.

2.    400을 API Gateway 응답 코드로 반환하도록 메서드 응답을 설정합니다.

3.    리소스 구성으로 돌아가서 통합 응답을 설정합니다.

4.    HTTP status regex(HTTP 상태 regex)의 값은 백엔드에서 반환한 상태를 캡처합니다. 그러면 상태가 2단계에서 정의한 응답 코드에 매핑됩니다.

HTTP status regex(HTTP 상태 regex)의 기본값이 '-'이고 메서드 응답 상태로 200에 매핑되면 모든 상태 코드가 캡처되어 백엔드 맵에서 200으로 반환됩니다. HTTP status regex(HTTP 상태 regex) 값을 **2\d{2}**로 변경하여 모든 2xx 응답을 캡처하고 200에 매핑할 수 있습니다.

5.    Add integration response(통합 응답 추가)를 선택하여 다른 상태 코드를 캡처합니다.

4xx의 경우 HTTP status regex(HTTP 상태 regex)에서 **4\d{2}**를 추가합니다. Method response status(메서드 응답 상태)에서 400을 선택합니다. 이는 2단계에서 정의되었습니다.

6.    API를 배포합니다. API가 2xx 상태 코드를 반환하면 해당 상태 코드가 200 상태 코드에 매핑됩니다. API가 4xx 상태 코드를 반환하면 해당 상태 코드가 400 상태 코드에 매핑됩니다.

정규 표현식은 다양한 방식으로 형식을 지정할 수 있습니다. 예를 들면 다음과 같습니다.

• .*([01][0-9][0-9]|2[0-4][0-9]|25[0-5]).*는 100-199, 200-249 또는 250-255 사이의 상태 코드와 일치합니다.
• .*5\d\d.*는 5xx와 같은 상태 코드와 일치합니다.

다음 예제 코드는 Lambda 함수를 테스트하기 위한 것입니다

def lambda_handler(event, context):
    if "error" not in event or event['error'] == "":
        return("Pass")
    elif event['error'] == 'sample 400':
        raise Exception({"errorMessage": "Error: Raising 400 from within the Lambda function","errorType": "Exception"})
    elif event['error'] == 'sample 500':
        raise Exception({"errorMessage": "Error: Raising 500 from within the Lambda function","errorType": "Exception"})
    else:
        return("Error Value in the json request should either be 400 or 500 to demonstrate")

이 예제의 코드는 API Gateway에서 전송된 오류 값이 400 또는 500 오류인지 확인합니다. 400 또는 500 오류인 경우 Lambda 코드는 오류 메시지와 함께 예외를 발생시킵니다. API Gateway가 응답을 수신하면 서비스는 오류 메시지가 통합 응답에 구성된 패턴과 일치하는지 확인합니다. Lambda 정규식 패턴이 일치하면 API Gateway가 그에 따라 응답합니다.

7.    구성이 성공적으로 완료되면 API Gateway 콘솔을 사용하여 상태 코드를 테스트할 수 있습니다.

매핑 템플릿으로 상태 코드 매핑

이전 예제에서는 정규 표현식을 사용하지만 매핑 템플릿을 사용할 수도 있습니다. 다음은 백엔드의 200 상태 코드를 재정의하여 400 상태 코드를 적용하는 예제입니다.

1.    다음 예제 코드를 사용하여 Lambda 함수를 생성합니다.

----------------------
def lambda_handler(event, context):
    # TODO implement print(event)
    return { 'statusCode': 200, 'body': "customerror" }
-----------------------

2.    백엔드에 대한 이전 Lambda 함수를 사용하여 Lambda 비프록시 통합으로 API를 생성합니다.

3.    API Gateway 콘솔로 API의 응답 상태 코드 재정의 자습서에 설명된 6~10단계를 따릅니다.

이 예제에서는 다음 매핑 템플릿을 사용합니다.

----------------------
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("customerror"))
#set($context.responseOverride.status = 400)
#end 
----------------------

4.    API를 저장, 테스트 및 배포합니다.

---

관련 정보

모델 및 매핑 템플릿 작업

API 요청 및 응답 변환

Amazon API Gateway 개발자 안내서