기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # AWS::Serverless::WebSocketApi 양방향 대화형 통신 애플리케이션을 생성할 수 있는 Amazon API Gateway WebSocket API를 생성합니다. WebSocket APIs 사용하면 클라이언트가 메시지를 요청할 필요 없이 서버가 클라이언트에 메시지를 보낼 수 있습니다. 자세한 내용은 [ APIs의 WebSocket API 작업을 참조하세요](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html). ** CloudFormation 후크 또는 IAM 정책을 사용하여 API Gateway 리소스에 대한 액세스를 제어하는 권한 부여자가 연결되어 있는지 확인하는 것이 좋습니다. CloudFormation 후크 사용에 대한 자세한 내용은 *CloudFormation CLI 사용 설명서*의 [후크 등록](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html) 및 [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub 리포지토리를 참조하세요. IAM 정책 사용에 대한 자세한 내용은 [API 게이트웨이 개발자 가이드의](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization) *API 경로에 권한 부여 필요를* 참조하세요. **참고** 에 배포하면가 AWS SAM 리소스를 CloudFormation 리소스로 AWS CloudFormation AWS SAM 변환합니다. 자세한 내용은 [에 대해 생성된 CloudFormation 리소스 AWS SAM](sam-specification-generated-resources.md) 단원을 참조하십시오. ## 구문 AWS Serverless Application Model (AWS SAM) 템플릿에서이 개체를 선언하려면 다음 구문을 사용합니다. ### YAML ``` Type: AWS::Serverless::WebSocketApi Properties: [ApiKeySelectionExpression](#sam-websocketapi-apikeyselectionexpression): {{String}} [AccessLogSettings](#sam-websocketapi-accesslogsettings): {{[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)}} [Auth](#sam-websocketapi-auth): {{WebSocketApiAuth}} [DefaultRouteSettings](#sam-websocketapi-defaultroutesettings): {{[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)}} [Description](#sam-websocketapi-description): {{String}} [DisableExecuteApiEndpoint](#sam-websocketapi-disableexecuteapiendpoint): {{Boolean}} [DisableSchemaValidation](#sam-websocketapi-disableschemavalidation): {{Boolean}} [Domain](#sam-websocketapi-domain): {{WebSocketApiDomainConfiguration}} [IpAddressType](#sam-websocketapi-ipaddresstype): {{String}} [Name](#sam-websocketapi-name): {{String}} [PropagateTags](#sam-websocketapi-propagatetags): {{Boolean}} [Routes](#sam-websocketapi-routes): {{RouteConfiguration}} [RouteSelectionExpression](#sam-websocketapi-routeselectionexpression): {{String}} [RouteSettings](#sam-websocketapi-routesettings): {{[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)}} [StageName](#sam-websocketapi-stagename): {{String}} [StageVariables](#sam-websocketapi-stagevariables): {{[Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)}} [Tags](#sam-websocketapi-tags): {{Map}} ``` ## 속성 `ApiKeySelectionExpression` API 키 선택 표현식입니다. 자세한 내용은 [API Gateway 개발자 안내서의 API 키 선택 표현식을](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html#apigateway-websocket-api-apikey-selection-expressions) 참조하세요. ** *유형*: 문자열 *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은 `AWS::ApiGatewayV2::Api` 리소스의 `[ApiKeySelectionExpression](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-apikeyselectionexpression)` 속성으로 직접 전달됩니다. `AccessLogSettings` 단계의 로깅 액세스에 대한 설정입니다. *유형*: [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings) *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은 `AWS::ApiGatewayV2::Stage` 리소스의 `[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)` 속성으로 직접 전달됩니다. `Auth` WebSocket API에 대한 액세스를 제어하기 위한 권한 부여를 구성합니다. 권한 부여는 `$connect` 경로에 적용됩니다. 자세한 내용은 [ APIs의 WebSocket API에 대한 액세스 제어를 참조하세요](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-control-access.html). ** *유형*: [WebSocketApiAuth](sam-property-websocketapi-websocketapiauth.md) *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다. `DefaultRouteSettings` 이 WebSocket API의 기본 라우팅 설정입니다. 이 설정은 특정 경로에 대해 `RouteSettings` 속성에서 재정의하지 않는 한 모든 경로에 적용됩니다. *유형*: [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings) *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은 `AWS::ApiGatewayV2::Stage` 리소스의 `[DefaultRouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-defaultroutesettings)` 속성으로 직접 전달됩니다. `Description` WebSocket API에 대한 설명입니다. *유형*: 문자열 *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은 `AWS::ApiGatewayV2::Api` 리소스의 `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-description)` 속성으로 직접 전달됩니다. `DisableExecuteApiEndpoint` 클라이언트가 기본 `execute-api` 엔드포인트를 사용하여 API를 간접 호출할 수 있는지를 지정합니다. 클라이언트가 사용자 지정 도메인 이름을 사용하여 API를 호출하도록 요구하려면 기본 엔드포인트를 비활성화합니다. *유형*: 부울 *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은 `AWS::ApiGatewayV2::Api` 리소스의 `[DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableexecuteapiendpoint)` 속성으로 직접 전달됩니다. `DisableSchemaValidation` 배포를 생성할 때 모델을 검증하지 마십시오. *유형*: 부울 *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은 `AWS::ApiGatewayV2::Api` 리소스의 `[DisableSchemaValidation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableschemavalidation)` 속성으로 직접 전달됩니다. `Domain` 이 WebSocket API에 대한 사용자 지정 도메인을 구성합니다. WebSocket APIs 상호 TLS 인증(MTLS)을 지원하지 않습니다. `MutualTlsAuthentication` 또는를 지정하면 `OwnershipVerificationCertificateArn` AWS SAM 가 오류를 반환합니다. *유형*: [WebSocketApiDomainConfiguration](sam-property-websocketapi-websocketapidomainconfiguration.md) *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다. `IpAddressType` API의 IP 주소 유형입니다. 유효한 값은 `ipv4` IPv4 전용 및 IPv4 및 IPv6`dualstack`용입니다. *유형*: 문자열 *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은 `AWS::ApiGatewayV2::Api` 리소스의 `[IpAddressType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-ipaddresstype)` 속성으로 직접 전달됩니다. `Name` WebSocket API의 이름입니다. 이름을 지정하지 않으면가 사용자를 대신하여 이름을 AWS SAM 생성합니다. *유형*: 문자열 *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은 `AWS::ApiGatewayV2::Api` 리소스의 `[Name](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-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](sam-property-websocketapi-routeconfiguration.md) *필수 항목 여부:* 예 *CloudFormation 호환성*:이 속성은에 고유 AWS SAM 하며 CloudFormation 동등한 속성이 없습니다. `RouteSelectionExpression` WebSocket API의 라우팅 선택 표현식입니다. 자세한 내용은 *API Gateway 개발자 안내서*의 [경로 선택 표현식을](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html#apigateway-websocket-api-route-selection-expressions) 참조하세요. 공통 값은 메시지 본문의 `action` 필드를 기반으로 메시지를 라우팅`$request.body.action`하는 입니다. *유형*: 문자열 *필수 항목 여부:* 예 *CloudFormation 호환성*:이 속성은 `AWS::ApiGatewayV2::Api` 리소스의 `[RouteSelectionExpression](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-routeselectionexpression)` 속성으로 직접 전달됩니다. `RouteSettings` 이 WebSocket API의 라우팅 설정입니다. 이러한 설정은 특정 경로에 `DefaultRouteSettings` 대해를 재정의합니다. *유형*: [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings) *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은 `AWS::ApiGatewayV2::Stage` 리소스의 `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)` 속성으로 직접 전달됩니다. `StageName` API 단계의 이름. 이름을 지정하지 않으면를 `default` 스테이지 이름으로 AWS SAM 사용합니다. *유형*: 문자열 *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은 `AWS::ApiGatewayV2::Stage` 리소스의 `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagename)` 속성으로 직접 전달됩니다. `StageVariables` 단계 변수를 정의하는 맵입니다. 변수 이름에는 영숫자와 밑줄 문자가 있을 수 있으며 값은와 일치해야 합니다`[A-Za-z0-9-._~:/?#&=,]+`. *유형*: [Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables) *필수 항목 여부*: 아니요 *CloudFormation 호환성*:이 속성은 `AWS::ApiGatewayV2::Stage` 리소스의 `[StageVariables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)` 속성으로 직접 전달됩니다. `Tags` 이 WebSocket API에 추가할 태그를 지정하는 맵(문자열 간). 태그의 유효한 키와 값에 대한 자세한 내용은 [ 사용자 가이드](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html)의 *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 ```