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 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 Gateway 開發人員指南》中的 API 金鑰選擇表達式。

類型：字串

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::ApiGatewayV2::Api 資源的 ApiKeySelectionExpression 屬性。

AccessLogSettings

階段中存取記錄的設定。

類型：AccessLogSettings

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::ApiGatewayV2::Stage 資源的 AccessLogSettings 屬性。

Auth

設定控制 WebSocket API 存取的授權。授權會套用至$connect路由。

如需詳細資訊，請參閱《 API Gateway 開發人員指南》中的控制對 WebSocket API 的存取 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 IPv4，dualstack適用於 IPv4 和 IPv6。

類型：字串

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::ApiGatewayV2::Api 資源的 IpAddressType 屬性。

Name

WebSocket API 的名稱。如果您未指定名稱，會為您 AWS SAM 產生名稱。

類型：字串

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::ApiGatewayV2::Api 資源的 Name 屬性。

PropagateTags

如果為 true，則會將 Tags 屬性 AWS SAM 新增至 AWS SAM 產生的 AWS::ApiGatewayV2::DomainName AWS::ApiGatewayV2::Stage和資源。

類型：布林值

必要：否

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

具有 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。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

Route53Configuration

WebSocketApiAuth