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](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html) 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](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html) dans le *guide de l'utilisateur de la CloudFormation CLI* et dans le [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/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](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization) 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](sam-specification-generated-resources.md).
## Syntaxe
Pour déclarer cette entité dans votre modèle AWS Serverless Application Model (AWS SAM), utilisez la syntaxe suivante.
### YAML
```
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}}
```
## 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](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html#apigateway-websocket-api-apikey-selection-expressions) 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-apikeyselectionexpression)` propriété d'une `AWS::ApiGatewayV2::Api` ressource.
`AccessLogSettings`
Les paramètres pour la journalisation des accès dans une étape.
*Type :* [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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'`$connect`itinéraire.
Pour plus d'informations, consultez la section [Contrôle de l'accès à WebSocket APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-control-access.html) dans le *guide du développeur d'API Gateway*.
*Type :* [WebSocketApiAuth](sam-property-websocketapi-websocketapiauth.md)
*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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[DefaultRouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableschemavalidation)` propriété d'une `AWS::ApiGatewayV2::Api` ressource.
`Domain`
Configure un domaine personnalisé pour cette WebSocket API.
WebSocket APIs ne prennent pas en charge l'authentification TLS mutuelle (MTLS). Si vous spécifiez `MutualTlsAuthentication` ou`OwnershipVerificationCertificateArn`, une erreur AWS SAM sera renvoyée.
*Type :* [WebSocketApiDomainConfiguration](sam-property-websocketapi-websocketapidomainconfiguration.md)
*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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-name)` propriété d'une `AWS::ApiGatewayV2::Api` ressource.
`PropagateTags`
Si`true`, 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](sam-property-websocketapi-routeconfiguration.md)
*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](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html#apigateway-websocket-api-route-selection-expressions) 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[StageVariables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html) 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
```