백엔드 통합 간접 호출: $default 라우팅 및 사용자 지정 라우팅

라우팅을 사용하여 메시지 처리

API Gateway WebSocket API에서는 클라이언트에서 백엔드 서비스로, 또는 그 반대로 메시지를 보낼 수 있습니다. HTTP의 요청/응답 모델과 달리 WebSocket에서는 클라이언트의 조치 없이도 백엔드에서 클라이언트로 메시지를 보낼 수 있습니다.

메시지는 JSON 또는 비 JSON일 수 있습니다. 그러나 JSON 메시지만 메시지 내용을 기반으로 특정 통합에 라우팅될 수 있습니다. 비 JSON 메시지는 $default 라우팅을 통해 백엔드로 전달됩니다.

참고

API Gateway는 최대 128KB의 메시지 페이로드를 지원하며 최대 프레임 크기는 32KB입니다. 메시지가 32KB를 초과하면 32KB 이하의 여러 프레임으로 분할해야 합니다. 큰 메시지(또는 프레임)가 수신되면 코드 1009와 함께 연결이 해제됩니다.

현재 이진 페이로드는 지원되지 않습니다. 이진 프레임이 수신되면 코드 1003과 함께 연결이 해제됩니다. 그러나 이진 페이로드를 텍스트로 변환할 수 있습니다. API Gateway의 WebSocket API에 대한 이진 미디어 유형를 참조하세요.

API Gateway의 WebSocket API를 사용하면 JSON 메시지를 라우팅하여 메시지 내용을 기반으로 특정 백엔드 서비스를 실행할 수 있습니다. 클라이언트가 WebSocket 연결을 통해 메시지를 보내면 WebSocket API에 대한 라우팅 요청이 이루어집니다. 요청은 API Gateway에서 해당 라우팅 키가 있는 라우팅과 매치됩니다. API Gateway 콘솔에서 AWS CLI를 사용하거나 AWS SDK를 사용하여 WebSocket API에 대한 경로 요청을 설정할 수 있습니다.

참고

AWS CLI, AWS SDK에서 통합을 생성하기 이전 또는 이후에 라우팅을 생성할 수 있습니다. 현재 콘솔은 통합의 재사용을 지원하지 않으므로 먼저 라우팅을 생성한 다음 해당 라우팅에 대한 통합을 생성해야 합니다.

통합 요청을 진행하기 전에 라우팅 요청의 확인을 수행하도록 API Gateway를 구성할 수 있습니다. 유효성 검사에 실패하면 API Gateway는 백엔드를 호출하지 않고 요청에 실패하고, 다음과 비슷한 "Bad request body" 게이트웨이 응답을 클라이언트에 전송하고, 유효성 검사 결과를 CloudWatch Logs에 게시합니다.

{"message" : "Bad request body", "connectionId": "{connectionId}", "messageId": "{messageId}"}

그러면 백엔드에 대한 불필요한 호출이 줄고 API의 다른 요구 사항에 집중할 수 있습니다.

양방향 통신을 활성화하기 위해 API의 라우팅에 대한 라우팅 응답을 정의할 수도 있습니다. 라우팅 응답은 특정 라우팅의 통합이 완료되면 클라이언트에 전송할 데이터를 설명합니다. 예를 들어 클라이언트가 응답을 받지 않고 백엔드로 메시지를 보내도록 하려면(단방향 통신)에는 라우팅에 대한 응답을 정의할 필요가 없습니다. 그러나 라우팅 응답을 제공하지 않으면 API Gateway는 통합 결과에 대한 정보를 클라이언트에 보내지 않습니다.

$default 라우팅

모든 API Gateway WebSocket API에는 $default 라우팅이 있을 수 있습니다. 이것은 다음과 같이 사용할 수 있는 특별한 라우팅 값입니다.

• 정의된 라우팅 키와 함께 사용할 경우, 정의된 라우팅 키와 일치하지 않는 수신 메시지에 대해 "대체" 라우팅(예: 특정 오류 메시지를 반환하는 일반 모의 통합)을 지정할 수 있습니다.

• 정의된 라우팅 키 없이 백엔드 구성 요소에 라우팅을 위임하는 프록시 모델을 지정하기 위해 사용할 수 있습니다.

• 비 JSON 페이로드에 대한 라우팅을 지정하는 데 사용할 수 있습니다.

사용자 지정 라우팅

메시지 내용을 기반으로 특정 통합을 호출하려는 경우 사용자 지정 라우팅을 생성하면 됩니다.

사용자 지정 라우팅은 사용자가 지정하는 라우팅 키와 통합을 사용합니다. 수신 메시지에 JSON 속성이 포함되어 있고 해당 속성이 라우팅 키 값과 일치하는 값으로 평가되면 API Gateway가 통합을 호출합니다. (자세한 내용은 API Gateway의 WebSocket API 개요 섹션을 참조하세요.)

