View a markdown version of this page

AWS::Serverless::WebSocketApi - AWS Serverless Application Model
SyntaxePropriétésExemples

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

AWS::Serverless::WebSocketApi

Crée une API Amazon WebSocket API Gateway, qui vous permet de créer des applications de communication interactives bidirectionnelles. WebSocket APIs autoriser le serveur à envoyer des messages aux clients sans que le client n'ait à les demander. Pour plus d'informations, consultez la section Travailler avec WebSocket APIs dans le guide du développeur d'API Gateway.

Nous vous recommandons d'utiliser CloudFormation des hooks ou des politiques IAM pour vérifier que les ressources API Gateway sont associées à des autorisateurs afin de contrôler l'accès à celles-ci.

Pour plus d'informations sur l'utilisation CloudFormation des hooks, consultez la section Enregistrement des hooks dans le guide de l'utilisateur de la CloudFormation CLI et dans le apigw-enforce-authorizer GitHub référentiel.

Pour plus d'informations sur l'utilisation de politiques IAM, veuillez consulter Exiger que les routes d'API disposent d'une autorisation dans le Guide du développeur API Gateway.

Note

Lorsque vous déployez vers AWS CloudFormation, vos AWS SAM ressources sont AWS SAM transformées en CloudFormation ressources. Pour de plus amples informations, veuillez consulter CloudFormation Ressources générées pour AWS SAM.

Syntaxe

Pour déclarer cette entité dans votre modèle AWS Serverless Application Model (AWS SAM), utilisez la syntaxe suivante.

Propriétés

ApiKeySelectionExpression

Expressions de sélection de la clé d'API Pour plus d'informations, consultez la section Expressions de sélection des clés d'API dans le guide du développeur d'API Gateway.

Type : chaîne

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la ApiKeySelectionExpression propriété d'une AWS::ApiGatewayV2::Api ressource.

AccessLogSettings

Les paramètres pour la journalisation des accès dans une étape.

Type : AccessLogSettings

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la AccessLogSettings propriété d'une AWS::ApiGatewayV2::Stage ressource.

Auth

Configure l'autorisation pour contrôler l'accès à votre WebSocket API. L'autorisation est appliquée à l'$connectitinéraire.

Pour plus d'informations, consultez la section Contrôle de l'accès à WebSocket APIs dans le guide du développeur d'API Gateway.

Type : WebSocketApiAuth

Obligatoire : non

CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.

DefaultRouteSettings

Les paramètres de route par défaut pour cette WebSocket API. Ces paramètres s'appliquent à tous les acheminements sauf s'ils sont remplacés par le paramètre RouteSettings pour certains acheminements.

Type : RouteSettings

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la DefaultRouteSettings propriété d'une AWS::ApiGatewayV2::Stage ressource.

Description

Description de l' WebSocket API.

Type : chaîne

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la Description propriété d'une AWS::ApiGatewayV2::Api ressource.

DisableExecuteApiEndpoint

Spécifie si les clients peuvent appeler votre API à l’aide du point de terminaison execute-api par défaut. Pour exiger que les clients utilisent un nom de domaine personnalisé pour appeler votre API, désactivez le point de terminaison par défaut.

Type : valeur booléenne

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la DisableExecuteApiEndpoint propriété d'une AWS::ApiGatewayV2::Api ressource.

DisableSchemaValidation

Évite les modèles de validation lors de la création d'un déploiement.

Type : valeur booléenne

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la DisableSchemaValidation propriété d'une AWS::ApiGatewayV2::Api ressource.

Domain

Configure un domaine personnalisé pour cette WebSocket API.

Note

WebSocket APIs ne prennent pas en charge l'authentification TLS mutuelle (MTLS). Si vous spécifiez MutualTlsAuthentication ouOwnershipVerificationCertificateArn, une erreur AWS SAM sera renvoyée.

Type : WebSocketApiDomainConfiguration

Obligatoire : non

CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.

IpAddressType

Type d'adresse IP de l'API. Les valeurs valides sont ipv4 pour IPv4 uniquement et dualstack pour IPv4 et IPv6.

Type : chaîne

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la IpAddressType propriété d'une AWS::ApiGatewayV2::Api ressource.

Name

Nom de l' WebSocket API. Si vous ne spécifiez pas de nom, il en AWS SAM génère un pour vous.

Type : chaîne

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la Name propriété d'une AWS::ApiGatewayV2::Api ressource.

PropagateTags

Sitrue, AWS SAM ajoute la Tags propriété aux AWS::ApiGatewayV2::DomainName ressources AWS::ApiGatewayV2::Stage et AWS SAM générées.

Type : valeur booléenne

Obligatoire : non

CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.

Routes

Les configurations de route pour cette WebSocket API. Les routes définissent la manière dont les messages sont acheminés vers les fonctions Lambda. Chaque route est composée d'une clé de route et d'un ARN de fonction Lambda.

WebSocket APIs prennent en charge trois itinéraires prédéfinis : $connect$disconnect, et$default. Vous pouvez également définir des itinéraires personnalisés.

Type : RouteConfiguration

Obligatoire : oui

CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.

RouteSelectionExpression

Expression de sélection d'itinéraire pour l' WebSocket API. Pour plus d'informations, consultez la section Expressions de sélection d'itinéraires dans le guide du développeur d'API Gateway.

Une valeur courante est$request.body.action, qui achemine les messages en fonction d'un action champ dans le corps du message.

Type : chaîne

Obligatoire : oui

CloudFormation compatibilité : cette propriété est transmise directement à la RouteSelectionExpression propriété d'une AWS::ApiGatewayV2::Api ressource.

RouteSettings

Les paramètres de route pour cette WebSocket API. Ces paramètres remplacent ceux définis DefaultRouteSettings pour des itinéraires spécifiques.

Type : RouteSettings

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la RouteSettings propriété d'une AWS::ApiGatewayV2::Stage ressource.

StageName

Le nom de l'étape d'API. Si vous ne spécifiez pas de nom, AWS SAM default utilisez-le comme nom de scène.

Type : chaîne

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la StageName propriété d'une AWS::ApiGatewayV2::Stage ressource.

StageVariables

Mappage qui définit les variables de l'étape. Les noms de variables peuvent comporter des caractères alphanumériques et des traits de soulignement, et les valeurs doivent correspondre. [A-Za-z0-9-._~:/?#&=,]+

Type : Json

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la StageVariables propriété d'une AWS::ApiGatewayV2::Stage ressource.

Tags

Une carte (chaîne à chaîne) qui spécifie les balises à ajouter à cette WebSocket API. Pour plus de détails sur les clés et les valeurs valides pour les étiquettes, voir l'étiquette Ressource dans le Guide de l'utilisateur CloudFormation .

Type: carte (map)

Obligatoire : non

CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.

Exemples

WebSocket API simple

L'exemple suivant crée une WebSocket API avec trois itinéraires.

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 avec Lambda Authorizer

L'exemple suivant crée une WebSocket API avec un autorisateur Lambda.

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