API Gateway 콘솔을 사용하여 요청 및 응답 데이터 매핑 설정 - Amazon API Gateway

API Gateway 콘솔을 사용하여 요청 및 응답 데이터 매핑 설정

API Gateway 콘솔을 사용하여 API 통합 요청/응답을 정의하려면 다음 지침을 따르세요.

참고

이 지침에서는 API Gateway 콘솔을 사용하여 API 통합 요청 설정 단원의 단계를 이미 완료한 것으로 가정합니다.

  1. 리소스 창에서 사용자의 메서드를 선택합니다.

  2. 통합 요청 탭의 통합 요청 설정에서 편집을 선택합니다.

  3. 요청 본문 패스스루에 대한 옵션을 선택하여 매핑되지 않은 콘텐츠 유형의 메서드 요청 본문이 Lambda 함수, HTTP 프록시 또는 AWS 서비스 프록시로의 변환 없이 통합 요청을 통해 전달되는 방식을 구성합니다. 여기에는 다음과 같은 세 가지 옵션이 있습니다.

    • 메서드 요청 콘텐츠 유형이 매핑 템플릿과 연결된 임의의 콘텐츠 유형과 일치하지 않은 경우 메서드 요청 본문이 통합 요청을 변환하지 않고 백엔드에 전달하도록 하려면 요청의 content-type 헤더와 일치하는 템플릿이 없는 경우를 선택합니다.

      참고

      API Gateway API를 호출하는 경우 통합 리소스상에서 WHEN_NO_MATCHpassthroughBehavior 속성 값으로 설정함으로써 이 옵션을 선택합니다.

    • 매핑 템플릿이 통합 요청에 정의되어 있지 않을 때 메서드 요청 본문이 통합 요청을 변환 없이 벡엔드에 전달하도록 하려는 경우 When there are no templates defined (recommended)(정의된 템플릿이 없는 경우(권장))를 선택합니다. 이 옵션을 선택할 때 템플릿이 정의되어 있는 경우 매핑되지 않은 콘텐츠 유형의 메서드 요청은 HTTP 415 미지원 미디어 유형 응답과 함께 거부됩니다.

      참고

      API Gateway API를 호출하는 경우 통합 리소스상에서 WHEN_NO_TEMPLATEpassthroughBehavior 속성 값으로 설정함으로써 이 옵션을 선택합니다.

    • 메서드 요청 콘텐츠 유형이 통합 요청에 정의된 매핑 템플릿과 연결된 임의의 콘텐츠 유형과 일치하지 않거나 통합 요청에 매핑 템플릿이 정의되어 있지 않은 경우 메서드 요청이 전달하지 않도록 하려면 없음을 선택합니다. 매핑되지 않은 콘텐츠 유형의 메서드 요청은 HTTP 415 미지원 미디어 유형 응답과 함께 거부됩니다.

      참고

      API Gateway API를 호출하는 경우 통합 리소스상에서 NEVERpassthroughBehavior 속성 값으로 설정함으로써 이 옵션을 선택합니다.

    통합 패스스루 동작에 관한 자세한 정보는 통합 패스스루 동작을 참조하십시오.

  4. HTTP 프록시 또는 AWS 서비스 프록시에 대해 통합 요청에 정의된 경로 파라미터, 쿼리 문자열 파라미터 또는 헤더 파라미터를 HTTP 프록시 또는 AWS 서비스 프록시의 메서드 요청에 정의된 상응하는 경로 파라미터, 쿼리 문자열 파라미터 또는 헤더 파라미터와 연결하려면, 다음을 수행합니다.

    1. URL 경로 파라미터, URL 쿼리 문자열 파라미터 또는 HTTP 요청 헤더를 각각 선택한 다음 경로 추가, 쿼리 문자열 추가 또는 헤더 추가를 각각 선택합니다.

    2. 이름에 HTTP 프록시 또는 AWS 서비스 프록시에 있는 경로 파라미터, 쿼리 문자열 파라미터 또는 헤더 파라미터의 이름을 입력합니다.

    3. 다음에서 매핑됨에 경로 파라미터, 쿼리 문자열 파라미터 또는 헤더 파라미터의 매핑 값을 입력합니다. 다음 형식 중 하나를 사용합니다.

      • 메서드 요청 페이지에 정의된 parameter-name이라는 경로 파라미터에 대한 method.request.path.parameter-name.

      • 메서드 요청 페이지에 정의된 parameter-name이라는 쿼리 문자열 파라미터에 대한 method.request.querystring.parameter-name.

      • 메서드 요청 페이지에 정의된 parameter-name이라는 다중 값 쿼리 문자열 파라미터에 대한 method.request.multivaluequerystring.parameter-name.

      • 메서드 요청 페이지에 정의된 parameter-name이라는 헤더 파라미터에 대한 method.request.header.parameter-name.

        아니면 리터럴 문자열 값(작은 따옴표 쌍으로 묶음)을 통합 헤더에 설정할 수 있습니다.

      • 메서드 요청 페이지에 정의된 parameter-name이라는 다중 값 헤더 파라미터에 대한 method.request.multivalueheader.parameter-name.

    4. 다른 파라미터를 추가하려면 추가 버튼을 선택합니다.

  5. 매핑 템플릿을 추가하려면 매핑 템플릿을 선택합니다.

  6. 수신되는 요청에 대한 매핑 템플릿을 정의하려면 매핑 템플릿 추가를 선택합니다. 콘텐츠 유형에 콘텐츠 유형(예:application/json)을 입력합니다. 그런 다음 매핑 템플릿을 입력합니다. 자세한 내용은 REST API용 매핑 템플릿 단원을 참조하십시오.

  7. Save(저장)를 선택합니다.

  8. 백엔드에서 받은 통합 응답을 호출 앱에 반환되는 API의 메서드 응답에 매핑할 수 있습니다. 백엔드에서 가용한 것 중 클라이언트가 선택한 응답 헤더에 반환하거나, 백엔드 응답 페이로드의 데이터 형식을 API 지정 형식으로 변환하는 것이 여기에 포함됩니다. 메서드 응답통합 응답을 구성하여 그와 같은 매핑을 지정할 수 있습니다.

    메서드가 Lambda 함수, HTTP 프록시 또는 AWS 서비스 프록시에서 반환한 HTTP 상태 코드를 기반으로 사용자 지정 응답 데이터 형식을 수신하도록 하려면 다음을 수행하세요.

    1. 통합 응답을 선택합니다. 기본값 - 응답에서 편집을 선택하여 메서드에서 200 HTTP 응답 코드에 대한 설정을 지정하거나, 응답 생성을 선택하여 메서드에서 임의의 다른 HTTP 응답 상태 코드에 대한 설정을 지정합니다.

    2. Lambda 오류 regex(Lambda 함수의 경우) 또는 HTTP 상태 regex(HTTP 프록시 또는 AWS 서비스 프록시)에 표현식을 입력하여 어떤 Lambda 함수 오류 문자열(Lambda 함수의 경우) 또는 HTTP 응답 상태 코드(HTTP 프록시 또는 AWS 서비스 프록시)를 출력 매핑에 매핑할지 지정합니다. 예를 들어, 모든 2xx HTTP 응답 상태 코드를 HTTP 프록시에서 이 출력 매핑으로 매핑하려면 HTTP status regex(HTTP 상태 regex)에서 '2\d{2}'를 입력합니다. Lambda 함수에서 “Invalid Request”를 포함하는 오류 메시지를 400 Bad Request 응답으로 반환하려면 “.*Invalid request.*”를 Lambda 오류 regex 표현식으로 입력합니다. Lambda로부터 받은 매핑되지 않은 오류 메시지 모두에 대해 400 Bad Request를 반환하려면 Lambda 오류 regex에 “(\n|.)+”을 입력합니다. 이 마지막 표현식은 API의 기본 오류 응답에 사용할 수 있습니다.

      참고

      API Gateway는 응답 매핑을 위해서 Java 패턴 스타일 정규식을 사용합니다. 자세한 내용은 Oracle 설명서의 패턴 단원을 참조하십시오

      오류 패턴은 Node.js의 callback(errorMessage)나 Java의 throw new MyException(errorMessage)에 의해 채워지는 Lambda 응답에 있는 errorMessage 속성의 전체 문자열과 대조됩니다. 또한 이스케이프된 문자는 표현식이 적용되기 전에 이스케이프가 해제됩니다.

      '+'를 선택 패턴으로 사용하여 응답을 필터링하는 경우 줄바꿈('\n') 문자를 포함하는 응답과 일치하지 않을 수 있다는 점에 유의하세요.

    3. 활성화되어 있는 경우 메서드 응답 페이지에서 정의한 HTTP 응답 상태 코드를 메서드 응답 상태에서 선택합니다.

    4. 메서드 응답 페이지에서 HTTP 응답 상태 코드에 대해 정의한 각 헤더에 대해 헤더 매핑에서 매핑 값을 지정합니다. Mapping value(매핑 값)에는 다음 형식 중 하나를 사용합니다.

      • integration.response.multivalueheaders.header-name 여기에서 header-name은 백엔드로부터 받은 다중 값 응답 헤더의 이름입니다.

        예를 들어, 백엔드 응답의 Date 헤더를 API 메서드의 응답의 Timestamp 헤더로 반환하기 위해 Response header(응답 헤더) 열은 Timestamp 입력을 포함하게 되며 연결된 Mapping value(매핑 값)integration.response.multivalueheaders.Date로 설정되어야 합니다.

      • integration.response.header.header-name 여기에서 header-name은 백엔드로부터 받은 단일 값 응답 헤더의 이름입니다.

        예를 들어, 백엔드 응답의 Date 헤더를 API 메서드의 응답의 Timestamp 헤더로 반환하기 위해 Response header(응답 헤더) 열은 Timestamp 입력을 포함하게 되며 연결된 Mapping value(매핑 값)integration.response.header.Date로 설정되어야 합니다.

    5. 매핑 템플릿을 선택한 다음 매핑 템플릿 추가를 선택합니다. 콘텐츠 유형 상자에서 Lambda 함수, HTTP 프록시 또는 AWS 서비스 프록시로부터 메서드로 전달될 데이터의 콘텐츠 유형을 입력합니다. 그런 다음 매핑 템플릿을 입력합니다. 자세한 내용은 REST API용 매핑 템플릿 단원을 참조하십시오.

    6. Save(저장)를 선택합니다.