기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
API Gateway에서 Lambda 오류 처리
Lambda 사용자 지정 통합의 경우에는 Lambda가 통합 응답에서 반환한 오류를 클라이언트에 대한 표준 HTTP 오류 응답으로 매핑해야 합니다. 그렇게 하지 않으면 Lambda 오류는 기본적으로 API 사용자가 직관적으로 이해하기 어려운 200 OK 응답으로 반환됩니다.
Lambda가 반환할 수 있는 오류 유형은 표준 오류와 사용자 지정 오류, 두 가지입니다. API에서 이 두 가지 오류를 다르게 처리해야 합니다.
Lambda 프록시 통합의 경우, Lambda는 다음 형식의 출력을 반환해야 합니다.
{ "isBase64Encoded" : "boolean", "statusCode": "number", "headers": { ... }, "body": "JSON string" }
이 출력에서 statusCode는 일반적으로 클라이언트 오류의 경우 4XX, 서버 오류의 경우 5XX입니다. API Gateway는 지정된 statusCode에 따라 Lambda 오류를 HTTP 오류 응답에 매핑함으로써 이러한 오류를 처리합니다. API Gateway에서 클라이언트에 대한 응답의 일부로 오류 유형(예: InvalidParameterException)을 전달하려면 Lambda 함수가 headers 속성에 헤더(예: "X-Amzn-ErrorType":"InvalidParameterException")를 포함해야 합니다.
API Gateway에서 표준 Lambda 오류 처리
표준 AWS Lambda의 오류 형식은 다음과 같습니다.
{ "errorMessage": "<replaceable>string</replaceable>", "errorType": "<replaceable>string</replaceable>", "stackTrace": [ "<replaceable>string</replaceable>", ... ] }
여기서 errorMessage는 오류의 문자열 표현식입니다. errorType은 언어 종속적 오류 또는 예외 유형입니다. stackTrace는 문자열 표현식 목록으로, 오류를 유발하는 스택 추적을 보여 줍니다.
예를 들어 다음과 같은 JavaScript(Node.js) Lambda 함수를 생각해 보세요.
export const handler = function(event, context, callback) { callback(new Error("Malformed input ...")); };
이 함수는 오류 메시지 Malformed
input ...이 포함된 다음과 같은 표준 Lambda 오류를 반환합니다.
{ "errorMessage": "Malformed input ...", "errorType": "Error", "stackTrace": [ "export const handler (/var/task/index.js:3:14)" ] }
마찬가지로 다음과 같은 Python Lambda 함수를 생각해 보세요. 동일한 Malformed input ... 오류 메시지와 함께 Exception을 야기하는 함수입니다.
def lambda_handler(event, context): raise Exception('Malformed input ...')
이 함수는 다음과 같은 표준 Lambda 오류를 반환합니다.
{ "stackTrace": [ [ "/var/task/lambda_function.py", 3, "lambda_handler", "raise Exception('Malformed input ...')" ] ], "errorType": "Exception", "errorMessage": "Malformed input ..." }
errorType 및 stackTrace 속성 값은 언어 종속적입니다. 또한 이 표준 오류는 Error 객체의 확장이거나 Exception 클래스의 하위 클래스인 모든 오류 객체에 적용됩니다.
표준 Lambda 오류를 메서드 응답에 매핑하려면, 먼저 주어진 Lambda 오류의 HTTP 상태 코드를 결정해야 합니다. 그런 다음 주어진 HTTP 상태 코드와 연결된 IntegrationResponse의 selectionPattern 속성에서 정규 표현식 패턴을 설정합니다. API Gateway 콘솔에서 이 selectionPattern은 각 통합 응답 아래의 통합 응답 섹션에 Lambda 오류 Regex로 표시됩니다.
참고
API Gateway는 응답 매핑을 위해서 Java 패턴 스타일 정규식을 사용합니다. 자세한 내용은 Oracle 설명서의 패턴
예를 들어, selectionPattern를 사용하여 새 AWS CLI 표현식을 설정하려면 put-integration-response 명령을 호출합니다.
aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Malformed.*" --region us-west-2
메서드 응답에 해당하는 오류 코드(400)도 설정해야 합니다. 그렇지 않으면 API Gateway는 실행 시간에 잘못된 구성 오류 응답을 내보냅니다.
참고
실행 시간에 API Gateway는 Lambda 오류의 errorMessage를 메시지를 selectionPattern 속성의 정규식 패턴과 비교합니다. 양쪽이 일치하면 API Gateway는 Lambda 오류를 해당 HTTP 상태 코드의 HTTP 응답으로 반환합니다. 일치하지 않으면 API Gateway는 오류를 기본 응답으로 반환하고, 만일 기본 응답이 구성되어 있지 않으면 잘못된 구성 예외로 내보냅니다.
지정된 응답에 대해 selectionPattern 값을 .*로 설정하면 이 응답이 기본 응답으로 다시 설정됩니다. 이는 해당 선택 패턴이 null(즉. 지정되지 않은 오류 메시지)을 포함하는 모든 오류 메시지와 일치하기 때문입니다. 그 결과로 나타나는 매핑은 기본 매핑을 무시합니다.
selectionPattern를 사용하여 기존의 AWS CLI 값을 업데이트하려면 integrationresponse:update 작업을 호출하여 /selectionPattern 경로 값을 Malformed* 패턴의 지정된 regex 표현식으로 바꿉니다.
API Gateway 콘솔을 사용하여 selectionPattern 표현식을 설정하려면, 지정된 HTTP 상태 코드의 통합 응답을 설정하거나 업데이트할 때 Lambda 오류 Regex 텍스트 상자에 원하는 표현식을 입력합니다.
API Gateway에서 사용자 지정 Lambda 오류 처리
AWS Lambda에서는 사용자 지정 오류 객체를 앞 단원에서 다룬 표준 오류 대신 JSON 문자열로 반환할 수 있습니다. 유효한 모든 JSON 객체를 오류로 사용할 수 있습니다. 예를 들어 다음 JavaScript(Node.js) Lambda 함수는 사용자 지정 오류를 반환합니다.
export const handler = (event, context, callback) => { ... // Error caught here: var myErrorObj = { errorType : "InternalServerError", httpStatus : 500, requestId : context.awsRequestId, trace : { "function": "abc()", "line": 123, "file": "abc.js" } } callback(JSON.stringify(myErrorObj)); };
myErrorObj을 호출하여 함수를 종료하려면 먼저 callback 객체를 JSON 문자열로 변환해야 합니다. 그렇지 않으면 myErrorObj가 "[object Object]"의 문자열로 반환됩니다. API 메서드가 앞의 Lambda 함수와 통합되면 API Gateway는 다음과 같은 페이로드의 통합 응답을 받습니다.
{ "errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}" }
통합 응답과 마찬가지로 이 오류 응답을 그대로 메서드 응답으로 전달할 수 있습니다. 아니면 매핑 템플릿을 사용하여 페이로드를 다른 형식으로 변환할 수도 있습니다. 예를 들어, 500 상태 코드의 메서드 응답이라면 다음과 같은 본문 매핑 템플릿을 고려해 보십시오.
{ errorMessage: $input.path('$.errorMessage'); }
이 템플릿은 사용자 지정 오류 JSON 문자열이 포함된 통합 응답 본문을 다음과 같은 메서드 응답 본문으로 변환합니다. 이 메서드 응답 본문에는 사용자 지정 오류 JSON 객체가 들어 있습니다.
{ "errorMessage" : { errorType : "InternalServerError", httpStatus : 500, requestId : context.awsRequestId, trace : { "function": "abc()", "line": 123, "file": "abc.js" } } };
API 요구 사항에 따라 사용자 지정 오류 속성 중 일부 또는 전부를 메서드 응답 헤더 파라미터로 전달해야 할 수 있습니다. 그러려면 통합 응답 본문의 사용자 지정 오류 매핑을 메서드 응답 헤더에 적용하면 됩니다.
예를 들어, 다음 OpenAPI 확장은 각각 errorMessage.errorType, errorMessage.httpStatus, errorMessage.trace.function 및 errorMessage.trace 속성에서 error_type, error_status, error_trace_function 및 error_trace 헤더로 매핑을 정의합니다.
"x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function", "method.response.header.error_status": "integration.response.body.errorMessage.httpStatus", "method.response.header.error_type": "integration.response.body.errorMessage.errorType", "method.response.header.error_trace": "integration.response.body.errorMessage.trace" }, ... } } }
API Gateway는 실행 시간에 헤더 매핑을 수행할 때 integration.response.body 파라미터를 역직렬화합니다. 그러나 이런 역직렬화는 Lambda 사용자 지정 오류 응답의 본문-헤더 매핑에만 적용되며, $input.body를 사용하는 본문-본문 매핑에는 적용되지 않습니다. 이러한 사용자 지정 오류의 본문-헤더 매핑을 사용할 경우, 클라이언트가 받는 메서드 응답에 다음 헤더가 포함되어 있습니다. 단, 메서드 요청에 error_status, error_trace, error_trace_function, error_type 헤더가 선언되어 있어야 합니다.
"error_status":"500", "error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}", "error_trace_function":"abc()", "error_type":"InternalServerError"
통합 응답 본문의 errorMessage.trace 속성은 복잡한 속성입니다. error_trace 헤더에 JSON 문자열로 매핑됩니다.