예를 들어 대화방 애플리케이션을 만들고 싶다고 가정해 보겠습니다. 라우팅 선택 표현식이 $request.body.action인 WebSocket API를 생성하는 것으로 시작할 수 있습니다. 그런 다음 joinroom, sendmessage 등 두 가지 라우팅을 정의합니다. 클라이언트 앱은 다음과 같은 메시지를 보내어 joinroom 라우팅을 호출할 수 있습니다.

{"action":"joinroom","roomname":"developers"}

그리고 다음과 같은 메시지를 보내어 sendmessage 라우팅을 호출할 수 있습니다.

{"action":"sendmessage","message":"Hello everyone"}

API Gateway WebSocket API 통합을 사용하여 비즈니스 로직에 연결

API Gateway WebSocket API에 대한 라우팅을 설정한 후에는 사용할 통합을 지정해야 합니다. 라우팅이 라우팅 요청과 라우팅 응답으로 구성될 수 있는 것과 마찬가지로, 통합은 통합 요청과 통합 응답으로 구성될 수 있습니다. 통합 요청에는 클라이언트에서 제공한 요청을 처리하기 위해 백엔드가 기대한 정보가 들어 있습니다. 통합 응답에는 백엔드가 API Gateway로 반환하는 데이터가 포함되어 있으며, 이는 클라이언트에 보낼 메시지를 구성하는 데 사용할 수 있습니다(라우팅 응답이 정의된 경우).

통합 설정에 대한 자세한 내용은 API Gateway의 WebSocket API 통합 단원을 참조하십시오.

WebSocket API와 REST API의 중요한 차이점

WebSocket API의 통합은 REST API의 통합과 유사하지만 다음과 같은 차이가 있습니다.

• 현재 API Gateway 콘솔에서는 먼저 라우팅을 생성한 다음, 해당 라우팅의 대상으로 통합을 생성해야 합니다. 그러나 API와 CLI에서는 순서와 상관없이 라우팅과 통합을 독립적으로 생성할 수 있습니다.

• 여러 라우팅에 하나의 통합을 사용할 수 있습니다. 예를 들어 서로 밀접한 관련이 있는 작업 집합의 경우, 하나의 Lambda 함수로 이동하도록 이러한 모든 라우팅을 설정하고 싶을 수 있습니다. 통합의 세부 사항을 여러 번 정의하는 대신, 한 번만 지정한 후 관련 라우팅에 각각 할당할 수 있습니다.

  참고

  현재 콘솔은 통합의 재사용을 지원하지 않으므로 먼저 라우팅을 생성한 다음 해당 라우팅에 대한 통합을 생성해야 합니다.

  AWS CLI, AWS SDK에서 라우팅의 대상을 "integrations/{integration-id}" 값으로 설정하면 통합을 재사용할 수 있습니다. 여기서 {integration-id}"는 이 라우팅과 연결될 통합의 고유 ID입니다.

• API Gateway는 라우팅 및 통합에 사용할 수 있는 여러 선택 표현식을 제공합니다. 콘텐츠 형식에 의존해 입력 템플릿 또는 출력 매핑을 선택할 필요가 없습니다. 라우팅 선택 표현식과 마찬가지로, 올바른 항목을 선택하기 위해 API Gateway에서 평가할 선택 표현식을 정의할 수 있습니다. 일치하는 템플릿이 없으면 모든 템플릿이 $default 템플릿으로 대체됩니다.

  • 통합 요청에서 템플릿 선택 표현식은 $request.body.<json_path_expression> 및 정적 값을 지원합니다.

  • 통합 응답에서 템플릿 선택 표현식은 $request.body.<json_path_expression>, $integration.response.statuscode, $integration.response.header.<headerName> 및 정적 값을 지원합니다.

요청과 응답이 동기식으로 전송되는 HTTP 프로토콜에서 통신은 기본적으로 단방향입니다. WebSocket 프로토콜에서 통신은 양방향입니다. 응답은 비동기식이며, 클라이언트의 메시지가 전송된 순서와 동일한 순서로 클라이언트가 수신하지는 않습니다. 또한 백엔드에서 클라이언트로 메시지를 보낼 수 있습니다.

참고

AWS_PROXY 또는 LAMBDA_PROXY 통합을 사용하도록 구성된 라우팅의 경우, 통신은 단방향이고 API Gateway는 백엔드 응답을 라우팅 응답에 자동으로 전달하지 않습니다. 예를 들어 LAMBDA_PROXY 통합의 경우 Lambda 함수가 반환하는 본문은 클라이언트에 반환되지 않습니다. 클라이언트가 통합 응답을 수신하도록 하려면 양방향 통신을 가능하게 할 라우팅 응답을 정의해야 합니다.