AWS::Serverless::WebSocketApi

양방향 대화형 통신 애플리케이션을 생성할 수 있는 Amazon API Gateway WebSocket API를 생성합니다. WebSocket APIs 사용하면 클라이언트가 메시지를 요청할 필요 없이 서버가 클라이언트에 메시지를 보낼 수 있습니다. 자세한 내용은 APIs의 WebSocket API 작업을 참조하세요.

CloudFormation 후크 또는 IAM 정책을 사용하여 API Gateway 리소스에 대한 액세스를 제어하는 권한 부여자가 연결되어 있는지 확인하는 것이 좋습니다.

CloudFormation 후크 사용에 대한 자세한 내용은 CloudFormation CLI 사용 설명서의 후크 등록 및 apigw-enforce-authorizer GitHub 리포지토리를 참조하세요.

IAM 정책 사용에 대한 자세한 내용은 API 게이트웨이 개발자 가이드의 API 경로에 권한 부여 필요를 참조하세요.

참고

에 배포하면가 AWS SAM 리소스를 CloudFormation 리소스로 AWS CloudFormation AWS SAM 변환합니다. 자세한 내용은 에 대해 생성된 CloudFormation 리소스 AWS SAM 단원을 참조하십시오.

구문

AWS Serverless Application Model (AWS SAM) 템플릿에서이 개체를 선언하려면 다음 구문을 사용합니다.

YAML


Type: AWS::Serverless::WebSocketApi
Properties:
  ApiKeySelectionExpression: String
  AccessLogSettings: AccessLogSettings
  Auth: WebSocketApiAuth
  DefaultRouteSettings: RouteSettings
  Description: String
  DisableExecuteApiEndpoint: Boolean
  DisableSchemaValidation: Boolean
  Domain: WebSocketApiDomainConfiguration
  IpAddressType: String
  Name: String
  PropagateTags: Boolean
  Routes: RouteConfiguration
  RouteSelectionExpression: String
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

속성

ApiKeySelectionExpression

API 키 선택 표현식입니다. 자세한 내용은 API Gateway 개발자 안내서의 API 키 선택 표현식을 참조하세요.

유형: 문자열

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은 AWS::ApiGatewayV2::Api 리소스의 ApiKeySelectionExpression 속성으로 직접 전달됩니다.

AccessLogSettings

단계의 로깅 액세스에 대한 설정입니다.

유형: AccessLogSettings

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은 AWS::ApiGatewayV2::Stage 리소스의 AccessLogSettings 속성으로 직접 전달됩니다.

Auth

WebSocket API에 대한 액세스를 제어하기 위한 권한 부여를 구성합니다. 권한 부여는 $connect 경로에 적용됩니다.

자세한 내용은 APIs의 WebSocket API에 대한 액세스 제어를 참조하세요.

유형: WebSocketApiAuth

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.

DefaultRouteSettings

이 WebSocket API의 기본 라우팅 설정입니다. 이 설정은 특정 경로에 대해 RouteSettings 속성에서 재정의하지 않는 한 모든 경로에 적용됩니다.

유형: RouteSettings

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은 AWS::ApiGatewayV2::Stage 리소스의 DefaultRouteSettings 속성으로 직접 전달됩니다.

Description

WebSocket API에 대한 설명입니다.

유형: 문자열

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은 AWS::ApiGatewayV2::Api 리소스의 Description 속성으로 직접 전달됩니다.

DisableExecuteApiEndpoint

클라이언트가 기본 execute-api 엔드포인트를 사용하여 API를 간접 호출할 수 있는지를 지정합니다. 클라이언트가 사용자 지정 도메인 이름을 사용하여 API를 호출하도록 요구하려면 기본 엔드포인트를 비활성화합니다.

유형: 부울

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은 AWS::ApiGatewayV2::Api 리소스의 DisableExecuteApiEndpoint 속성으로 직접 전달됩니다.

DisableSchemaValidation

배포를 생성할 때 모델을 검증하지 마십시오.

유형: 부울

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은 AWS::ApiGatewayV2::Api 리소스의 DisableSchemaValidation 속성으로 직접 전달됩니다.

Domain

이 WebSocket API에 대한 사용자 지정 도메인을 구성합니다.

참고

WebSocket APIs 상호 TLS 인증(MTLS)을 지원하지 않습니다. MutualTlsAuthentication 또는를 지정하면 OwnershipVerificationCertificateArn AWS SAM 가 오류를 반환합니다.

유형: WebSocketApiDomainConfiguration

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.

IpAddressType

API의 IP 주소 유형입니다. 유효한 값은 ipv4 IPv4 전용 및 IPv4 및 IPv6dualstack용입니다.

유형: 문자열

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은 AWS::ApiGatewayV2::Api 리소스의 IpAddressType 속성으로 직접 전달됩니다.

