WebSocket API에 대한 라우팅 작업

WebSocket API에서 수신되는 JSON 메시지는 사용자가 구성한 라우팅을 기반으로 백엔드 통합으로 전달됩니다. (비 JSON 메시지는 사용자가 구성한 $default 라우팅으로 전달됩니다.)

라우팅에는 라우팅 선택 표현식을 평가할 경우 예상되는 값인 라우팅 키가 포함되어 있습니다. routeSelectionExpression은 API 수준에서 정의되는 속성입니다. 메시지 페이로드에 존재할 것으로 예상되는 JSON 속성을 지정합니다. 라우팅 선택 표현식에 대한 자세한 내용은 라우팅 선택 표현식 단원을 참조하십시오.

예를 들어 JSON 메시지에 action 속성이 있고 이 속성을 기반으로 다른 작업을 수행하려는 경우, 라우팅 선택 표현식은 ${request.body.action}일 수 있습니다. 라우팅 테이블은 사용자가 테이블에 정의한 사용자 지정 라우팅 키 값에 따라 action 속성 값을 일치시켜 어떤 작업을 수행할 것인지 지정할 것입니다.

$connect, $disconnect, $default 등 세 가지 사전 정의된 라우팅을 사용할 수 있습니다. 또한 사용자 지정 라우팅을 생성할 수 있습니다.

API Gateway는 클라이언트와 WebSocket API 간 지속적인 연결이 시작될 때 $connect 라우팅을 호출합니다.
API Gateway는 클라이언트 또는 서버가 API와의 연결을 끊을 때 $disconnect 라우팅을 호출합니다.
일치하는 라우팅이 발견되면 메시지를 기준으로 라우팅 선택 표현식이 평가된 후 API Gateway가 사용자 지정 라우팅을 호출합니다. 일치 여부에 따라 어떤 통합이 호출될지 결정됩니다.
일치하는 라우팅이 없거나 메시지를 기준으로 라우팅 선택 표현식을 평가할 수 없는 경우 API Gateway가 $default 라우팅을 호출합니다.

라우팅 선택 표현식

서비스가 수신 메시지에 대해 따라야 할 라우팅을 선택할 때 라우팅 선택 표현식이 평가됩니다. 서비스는 routeKey가 평가된 값과 정확하게 일치하는 라우팅을 사용합니다. 일치하는 값이 없고 라우팅 키가 $default인 라우팅이 존재하는 경우, 그 값이 선택됩니다. 평가된 값과 일치하는 라우팅이 없고 $default 라우팅이 없는 경우 서비스는 오류를 반환합니다. WebSocket 기반 API의 경우 표현식은 $request.body.{path_to_body_element} 형식이어야 합니다.

예를 들어 다음과 같은 JSON 메시지를 보낸다고 가정하겠습니다.


{
    "service" : "chat",
    "action" : "join",
    "data" : {
        "room" : "room1234"
   }
}

action 속성을 기반으로 API의 동작을 선택할 수 있습니다. 이 경우 다음 라우팅 선택 표현식을 정의할 수 있습니다.


$request.body.action

이 예에서 request.body는 메시지의 JSON 페이로드를 나타내며 .action은 JSONPath 표현식입니다. request.body 뒤에 모든 JSON 경로 표현식을 사용할 수 있지만 결과는 문자열로 변환됩니다. 예를 들어, JSONPath 표현식이 두 요소의 배열을 반환하면 "[item1, item2]" 문자열로 표시됩니다. 따라서 표현식을 배열이나 객체가 아닌 값으로 평가하는 것이 좋습니다.

단순히 정적 값을 사용하거나 여러 변수를 사용할 수 있습니다. 다음 표는 이전의 페이로드에 대한 예제와 평가된 결과를 보여줍니다.

표현식	평가된 결과	설명
`$request.body.action`	`join`	언래핑된 변수
`${request.body.action}`	`join`	래핑된 변수
`${request.body.service}/${request.body.action}`	`chat`/`join`	정적 값이 있는 여러 변수
`${request.body.action}-${request.body.invalidPath}`	`join-`	JSONPath를 찾지 못하면 변수는 ""로 해석됩니다.
`action`	`action`	정적 값
`\$default`	`$default`	정적 값

평가된 결과는 라우팅을 찾는 데 사용됩니다. 일치하는 라우팅 키를 가진 라우팅이 있는 경우, 해당 라우팅이 선택되어 메시지를 처리합니다. 일치하는 라우팅이 없으면 API Gateway가 사용 가능한 $default 라우팅을 찾습니다. $default 라우팅이 정의되지 않은 경우, API Gateway는 오류를 반환합니다.

