AWS::Serverless::WebSocketApi

Erstellt eine Amazon API Gateway WebSocket Gateway-API, mit der Sie interaktive bidirektionale Kommunikationsanwendungen erstellen können. WebSocket APIs ermöglicht es dem Server, Nachrichten an Clients zu senden, ohne dass der Client sie anfordern muss. Weitere Informationen finden Sie unter Arbeiten mit WebSocket APIs im API Gateway Developer Guide.

Wir empfehlen, CloudFormation Hooks oder IAM-Richtlinien zu verwenden, um zu überprüfen, ob an API-Gateway-Ressourcen Autorisatoren angehängt sind, um den Zugriff darauf zu kontrollieren.

Weitere Informationen zur Verwendung von CloudFormation Hooks finden Sie unter Hooks registrieren im CloudFormation CLI-Benutzerhandbuch und im apigw-enforce-authorizer GitHub Repository.

Weitere Informationen zur Verwendung von IAM-Richtlinien finden Sie unter Erfordern, dass API-Routen autorisiert sind im API Gateway Developer Guide.

Anmerkung

Bei der Bereitstellung auf werden AWS CloudFormation Ihre AWS SAM Ressourcen in Ressourcen umgewandelt CloudFormation . AWS SAM Weitere Informationen finden Sie unter Generierte CloudFormation Ressourcen für AWS SAM.

Syntax

Verwenden Sie die folgende Syntax, um diese Entität in Ihrer Vorlage AWS Serverless Application Model (AWS SAM) zu deklarieren.

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

Eigenschaften

ApiKeySelectionExpression

Ein API-Schlüssel-Auswahlausdruck. Weitere Informationen finden Sie unter API-Schlüsselauswahlausdrücke im API Gateway Developer Guide.

Typ: Zeichenfolge

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die ApiKeySelectionExpression Eigenschaft einer AWS::ApiGatewayV2::Api Ressource übergeben.

AccessLogSettings

Die Einstellungen für die Zugriffsprotokollierung in einer Phase.

Typ: AccessLogSettings

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die AccessLogSettings Eigenschaft einer AWS::ApiGatewayV2::Stage Ressource übergeben.

Auth

Konfiguriert die Autorisierung zur Steuerung des Zugriffs auf Ihre WebSocket API. Die Autorisierung wird auf die $connect Route angewendet.

Weitere Informationen finden Sie unter Steuern des Zugriffs auf WebSocket APIs im API Gateway Developer Guide.

Typ: WebSocketApiAuth

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.

DefaultRouteSettings

Die Standardrouteneinstellungen für diese WebSocket API. Diese Einstellungen gelten für alle Routen, sofern sie nicht durch die RouteSettings Eigenschaft für bestimmte Routen außer Kraft gesetzt werden.

Typ: RouteSettings

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die DefaultRouteSettings Eigenschaft einer AWS::ApiGatewayV2::Stage Ressource übergeben.

Description

Eine Beschreibung der WebSocket API.

Typ: Zeichenfolge

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die Description Eigenschaft einer AWS::ApiGatewayV2::Api Ressource übergeben.

DisableExecuteApiEndpoint

Gibt an, ob Clients Ihre API mithilfe des execute-api-Standardendpunkts aufrufen können. Deaktivieren Sie den Standardendpunkt, um bei Clients die Verwendung eines benutzerdefinierten Domänennamen zum Aufrufen Ihrer API erforderlich zu machen.

Typ: Boolesch

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die DisableExecuteApiEndpoint Eigenschaft einer AWS::ApiGatewayV2::Api Ressource übergeben.

DisableSchemaValidation

Vermeiden Sie die Validierung von Modellen, wenn Sie eine Bereitstellung erstellen.

Typ: Boolesch

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die DisableSchemaValidation Eigenschaft einer AWS::ApiGatewayV2::Api Ressource übergeben.

Domain

Konfiguriert eine benutzerdefinierte Domain für diese WebSocket API.