Name

WebSocket API의 이름입니다. 이름을 지정하지 않으면가 사용자를 대신하여 이름을 AWS SAM 생성합니다.

유형: 문자열

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은 AWS::ApiGatewayV2::Api 리소스의 Name 속성으로 직접 전달됩니다.

PropagateTags

true인 경우,가 AWS SAM 생성하는 AWS::ApiGatewayV2::Stage 및 AWS::ApiGatewayV2::DomainName 리소스에 Tags 속성을 AWS SAM 추가합니다.

유형: 부울

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.

Routes

이 WebSocket API의 라우팅 구성입니다. 라우팅은 메시지가 Lambda 함수로 라우팅되는 방법을 정의합니다. 각 라우팅은 라우팅 키와 Lambda 함수 ARN으로 구성됩니다.

WebSocket APIs $connect, 및 $disconnect의 세 가지 사전 정의된 경로를 지원합니다$default. 사용자 지정 경로를 정의할 수도 있습니다.

유형: RouteConfiguration

필수 항목 여부: 예

CloudFormation 호환성:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.

RouteSelectionExpression

WebSocket API의 라우팅 선택 표현식입니다. 자세한 내용은 API Gateway 개발자 안내서의 경로 선택 표현식을 참조하세요.

공통 값은 메시지 본문의 action 필드를 기반으로 메시지를 라우팅$request.body.action하는 입니다.

유형: 문자열

필수 항목 여부: 예

CloudFormation 호환성:이 속성은 AWS::ApiGatewayV2::Api 리소스의 RouteSelectionExpression 속성으로 직접 전달됩니다.

RouteSettings

이 WebSocket API의 라우팅 설정입니다. 이러한 설정은 특정 경로에 DefaultRouteSettings 대해를 재정의합니다.

유형: RouteSettings

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은 AWS::ApiGatewayV2::Stage 리소스의 RouteSettings 속성으로 직접 전달됩니다.

StageName

API 단계의 이름. 이름을 지정하지 않으면를 default 스테이지 이름으로 AWS SAM 사용합니다.

유형: 문자열

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은 AWS::ApiGatewayV2::Stage 리소스의 StageName 속성으로 직접 전달됩니다.

StageVariables

단계 변수를 정의하는 맵입니다. 변수 이름에는 영숫자와 밑줄 문자가 있을 수 있으며 값은와 일치해야 합니다[A-Za-z0-9-._~:/?#&=,]+.

유형: Json

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은 AWS::ApiGatewayV2::Stage 리소스의 StageVariables 속성으로 직접 전달됩니다.

Tags

이 WebSocket API에 추가할 태그를 지정하는 맵(문자열 간). 태그의 유효한 키와 값에 대한 자세한 내용은 사용자 가이드의 CloudFormation 리소스 태그를 참조하세요.

유형: 맵

필수 항목 여부: 아니요

CloudFormation 호환성:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다.

예제

Simple WebSocket API

다음 예제에서는 세 가지 경로로 WebSocket API를 생성합니다.


Resources:
  MyWebSocketApi:
    Type: AWS::Serverless::WebSocketApi
    Properties:
      RouteSelectionExpression: $request.body.action
      Routes:
        $connect:
          FunctionArn: !GetAtt ConnectFunction.Arn
        $disconnect:
          FunctionArn: !GetAtt DisconnectFunction.Arn
        sendMessage:
          FunctionArn: !GetAtt SendMessageFunction.Arn

  ConnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.connect
      Runtime: nodejs20.x
      CodeUri: ./src

  DisconnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.disconnect
      Runtime: nodejs20.x
      CodeUri: ./src

  SendMessageFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.sendMessage
      Runtime: nodejs20.x
      CodeUri: ./src

Lambda 권한 부여자를 사용하는 WebSocket API

다음 예제에서는 Lambda 권한 부여자를 사용하여 WebSocket API를 생성합니다.


Resources:
  MyWebSocketApi:
    Type: AWS::Serverless::WebSocketApi
    Properties:
      RouteSelectionExpression: $request.body.action
      Auth:
        AuthType: CUSTOM
        AuthArn: !GetAtt AuthorizerFunction.Arn
        IdentitySource:
          - route.request.header.Authorization
      Routes:
        $connect:
          FunctionArn: !GetAtt ConnectFunction.Arn
        sendMessage:
          FunctionArn: !GetAtt SendMessageFunction.Arn

  AuthorizerFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.authorize
      Runtime: nodejs20.x
      CodeUri: ./src

  ConnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.connect
      Runtime: nodejs20.x
      CodeUri: ./src

  SendMessageFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.sendMessage
      Runtime: nodejs20.x
      CodeUri: ./src

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

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

문서 규칙

Route53Configuration

WebSocketApiAuth