API Gateway에서 WebSocket API에 대한 라우팅 설정

처음 새 WebSocket API를 생성할 때 $connect, $disconnect, $default 등 세 가지 사전 정의된 라우팅이 있습니다. 콘솔, API 또는 AWS CLI를 사용하여 생성할 수 있습니다. 필요에 따라 사용자 지정 라우팅을 생성할 수 있습니다. 자세한 내용은 API Gateway의 WebSocket API 소개 단원을 참조하세요.

참고

CLI에서는 통합을 생성하기 이전 또는 이후에 라우팅을 생성할 수 있으며 여러 라우팅에 대해 동일한 통합을 재사용할 수 있습니다.

API Gateway 콘솔을 사용하여 라우팅 생성

API Gateway 콘솔을 사용하여 라우팅을 생성하려면

API Gateway 콘솔에 로그인하고 API를 선택한 다음 라우팅을 선택하세요.
경로 생성을 선택합니다.
라우팅 키에 라우팅 키 이름을 입력합니다. 사전 정의된 경로($connect, $disconnect 및 $default) 또는 사용자 지정 경로를 생성할 수 있습니다.

참고
사용자 지정 라우팅을 생성할 때 라우팅 키 이름에 $ 접두사를 사용하지 마십시오. 이 접두사는 미리 정의된 라우팅에 예약되어 있습니다.
경로의 통합 유형을 선택하고 구성합니다. 자세한 내용은 API Gateway 콘솔을 사용하여 WebSocket API 통합 요청을 설정 단원을 참조하십시오.

AWS CLI를 사용하여 라우팅 생성

AWS CLI를 사용하여 라우팅을 생성하려면 다음 예와 같이 create-route를 호출합니다.


aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default

출력 예:


{
    "ApiKeyRequired": false,
    "AuthorizationType": "NONE",
    "RouteKey": "$default",
    "RouteId": "1122334"
}

`$connect`에 대한 라우팅 요청 설정 지정

API에 대해 $connect 라우팅을 설정하면 다음 선택적 설정을 사용하여 API에 대한 권한 부여를 활성화할 수 있습니다. 자세한 내용은 $connect 라우팅 단원을 참조하세요.

권한 부여: 권한 부여가 필요하지 않으면 NONE을 지정할 수 있습니다. 또는 다음을 지정할 수 있습니다.
- AWS_IAM: 표준 AWS IAM 정책을 사용하여 API에 대한 액세스를 제어합니다.
- CUSTOM: 이전에 생성한 Lambda 권한 부여자 함수를 지정하여 API에 대한 권한 부여를 구현합니다. 권한 부여자는 자신의 AWS 계정이나 다른 AWS 계정에 상주할 수 있습니다. Lambda 권한 부여자에 대한 자세한 내용은 API Gateway Lambda 권한 부여자 사용 단원을 참조하세요.
  
  참고
  API Gateway 콘솔에서 CUSTOM 설정은 Lambda 권한 부여자 구성(콘솔)에서 설명한 대로 권한 부여자 함수를 설정한 후에만 볼 수 있습니다.
중요
권한 부여 설정은 $connect 라우팅뿐만 아니라 전체 API에 적용됩니다. $connect 라우팅은 모든 연결에서 호출되기 때문에 다른 라우팅을 보호합니다.
API Key Required(API 키 필요): 선택적으로, API의 $connect 라우팅에 대한 API 키가 필요할 수 있습니다. API 키와 사용량 계획을 함께 사용하여 API 액세스를 제어하고 추적할 수 있습니다. 자세한 내용은 API 키를 사용하여 사용량 계획 생성 및 사용 단원을 참조하세요.

API Gateway 콘솔을 사용하여 `$connect` 라우팅 요청 설정

API Gateway 콘솔을 사용하여 WebSocket API에 대한 $connect 라우팅 요청을 설정하려면 다음을 수행하세요.

API Gateway 콘솔에 로그인하고 API를 선택한 다음 라우팅을 선택하세요.
경로에서 API Gateway 콘솔을 사용하여 라우팅 생성을 따라 $connect를 선택하거나 $connect 경로를 생성합니다.
경로 요청 설정 섹션에서 편집을 선택합니다.
권한 부여에서 권한 부여 유형을 선택합니다.
$connect 경로용 API를 요구하려면 API 키 필요를 선택합니다.
Save changes(변경 사항 저장)를 선택합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

생성 및 구성

WebSocket API 라우팅 응답 설정