Anmerkung

WebSocket APIs unterstützen keine gegenseitige TLS-Authentifizierung (MTLS). Wenn Sie MutualTlsAuthentication oder angebenOwnershipVerificationCertificateArn, AWS SAM wird ein Fehler zurückgegeben.

Typ: WebSocketApiDomainConfiguration

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.

IpAddressType

Der IP-Adresstyp für die API. Gültige Werte sind IPv4 nur ipv4 für und dualstack für IPv4 und IPv6.

Typ: Zeichenfolge

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die IpAddressType Eigenschaft einer AWS::ApiGatewayV2::Api Ressource übergeben.

Name

Ein Name für die WebSocket API. Wenn Sie keinen Namen angeben, AWS SAM generiert es einen Namen für Sie.

Typ: Zeichenfolge

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die Name Eigenschaft einer AWS::ApiGatewayV2::Api Ressource übergeben.

PropagateTags

Wenntrue, AWS SAM fügt die Tags Eigenschaft zu den AWS::ApiGatewayV2::DomainName Ressourcen AWS::ApiGatewayV2::Stage hinzu, die AWS SAM generiert werden.

Typ: Boolesch

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.

Routes

Die Routenkonfigurationen für diese WebSocket API. Routen definieren, wie Nachrichten an Lambda-Funktionen weitergeleitet werden. Jede Route besteht aus einem Routenschlüssel und einem Lambda-Funktions-ARN.

WebSocket APIs unterstützt drei vordefinierte Routen: $connect$disconnect, und$default. Sie können auch benutzerdefinierte Routen definieren.

Typ: RouteConfiguration

Erforderlich: Ja

CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.

RouteSelectionExpression

Der Routenauswahlausdruck für die WebSocket API. Weitere Informationen finden Sie unter Route Selection Expressions im API Gateway Developer Guide.

Ein gängiger Wert ist$request.body.action, der Nachrichten auf der Grundlage eines action Felds im Nachrichtentext weiterleitet.

Typ: Zeichenfolge

Erforderlich: Ja

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die RouteSelectionExpression Eigenschaft einer AWS::ApiGatewayV2::Api Ressource übergeben.

RouteSettings

Die Routeneinstellungen für diese WebSocket API. Diese Einstellungen überschreiben die DefaultRouteSettings für bestimmte Routen.

Typ: RouteSettings

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die RouteSettings Eigenschaft einer AWS::ApiGatewayV2::Stage Ressource übergeben.

StageName

Der Name der API-Stufe. Wenn Sie keinen Namen angeben, AWS SAM wird er default als Phasennamen verwendet.

Typ: Zeichenfolge

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die StageName Eigenschaft einer AWS::ApiGatewayV2::Stage Ressource übergeben.

StageVariables

Eine Zuweisung, welche die Stufenvariablen definiert. Variablennamen können alphanumerische Zeichen und Unterstriche enthalten, und die Werte müssen übereinstimmen. [A-Za-z0-9-._~:/?#&=,]+

Type: Json

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft wird direkt an die StageVariables Eigenschaft einer AWS::ApiGatewayV2::Stage Ressource übergeben.

Tags

Eine Zuordnung (Zeichenfolge zu Zeichenfolge), die die Tags spezifiziert, die zu dieser WebSocket API hinzugefügt werden sollen. Einzelheiten zu gültigen Schlüsseln und Werten für Tags finden Sie unter Resource-Tag im CloudFormation Benutzerhandbuch.

Typ: Karte

Required: No

CloudFormation Kompatibilität: Diese Eigenschaft ist einzigartig AWS SAM und hat kein CloudFormation Äquivalent.

Beispiele

Einfache WebSocket API

Das folgende Beispiel erstellt eine WebSocket API mit drei Routen.

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 API mit Lambda Authorizer

Das folgende Beispiel erstellt eine WebSocket API mit einem Lambda-Authorizer.

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