AWS::Serverless::WebSocketApi

创建 Amazon API Gateway WebSocket API，使您能够创建双向交互式通信应用程序。 WebSocket APIs 允许服务器向客户端发送消息，而无需客户端请求消息。有关更多信息，请参阅 API Gateway 开发者指南 WebSocket APIs中的使用。

我们建议您使用 CloudFormation 挂钩或 IAM 策略来验证 API Gateway 资源是否附加了授权者来控制对它们的访问。

有关使用 CloudFormation 挂钩的更多信息，请参阅 CloudFormation CLI 用户指南和apigw-enforce-authorizer GitHub 存储库中的注册挂钩。

有关使用 IAM 策略的更多信息，请参阅《API Gateway 开发人员指南》中的要求 API 路由具有授权。

注意

部署到时 AWS CloudFormation， AWS SAM 会将您的 AWS SAM 资源转换为 CloudFormation 资源。有关更多信息，请参阅 生成的 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

Properties

ApiKeySelectionExpression

一个 API 键选择表达式。有关更多信息，请参阅 API Gate way 开发者指南中的 API 密钥选择表达式。

类型：字符串

必需：否

CloudFormation 兼容性：此属性直接传递给AWS::ApiGatewayV2::Api资源的ApiKeySelectionExpression属性。

AccessLogSettings

某个阶段的访问日志记录的设置。

类型：AccessLogSettings

必需：否

CloudFormation 兼容性：此属性直接传递给AWS::ApiGatewayV2::Stage资源的AccessLogSettings属性。

Auth

配置授权，以控制对您的 WebSocket API 的访问权限。授权已应用于$connect路径。

有关更多信息，请参阅《API Gateway 开发者指南》 WebSocket APIs中的控制访问权限。

类型：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 仅ipv4dualstack适用于 IPv4 和 IPv6。

类型：字符串

必需：否

CloudFormation 兼容性：此属性直接传递给AWS::ApiGatewayV2::Api资源的IpAddressType属性。

Name

WebSocket API 的名称。如果您未指定名称，则会为您 AWS SAM 生成一个名称。

类型：字符串

必需：否

CloudFormation 兼容性：此属性直接传递给AWS::ApiGatewayV2::Api资源的Name属性。

PropagateTags

如果true，则 AWS SAM 将该Tags属性添加到 AWS SAM 生成的AWS::ApiGatewayV2::Stage和AWS::ApiGatewayV2::DomainName资源中。

类型：布尔值

必需：否

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 开发者指南中的路由选择表达式。

一个常见的值是$request.body.action，它根据消息正文中的action字段路由消息。

类型：字符串

是否必需：是

CloudFormation 兼容性：此属性直接传递给AWS::ApiGatewayV2::Api资源的RouteSelectionExpression属性。

RouteSettings

此 WebSocket API 的路由设置。这些设置会覆盖DefaultRouteSettings特定路径的。

类型：RouteSettings

必需：否

CloudFormation 兼容性：此属性直接传递给AWS::ApiGatewayV2::Stage资源的RouteSettings属性。

StageName

API 阶段的名称。如果未指定名称，则 AWS SAM 使用default作为舞台名称。

类型：字符串

必需：否

CloudFormation 兼容性：此属性直接传递给AWS::ApiGatewayV2::Stage资源的StageName属性。

StageVariables

一个定义阶段变量的映射。变量名可以包含字母数字和下划线字符，并且值必须匹配[A-Za-z0-9-._~:/?#&=,]+。

类型：Json

必需：否

CloudFormation 兼容性：此属性直接传递给AWS::ApiGatewayV2::Stage资源的StageVariables属性。

Tags

用于指定要添加到此 WebSocket API 的标签的映射（字符串到字符串）。有关标签的有效键和值的详细信息，请参阅《CloudFormation 用户指南》中的资源标签。

类型：映射

必需：否

CloudFormation 兼容性：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。

示例

简单的 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

WebSocket 带有 Lambda 授权器的 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