Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

# AWS::Serverless::WebSocketApi
<a name="sam-resource-websocketapi"></a>

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](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html) 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](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html) im *CloudFormation CLI-Benutzerhandbuch* und im [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub Repository.

Weitere Informationen zur Verwendung von IAM-Richtlinien finden Sie unter [Erfordern, dass API-Routen autorisiert sind](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization) 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](sam-specification-generated-resources.md).

## Syntax
<a name="sam-resource-websocketapi-syntax"></a>

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

### YAML
<a name="sam-resource-websocketapi-syntax.yaml"></a>

```
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}}
```

## Eigenschaften
<a name="sam-resource-websocketapi-properties"></a>

 `ApiKeySelectionExpression`   <a name="sam-websocketapi-apikeyselectionexpression"></a>
Ein API-Schlüssel-Auswahlausdruck. Weitere Informationen finden Sie unter [API-Schlüsselauswahlausdrücke](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html#apigateway-websocket-api-apikey-selection-expressions) im *API Gateway Developer Guide*.  
*Typ:* Zeichenfolge  
*Required*: No  
*CloudFormation Kompatibilität*: Diese Eigenschaft wird direkt an die `[ApiKeySelectionExpression](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-apikeyselectionexpression)` Eigenschaft einer `AWS::ApiGatewayV2::Api` Ressource übergeben.

 `AccessLogSettings`   <a name="sam-websocketapi-accesslogsettings"></a>
Die Einstellungen für die Zugriffsprotokollierung in einer Phase.  
*Typ:* [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)  
*Required*: No  
*CloudFormation Kompatibilität*: Diese Eigenschaft wird direkt an die `[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)` Eigenschaft einer `AWS::ApiGatewayV2::Stage` Ressource übergeben.

 `Auth`   <a name="sam-websocketapi-auth"></a>
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](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-control-access.html) im *API Gateway Developer Guide*.  
*Typ:* [WebSocketApiAuth](sam-property-websocketapi-websocketapiauth.md)  
*Required*: No  
*CloudFormation Kompatibilität*: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.

 `DefaultRouteSettings`   <a name="sam-websocketapi-defaultroutesettings"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)  
*Required*: No  
*CloudFormation Kompatibilität*: Diese Eigenschaft wird direkt an die `[DefaultRouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-defaultroutesettings)` Eigenschaft einer `AWS::ApiGatewayV2::Stage` Ressource übergeben.

 `Description`   <a name="sam-websocketapi-description"></a>
Eine Beschreibung der WebSocket API.  
*Typ:* Zeichenfolge  
*Required*: No  
*CloudFormation Kompatibilität*: Diese Eigenschaft wird direkt an die `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-description)` Eigenschaft einer `AWS::ApiGatewayV2::Api` Ressource übergeben.

 `DisableExecuteApiEndpoint`   <a name="sam-websocketapi-disableexecuteapiendpoint"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableexecuteapiendpoint)` Eigenschaft einer `AWS::ApiGatewayV2::Api` Ressource übergeben.

 `DisableSchemaValidation`   <a name="sam-websocketapi-disableschemavalidation"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableschemavalidation)` Eigenschaft einer `AWS::ApiGatewayV2::Api` Ressource übergeben.

 `Domain`   <a name="sam-websocketapi-domain"></a>
Konfiguriert eine benutzerdefinierte Domain für diese WebSocket API.  
WebSocket APIs unterstützen keine gegenseitige TLS-Authentifizierung (MTLS). Wenn Sie `MutualTlsAuthentication` oder angeben`OwnershipVerificationCertificateArn`, AWS SAM wird ein Fehler zurückgegeben.
*Typ:* [WebSocketApiDomainConfiguration](sam-property-websocketapi-websocketapidomainconfiguration.md)  
*Required*: No  
*CloudFormation Kompatibilität*: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.

 `IpAddressType`   <a name="sam-websocketapi-ipaddresstype"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-ipaddresstype)` Eigenschaft einer `AWS::ApiGatewayV2::Api` Ressource übergeben.

 `Name`   <a name="sam-websocketapi-name"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-name)` Eigenschaft einer `AWS::ApiGatewayV2::Api` Ressource übergeben.

 `PropagateTags`   <a name="sam-websocketapi-propagatetags"></a>
Wenn`true`, 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`   <a name="sam-websocketapi-routes"></a>
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](sam-property-websocketapi-routeconfiguration.md)  
*Erforderlich*: Ja  
*CloudFormation Kompatibilität*: Diese Eigenschaft ist einzigartig für AWS SAM und hat kein CloudFormation Äquivalent.

 `RouteSelectionExpression`   <a name="sam-websocketapi-routeselectionexpression"></a>
Der Routenauswahlausdruck für die WebSocket API. Weitere Informationen finden Sie unter [Route Selection Expressions](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html#apigateway-websocket-api-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-routeselectionexpression)` Eigenschaft einer `AWS::ApiGatewayV2::Api` Ressource übergeben.

 `RouteSettings`   <a name="sam-websocketapi-routesettings"></a>
Die Routeneinstellungen für diese WebSocket API. Diese Einstellungen überschreiben die `DefaultRouteSettings` für bestimmte Routen.  
*Typ:* [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)  
*Required*: No  
*CloudFormation Kompatibilität*: Diese Eigenschaft wird direkt an die `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)` Eigenschaft einer `AWS::ApiGatewayV2::Stage` Ressource übergeben.

 `StageName`   <a name="sam-websocketapi-stagename"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagename)` Eigenschaft einer `AWS::ApiGatewayV2::Stage` Ressource übergeben.

 `StageVariables`   <a name="sam-websocketapi-stagevariables"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)  
*Required*: No  
*CloudFormation Kompatibilität*: Diese Eigenschaft wird direkt an die `[StageVariables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)` Eigenschaft einer `AWS::ApiGatewayV2::Stage` Ressource übergeben.

 `Tags`   <a name="sam-websocketapi-tags"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html) im *CloudFormation Benutzerhandbuch*.  
*Typ*: Karte  
*Required*: No  
*CloudFormation Kompatibilität*: Diese Eigenschaft ist einzigartig AWS SAM und hat kein CloudFormation Äquivalent.

## Beispiele
<a name="sam-resource-websocketapi-examples"></a>

### Einfache WebSocket API
<a name="sam-resource-websocketapi-examples-simple"></a>

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
<a name="sam-resource-websocketapi-examples-auth"></a>

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
```