` et les valeurs statiques.
Dans le protocole HTTP, dans lequel les demandes et les réponses sont envoyées de manière synchrone, la communication est essentiellement unidirectionnelle. Dans le WebSocket protocole, la communication est bidirectionnelle. Les réponses sont asynchrones et ne sont pas nécessairement reçues par le client dans l’ordre où les messages du client ont été envoyés. De plus, le serveur principal peut envoyer des messages au client.
**Note**
Pour une route qui est configurée pour utiliser l’intégration `AWS_PROXY` ou `LAMBDA_PROXY`, la communication est unidirectionnelle et API Gateway ne transmet pas automatiquement la réponse du backend par le biais de la réponse de routage. Par exemple, dans le cas de l’intégration `LAMBDA_PROXY`, le corps de message renvoyé par la fonction Lambda n’est pas renvoyé au client. Si vous voulez que le client reçoive les réponses de l’intégration, vous devez définir une réponse de routage pour permettre la communication bidirectionnelle.
# WebSocket expressions de sélection
API Gateway utilise des expressions de sélection pour évaluer le contexte de demande et de réponse, et générer une clé. La clé est ensuite utilisée pour effectuer une sélection parmi un ensemble de valeurs possibles, généralement fournies par vous, en tant que développeur de l’API. L’ensemble exact des variables prises en charge varie en fonction de l’expression en question. Les différentes expressions sont présentées plus en détail ci-après.
Pour toutes les expressions, le langage suit le même ensemble de règles :
+ Une variable est précédée du préfixe `"$"`.
+ Des accolades peuvent être utilisées pour définir explicitement les limites des variables (par exemple., `"${request.body.version}-beta"`.
+ Plusieurs variables sont prises en charge, mais l’évaluation n’intervient qu’une seule fois (pas d’évaluation récursive).
+ L’échappement du symbole du dollar (`$`) est effectué avec `"\"`. C’est particulièrement utile lorsque vous définissez une expression qui est mappée à la clé `$default` réservée (par exemple, `"\$default"`).
+ Dans certains cas, un format de modèle est requis. Dans ce cas, l’expression doit être encapsulée avec des barres obliques (`"/"`) (par exemple, `"/2\d\d/"`) pour correspondre aux codes de statut `2XX`.
**Topics**
+ [Expressions de sélection de la réponse de routage](#apigateway-websocket-api-route-response-selection-expressions)
+ [Expressions de sélection de la clé d’API](#apigateway-websocket-api-apikey-selection-expressions)
+ [Expressions de sélection du mappage d’API](#apigateway-websocket-api-mapping-selection-expressions)
+ [WebSocket résumé de l'expression de sélection](#apigateway-websocket-api-selection-expression-table)
## Expressions de sélection de la réponse de routage
Une [réponse de routage](apigateway-websocket-api-route-response.md) est utilisée pour modéliser une réponse du serveur principal au client. En effet WebSocket APIs, une réponse d'itinéraire est facultative. Une fois défini, il indique à API Gateway qu'il doit renvoyer une réponse à un client à la réception d'un WebSocket message.
L’évaluation de l’*expression de sélection de la réponse de routage* génère une clé de réponse de routage. Au final, cette clé est utilisée pour choisir l’un des éléments [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html) associés à l’API. Cependant, à l’heure actuelle, seule la clé `$default` est prise en charge.
## Expressions de sélection de la clé d’API
Cette expression est évaluée lorsque le service détermine que la demande en question doit continuer uniquement si le client fournit une [clé d’API](api-gateway-basic-concept.md#apigateway-definition-api-key).
À l’heure actuelle, les seules deux valeurs prises en charge sont `$request.header.x-api-key` et `$context.authorizer.usageIdentifierKey`.
## Expressions de sélection du mappage d’API
Cette expression est évaluée pour déterminer quelle étape d’API est sélectionnée lorsqu’une demande est effectuée à l’aide d’un domaine personnalisé.
À l'heure actuelle, la seule valeur prise en charge est `$request.basepath`.
## WebSocket résumé de l'expression de sélection
Le tableau suivant récapitule les cas d'utilisation des expressions de sélection dans WebSocket APIs :
| Expression de sélection | Correspond à la clé pour | Remarques | Exemple de cas d’utilisation |
| --- | --- | --- | --- |
| Api.RouteSelectionExpression | Route.RouteKey | \$1default est pris en charge en tant que route fourre-tout. | WebSocket Acheminez les messages en fonction du contexte d'une demande du client. |
| Route.ModelSelectionExpression | Clé pour Route.RequestModels | Facultatif. Si elle est fournie pour une intégration autre que de proxy, la validation du modèle a lieu. `$default` est pris en charge en tant que fourre-tout. | Effectuer une validation de demande de manière dynamique au sein de la même route. |
| Integration.TemplateSelectionExpression | Clé pour Integration.RequestTemplates | Facultatif. Peut être fournie pour une intégration autre que de proxy pour manipuler des charges utiles entrantes. `${request.body.jsonPath}` et les valeurs statiques sont prises en charge. `$default` est pris en charge en tant que fourre-tout. | Manipuler la demande de l’appelant en fonction des propriétés dynamiques de la demande. |
| Integration.IntegrationResponseSelectionExpression | IntegrationResponse.IntegrationResponseKey | Facultatif. Peut être fournie pour une intégration autre que de proxy. Agit en tant que modèle de correspondance pour des messages d’erreur (à partir de Lambda) ou des codes d’état (à partir d’intégrations HTTP). `$default` est obligatoire pour des intégrations autres que de proxy pour agir en tant que fourre-tout pour les réponses fructueuses. | Manipuler la réponse du serveur principal. Choisir l’action à exécuter en fonction de la réponse dynamique du serveur principal (par exemple, traitement distinctif de certaines erreurs). |
| IntegrationResponse.TemplateSelectionExpression | Clé pour IntegrationResponse.ResponseTemplates | Facultatif. Peut être fournie pour une intégration autre que de proxy. \$1default est pris en charge. | Dans certains cas, une propriété dynamique de la réponse peut imposer différentes transformations au sein de la même route et de l’intégration associée. `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}`, et les valeurs statiques sont prises en charge. `$default` est pris en charge en tant que fourre-tout. |
| Route.RouteResponseSelectionExpression | RouteResponse.RouteResponseKey | Doit être fourni pour initier une communication bidirectionnelle pour un WebSocket itinéraire. À l’heure actuelle, cette valeur est limitée à `$default` uniquement. | |
| RouteResponse.ModelSelectionExpression | Clé pour RouteResponse.RequestModels | Non prise en charge actuellement. | |
# Développez WebSocket APIs dans API Gateway
Cette section fournit des détails sur les fonctionnalités d'API Gateway dont vous avez besoin pour développer votre API Gateway APIs.
Au fur et à mesure que vous développez votre API API Gateway, vous décidez d’un certain nombre de caractéristiques de votre API. Ces caractéristiques dépendent du cas d’utilisation de votre API. Par exemple, vous pourriez vouloir autoriser uniquement certains clients à appeler votre API ou qu’elle soit disponible pour tout le monde. Vous pouvez souhaiter utiliser un appel d’API pour exécuter une fonction Lambda, créer une requête de base de données ou appeler une application.
**Topics**
+ [Création WebSocket APIs dans API Gateway](apigateway-websocket-api-create-empty-api.md)
+ [Types d’adresses IP pour les API WebSocket dans API Gateway](websocket-api-ip-address-type.md)
+ [Création de routes pour WebSocket APIs in API Gateway](websocket-api-develop-routes.md)
+ [Contrôler et gérer l'accès WebSocket APIs à API Gateway](apigateway-websocket-api-control-access.md)
+ [Intégrations pour WebSocket APIs in API Gateway](apigateway-websocket-api-integrations.md)
+ [Demande de validation pour WebSocket APIs in API Gateway](websocket-api-request-validation.md)
+ [Transformations de données pour WebSocket APIs dans API Gateway](websocket-api-data-transformations.md)
+ [Types de supports binaires pour les API WebSocket dans API Gateway](websocket-api-develop-binary-media-types.md)
+ [Invoquer WebSocket APIs](apigateway-how-to-call-websocket-api.md)
# Création WebSocket APIs dans API Gateway
Vous pouvez créer une WebSocket API dans la console API Gateway, à l'aide de la commande AWS CLI [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) ou à l'aide de la `CreateApi` commande d'un AWS SDK. Les procédures suivantes montrent comment créer une nouvelle WebSocket API.
**Note**
WebSocket APIs ne supporte que TLS 1.2 et TLS 1.3. Les versions antérieures de TLS ne sont pas prises en charge.
## Création d'une WebSocket API à l'aide de AWS CLI commandes
La commande [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) suivante crée une API avec l’expression de sélection de route `$request.body.action` :
```
aws apigatewayv2 --region us-east-1 create-api --name "myWebSocketApi3" --protocol-type WEBSOCKET --route-selection-expression '$request.body.action'
```
Le résultat se présente comme suit :
```
{
"ApiKeySelectionExpression": "$request.header.x-api-key",
"Name": "myWebSocketApi3",
"CreatedDate": "2018-11-15T06:23:51Z",
"ProtocolType": "WEBSOCKET",
"RouteSelectionExpression": "'$request.body.action'",
"ApiId": "aabbccddee"
}
```
## Création d'une WebSocket API à l'aide de la console API Gateway
Vous pouvez créer une WebSocket API dans la console en choisissant le WebSocket protocole et en lui attribuant un nom.
**Important**
Une fois l’API créée, vous ne pouvez pas modifier le protocole que vous avez choisi. Il n'existe aucun moyen de convertir une WebSocket API en API REST ou vice versa.
**Pour créer une WebSocket API à l'aide de la console API Gateway**
1. Connectez-vous à la console API Gateway et choisissez **Create API (Créer une API)**.
1. Sous **WebSocket API**, choisissez **Build**. Seuls les points de terminaison régionaux sont pris en charge.
1. Pour **Nom de l’API**, saisissez le nom de votre API.
1. Pour **Expression de sélection de routage**, saisissez une valeur. Par exemple, `$request.body.action`.
Pour plus d’informations sur les expressions de sélection de la route, consultez la section [Expressions de sélection de la route](websocket-api-develop-routes.md#apigateway-websocket-api-route-selection-expressions).
1. Effectuez l’une des actions suivantes :
+ Choisissez **Créer une API vide** pour créer une API sans routes.
+ Choisissez **Suivant** pour joindre des routes à votre API.
Vous pouvez joindre des routes après avoir créé votre API.
# Types d’adresses IP pour les API WebSocket dans API Gateway
Lorsque vous créez une API, vous spécifiez le type d’adresses IP qui peut invoquer votre API. Vous avez le choix entre IPv4 (pour autoriser les adresses IPv4 à invoquer votre API) et Dualstack (pour autoriser les adresses IPv4 et IPv6 à invoquer votre API). Nous vous recommandons de définir le type d’adresse IP sur Dualstack pour éviter l’épuisement de l’espace IP ou renforcer votre niveau de sécurité. Pour plus d’informations sur les avantages d’un type d’adresse IP à double pile, consultez [IPv6 sur AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Considérations relatives aux types d’adresses IP
Les considérations suivantes peuvent avoir une incidence sur votre utilisation des types d’adresses IP :
+ Le type d’adresses IP par défaut pour toutes les API WebSocket est IPv4.
+ Si vous remplacez le type d’adresse IP IPv4 d’une API existante par un type d’adresse IP à double pile, vérifiez que toutes les stratégies d’accès à vos API ont été mises à jour pour prendre en compte les appels IPv6. La modification du type d’adresse IP prend effet immédiatement.
+ Votre API peut être mappée à un nom de domaine personnalisé présentant un type d’adresse IP différent de celui de votre API. La désactivation du point de terminaison de votre API par défaut peut avoir une incidence sur la manière dont les appelants peuvent invoquer votre API.
## Modification du type d’adresse IP d’une API WebSocket
Vous pouvez modifier le type d’adresse IP en mettant à jour la configuration de l’API. Vous pouvez mettre à jour la configuration de l’API à l’aide de la AWS Management Console, de l’AWS CLI, d’CloudFormation ou d’un kit SDK AWS. Si vous modifiez le type d’adresse IP de l’API, vous n’avez pas besoin de redéployer votre API pour que les modifications prennent effet.
------
#### [ AWS Management Console ]
**Pour modifier le type d’adresse IP d’une API WebSocket**
1. Connectez-vous à la console API Gateway à l’adresse : [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choisissez une API WebSocket.
1. Choisissez **Paramètres de l’API**, puis **Modifier**.
1. Pour Type d’adresse IP, choisissez **IPv4** ou **Dualstack**.
1. Choisissez **Save (Enregistrer)**.
La modification de la configuration de votre API prend effet immédiatement.
------
#### [ AWS CLI ]
La commande [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) suivante met à jour une API pour qu’elle possède le type d’adresse IP Dualstack :
```
aws apigatewayv2 update-api \
--api-id abcd1234 \
--ip-address-type dualstack
```
Le résultat se présente comme suit :
```
{
"ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com",
"ApiId": "abcd1234",
"ApiKeySelectionExpression": "$request.header.x-api-key",
"CreatedDate": "2025-02-04T22:20:20+00:00",
"DisableExecuteApiEndpoint": false,
"Name": "My-WebSocket-API",
"ProtocolType": "WEBSOCKET",
"RouteSelectionExpression": "$request.method $request.path",
"Tags": {},
"NotificationUris": [],
"IpAddressType": "dualstack"
}
```
------
# Création de routes pour WebSocket APIs in API Gateway
Dans votre WebSocket API, les messages JSON entrants sont dirigés vers les intégrations du backend en fonction des routes que vous configurez. (Les messages non JSON sont dirigés vers une route `$default` que vous configurez.)
Une *route* comprend une *clé de routage*, qui correspond à la valeur attendue une fois qu’une *expression de sélection de la route* est évaluée. L’attribut `routeSelectionExpression` est défini au niveau de l’API. Il spécifie une propriété JSON attendue dans la charge utile du message. Pour plus d’informations sur les expressions de sélection de la route, consultez la section [Expressions de sélection de la route](#apigateway-websocket-api-route-selection-expressions).
Par exemple, si vos messages JSON contiennent une propriété `action` et que vous souhaitez effectuer différentes actions en fonction de cette propriété, votre expression de sélection de la route peut être `${request.body.action}`. Votre table de routage spécifie l'action à exécuter en mettant en correspondance la valeur de la propriété `action` avec les valeurs des clés de routage personnalisées que vous avez définies dans la table.
Trois routes prédéfinies peuvent être utilisées : `$connect`, `$disconnect` et `$default`. De plus, vous pouvez créer des routes personnalisées.
+ API Gateway appelle la `$connect` route lorsqu'une connexion persistante entre le client et une WebSocket API est initiée.
+ API Gateway appelle la route `$disconnect` lorsque le client ou le serveur se déconnecte de l’API.
+ API Gateway appelle une route personnalisée après évaluation de l’expression de sélection de la route par rapport au message si une route correspondante est trouvée ; la correspondance détermine l’intégration appelée.
+ API Gateway appelle la route `$default` si l’expression de sélection de la route ne peut pas être évaluée par rapport au message ou si aucune route correspondante n’est trouvée.
## Expressions de sélection de la route
Une *expression de sélection de la route* est évaluée lorsque le service sélectionne la route que doit suivre un message entrant. Le service utilise la route dont la clé `routeKey` correspond exactement à la valeur évaluée. Si aucune clé ne correspond et qu’une route avec la clé `$default` existe, celle-ci est sélectionnée. Si aucune route ne correspond à la valeur évaluée et qu’il n’y a pas de route `$default`, le service renvoie une erreur. Pour WebSocket based APIs, l'expression doit être de la forme`$request.body.{path_to_body_element}`.
Par exemple, supposons que vous envoyiez le message JSON suivant :
```
{
"service" : "chat",
"action" : "join",
"data" : {
"room" : "room1234"
}
}
```
Vous pouvez sélectionner le comportement de votre API en fonction de la propriété `action`. Dans ce cas, vous pouvez définir l’expression de sélection de la route suivante :
```
$request.body.action
```
Dans cet exemple, il `request.body` fait référence à la charge utile JSON de votre message et `.action` est une [JSONPath](https://goessner.net/articles/JsonPath/)expression. Vous pouvez utiliser n’importe quelle expression de chemin JSON après `request.body`, mais n’oubliez pas que le résultat sera obtenu à l’aide de stringify. Par exemple, si votre JSONPath expression renvoie un tableau de deux éléments, celui-ci sera présenté sous forme de chaîne`"[item1, item2]"`. C’est la raison pour laquelle il est recommandé d’utiliser une expression qui correspond à une valeur plutôt qu’à un tableau ou un objet.
Vous pouvez utiliser simplement une valeur statique ou plusieurs variables. Le tableau suivant montre des exemples et leurs résultats évalués par rapport à la charge utile précédente.
| Expression | Résultat évalué | Description |
| --- | --- | --- |
| \$1request.body.action | join | Variable désencapsulée |
| \$1\$1request.body.action\$1 | join | Variable encapsulée |
| \$1\$1request.body.service\$1/\$1\$1request.body.action\$1 | chat/join | Plusieurs variables avec des valeurs statiques |
| \$1\$1request.body.action\$1-\$1\$1request.body.invalidPath\$1 | join- | Si le n' JSONPath est pas trouvé, la variable est résolue sous la forme « ». |
| action | action | Valeur statique |
| \$1\$1default | \$1default | Valeur statique |
Le résultat évalué est utilisé pour trouver une route. S’il existe une route avec une clé de routage correspondante, elle est sélectionnée pour traiter le message. Si aucune route correspondante n’existe, API Gateway tente de trouver la route `$default`, si elle est disponible. Si la route `$default` n’est pas définie, API Gateway renvoie une erreur.
## Configuration de routes pour une WebSocket API dans API Gateway
Lorsque vous créez une nouvelle WebSocket API pour la première fois, il existe trois itinéraires prédéfinis : `$connect``$disconnect`, et`$default`. Vous pouvez les créer à l'aide de la console, de l'API ou AWS CLI. Si vous le souhaitez, vous pouvez créer des routes personnalisées. Pour plus d’informations, consultez [Vue d'ensemble de WebSocket APIs in API Gateway](apigateway-websocket-api-overview.md).
**Note**
Dans l’interface de ligne de commande, vous pouvez créer des routes avant ou après avoir créé des intégrations, et réutiliser la même intégration pour plusieurs routes.
### Création d’une route à l’aide de la console API Gateway
**Pour créer une route à l’aide de la console API Gateway**
1. Connectez-vous à la console API Gateway et choisissez l’API, puis choisissez **Routes**.
1. Choisissez **Créer une route**.
1. Pour **Clé de route**, entrez le nom de la clé de route. Vous pouvez créer les routes prédéfinies (`$connect`, `$disconnect` et `$default`) ou une route personnalisée.
**Note**
Lorsque vous créez une route personnalisée, n’utilisez pas le préfixe `$` dans le nom de la clé de routage. Ce préfixe est réservé aux routes prédéfinies.
1. Sélectionnez et configurez le type d’intégration pour la route. Pour de plus amples informations, veuillez consulter [Configuration d'une demande d'intégration d' WebSocket API à l'aide de la console API Gateway](apigateway-websocket-api-integration-requests.md#apigateway-websocket-api-integration-request-using-console).
### Créez un itinéraire à l'aide du AWS CLI
La commande [create-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route.html) suivante crée une route :
```
aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default
```
Le résultat se présente comme suit :
```
{
"ApiKeyRequired": false,
"AuthorizationType": "NONE",
"RouteKey": "$default",
"RouteId": "1122334"
}
```
### Spécification des paramètres de requête de routage pour `$connect`
Lorsque vous configurez la route `$connect` pour votre API, les paramètres facultatifs suivants sont disponibles pour activer les autorisations pour votre API. Pour plus d’informations, consultez [Route `$connect`](apigateway-websocket-api-route-keys-connect-disconnect.md#apigateway-websocket-api-routes-about-connect).
+ **Authorization (Autorisation)** : Si aucune autorisation n’est nécessaire, vous pouvez spécifier `NONE`. Sinon, vous pouvez spécifier :
+ `AWS_IAM`pour utiliser des politiques AWS IAM standard afin de contrôler l'accès à votre API.
+ `CUSTOM` pour implémenter l’autorisation pour une API en spécifiant une fonction de mécanisme d’autorisation Lambda que vous avez créée précédemment. L'autorisateur peut résider dans votre propre AWS compte ou sur un autre AWS compte. Pour plus d’informations sur les mécanismes d’autorisation Lambda, consultez [Utilisation des mécanismes d’autorisation Lambda API Gateway](apigateway-use-lambda-authorizer.md).
**Note**
Dans la console API Gateway, le paramètre `CUSTOM` est visible uniquement une fois que vous avez configuré une fonction de mécanisme d’autorisation, comme décrit dans [Configuration d’un mécanisme d’autorisation Lambda (console)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console).
**Important**
Le paramètre **Authorization (Autorisation)** est appliqué à l’ensemble de l’API, et pas uniquement à la route `$connect`. La route `$connect` protège les autres routes, car elle est appelée sur chaque connexion.
+ **Clé d’API obligatoire** : si vous le souhaitez, vous pouvez exiger une clé d’API pour une route `$connect` de l’API. Vous pouvez utiliser des clés d'API ainsi que des plans d'utilisation pour contrôler et suivre l'accès à votre APIs. Pour de plus amples informations, veuillez consulter [Plans d'utilisation et clés d'API pour REST APIs dans API Gateway](api-gateway-api-usage-plans.md).
### Configuration de la demande de route `$connect` à l’aide de la console API Gateway
Pour configurer la demande de `$connect` route pour une WebSocket API à l'aide de la console API Gateway, procédez comme suit :
1. Connectez-vous à la console API Gateway et choisissez l’API, puis choisissez **Routes**.
1. Sous **Routes**, choisissez `$connect` ou créez une route `$connect` en suivant [Création d’une route à l’aide de la console API Gateway](#apigateway-websocket-api-route-using-console).
1. Dans la section **Paramètres de requête de routage**, choisissez **Modifier**.
1. Pour **Autorisation**, sélectionnez un type d’autorisation.
1. Pour demander une API pour la route `$connect`, sélectionnez **Exiger une clé d’API**.
1. Sélectionnez **Enregistrer les modifications**.
# Configuration des réponses d'itinéraire pour WebSocket APIs dans API Gateway
WebSocket les itinéraires peuvent être configurés pour une communication bidirectionnelle ou unidirectionnelle. API Gateway ne transmet pas la réponse du backend à la réponse de routage, sauf si vous avez configuré une réponse de routage.
**Note**
Vous ne pouvez définir la réponse de l'`$default`itinéraire que pour WebSocket APIs. Vous pouvez utiliser une réponse d’intégration pour manipuler la réponse d’un service backend. Pour de plus amples informations, veuillez consulter [Présentation des réponses d’intégration](apigateway-websocket-api-integration-responses.md#apigateway-websocket-api-integration-response-overview).
Vous pouvez configurer les réponses d'itinéraire et les expressions de sélection des réponses à l'aide de la console API Gateway AWS CLI ou d'un AWS SDK.
Pour plus d’informations sur les expressions de sélection de la réponse de routage, consultez la section [Expressions de sélection de la réponse de routage](apigateway-websocket-api-selection-expressions.md#apigateway-websocket-api-route-response-selection-expressions).
**Topics**
+ [Configuration d’une réponse de routage à l’aide de la console API Gateway](#apigateway-websocket-api-route-response-using-console)
+ [Configurez une réponse d'itinéraire à l'aide du AWS CLI](#apigateway-websocket-api-route-response-using-awscli)
## Configuration d’une réponse de routage à l’aide de la console API Gateway
Après avoir créé une WebSocket API et attaché une fonction Lambda proxy à la route par défaut, vous pouvez configurer la réponse de route à l'aide de la console API Gateway :
1. Connectez-vous à la console API Gateway, choisissez une WebSocket API avec une intégration de la fonction Lambda par proxy sur la `$default` route.
1. Sous **Routes** (Routes), choisissez la route `$default`.
1. Choisissez **Activer la communication bidirectionnelle**.
1. Sélectionnez **Deploy API (Déployer une API)**.
1. Déployez votre API dans une étape.
Utilisez la commande [wscat](https://www.npmjs.com/package/wscat) suivante pour vous connecter à votre API. Pour plus d’informations sur `wscat`, consultez [`wscat`À utiliser pour se connecter à une WebSocket API et y envoyer des messages](apigateway-how-to-call-websocket-api-wscat.md).
```
wscat -c wss://api-id.execute-api.us-east-2.amazonaws.com/test
```
Appuyez sur la touche Entrée pour appeler la route par défaut. Le corps de votre fonction Lambda vous est renvoyé.
## Configurez une réponse d'itinéraire à l'aide du AWS CLI
La [create-route-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route-response.html)commande suivante crée une réponse d'itinéraire pour l'`$default`itinéraire. Vous pouvez identifier l’ID de l’API et l’ID du routage à l’aide des commandes [get-apis](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-apis.html) et [get-routes](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-routes.html).
```
aws apigatewayv2 create-route-response \
--api-id aabbccddee \
--route-id 1122334 \
--route-response-key '$default'
```
Le résultat se présente comme suit :
```
{
"RouteResponseId": "abcdef",
"RouteResponseKey": "$default"
}
```
# Configurer un `$connect` itinéraire qui nécessite un WebSocket sous-protocole
Les clients peuvent utiliser `Sec-WebSocket-Protocol` ce champ pour demander un [WebSocket sous-protocole](https://datatracker.ietf.org/doc/html/rfc6455#page-12) lors de la connexion à votre WebSocket API. Vous pouvez configurer une intégration pour la route `$connect` afin d’autoriser les connexions uniquement si un client demande un sous-protocole pris en charge par votre API.
L’exemple de fonction Lambda suivant renvoie l’en-tête `Sec-WebSocket-Protocol` aux clients. La fonction établit une connexion à votre API uniquement si le client spécifie le sous-protocole `myprotocol`.
Pour un CloudFormation modèle qui crée cet exemple d'intégration d'API et de proxy Lambda, consultez. [samples/ws-subprotocol.zip](samples/ws-subprotocol.zip)
```
export const handler = async (event) => {
if (event.headers != undefined) {
const headers = toLowerCaseProperties(event.headers);
if (headers['sec-websocket-protocol'] != undefined) {
const subprotocolHeader = headers['sec-websocket-protocol'];
const subprotocols = subprotocolHeader.split(',');
if (subprotocols.indexOf('myprotocol') >= 0) {
const response = {
statusCode: 200,
headers: {
"Sec-WebSocket-Protocol" : "myprotocol"
}
};
return response;
}
}
}
const response = {
statusCode: 400
};
return response;
};
function toLowerCaseProperties(obj) {
var wrapper = {};
for (var key in obj) {
wrapper[key.toLowerCase()] = obj[key];
}
return wrapper;
}
```
Vous pouvez utiliser [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat) pour vérifier que votre API autorise les connexions uniquement si un client demande un sous-protocole pris en charge par votre API. Les commandes suivantes utilisent l’indicateur `-s` pour spécifier des sous-protocoles pendant la connexion.
La commande suivante tente une connexion avec un sous-protocole non pris en charge. Étant donné que le client a spécifié le sous-protocole `chat1`, l’intégration Lambda renvoie une erreur 400 et la connexion échoue.
```
wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1
error: Unexpected server response: 400
```
La commande suivante inclut un sous-protocole pris en charge dans la demande de connexion. L’intégration Lambda permet la connexion.
```
wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1,myprotocol
connected (press CTRL+C to quit)
```
Pour en savoir plus sur l'invocation WebSocket APIs, consultez[Invoquer WebSocket APIs](apigateway-how-to-call-websocket-api.md).
# Contrôler et gérer l'accès WebSocket APIs à API Gateway
API Gateway prend en charge plusieurs mécanismes de contrôle et de gestion de l'accès à votre WebSocket API.
Les mécanismes suivants peuvent être utilisés pour l’authentification et l’autorisation :
+ Les **rôles et politiques AWS IAM standard** offrent des contrôles d'accès flexibles et robustes. Vous pouvez utiliser les rôles et les politiques IAM pour contrôler qui peut les créer et les gérer APIs, ainsi que les personnes habilitées à les invoquer. Pour de plus amples informations, veuillez consulter [Contrôler l'accès à l' WebSocket APIs aide d'une autorisation IAM](apigateway-websocket-control-access-iam.md).
+ Les **balises IAM** peuvent être utilisées avec des politiques IAM pour contrôler l’accès. Pour de plus amples informations, veuillez consulter [Utilisation de balises pour contrôler l’accès aux ressources API REST API Gateway](apigateway-tagging-iam-policy.md).
+ **Les autorisateurs Lambda sont des** fonctions Lambda qui contrôlent l'accès à. APIs Pour de plus amples informations, veuillez consulter [Contrôlez l'accès à l' WebSocket APIs aide des AWS Lambda autorisateurs REQUEST](apigateway-websocket-api-lambda-auth.md).
Pour améliorer votre niveau de sécurité, nous vous recommandons de configurer un autorisateur pour l'`$connect`itinéraire sur tous vos WebSocket APIs itinéraires. Vous devrez peut-être le faire pour vous conformer aux différents cadres de conformité. Pour plus d’informations, consultez [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) dans le *Guide de l’utilisateur AWS Security Hub *.
**Topics**
+ [Contrôler l'accès à l' WebSocket APIs aide d'une autorisation IAM](apigateway-websocket-control-access-iam.md)
+ [Contrôlez l'accès à l' WebSocket APIs aide des AWS Lambda autorisateurs REQUEST](apigateway-websocket-api-lambda-auth.md)
# Contrôler l'accès à l' WebSocket APIs aide d'une autorisation IAM
L'autorisation IAM dans WebSocket APIs est similaire à celle pour [REST APIs](api-gateway-control-access-using-iam-policies-to-invoke-api.md), avec les exceptions suivantes :
+ L’action `execute-api` prend en charge `ManageConnections` en plus des actions existantes (`Invoke`, `InvalidateCache`). `ManageConnections` contrôle l’accès à l’API @connections.
+ WebSocket les routes utilisent un format d'ARN différent :
```
arn:aws:execute-api:region:account-id:api-id/stage-name/route-key
```
+ L'`@connections`API utilise le même format ARN que REST APIs :
```
arn:aws:execute-api:region:account-id:api-id/stage-name/POST/@connections
```
**Important**
Lorsque vous utilisez [Autorisation IAM](#apigateway-websocket-control-access-iam), vous devez signer les requêtes avec [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html).
Par exemple, vous pouvez configurer la politique suivante pour le client. Cet exemple autorise tout le monde à envoyer un message (`Invoke`) pour toutes les routes, sauf pour une route secrète de l’étape `prod`, et empêche tout le monde de renvoyer un message aux clients connectés (`ManageConnections`) pour toutes les étapes.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/prod/*"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/prod/secret"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:ManageConnections"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/*"
]
}
]
}
```
------
# Contrôlez l'accès à l' WebSocket APIs aide des AWS Lambda autorisateurs REQUEST
Une fonction d'autorisation Lambda dans WebSocket APIs est similaire à celle de [REST APIs](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-lambda-function-create), avec les exceptions suivantes :
+ Vous pouvez uniquement utiliser une fonction de mécanisme d’autorisation Lambda pour la route `$connect`.
+ Vous ne pouvez pas utiliser de variables de chemin (`event.pathParameters`), car le chemin d’accès est fixe.
+ `event.methodArn` est différent de son équivalent de l’API REST, car il ne possède pas de méthode HTTP. Dans le cas de `$connect`, `methodArn` se termine par `"$connect"` :
```
arn:aws:execute-api:region:account-id:api-id/stage-name/$connect
```
+ Les variables de contexte `event.requestContext` sont différentes de celles de REST APIs.
L'exemple suivant montre une entrée dans un `REQUEST` autorisateur pour une WebSocket API :
```
{
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/default/$connect",
"headers": {
"Connection": "upgrade",
"content-length": "0",
"HeaderAuth1": "headerValue1",
"Host": "abcdef123.execute-api.us-east-1.amazonaws.com",
"Sec-WebSocket-Extensions": "permessage-deflate; client_max_window_bits",
"Sec-WebSocket-Key": "...",
"Sec-WebSocket-Version": "13",
"Upgrade": "websocket",
"X-Amzn-Trace-Id": "...",
"X-Forwarded-For": "...",
"X-Forwarded-Port": "443",
"X-Forwarded-Proto": "https"
},
"multiValueHeaders": {
"Connection": [
"upgrade"
],
"content-length": [
"0"
],
"HeaderAuth1": [
"headerValue1"
],
"Host": [
"abcdef123.execute-api.us-east-1.amazonaws.com"
],
"Sec-WebSocket-Extensions": [
"permessage-deflate; client_max_window_bits"
],
"Sec-WebSocket-Key": [
"..."
],
"Sec-WebSocket-Version": [
"13"
],
"Upgrade": [
"websocket"
],
"X-Amzn-Trace-Id": [
"..."
],
"X-Forwarded-For": [
"..."
],
"X-Forwarded-Port": [
"443"
],
"X-Forwarded-Proto": [
"https"
]
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"multiValueQueryStringParameters": {
"QueryString1": [
"queryValue1"
]
},
"stageVariables": {},
"requestContext": {
"routeKey": "$connect",
"eventType": "CONNECT",
"extendedRequestId": "...",
"requestTime": "19/Jan/2023:21:13:26 +0000",
"messageDirection": "IN",
"stage": "default",
"connectedAt": 1674162806344,
"requestTimeEpoch": 1674162806345,
"identity": {
"sourceIp": "..."
},
"requestId": "...",
"domainName": "abcdef123.execute-api.us-east-1.amazonaws.com",
"connectionId": "...",
"apiId": "abcdef123"
}
}
```
L'exemple de fonction d'autorisation Lambda suivant est une WebSocket version de la fonction d'autorisation Lambda pour REST dans : APIs [Exemples supplémentaires de fonctions de mécanisme d’autorisation Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-lambda-function-create)
------
#### [ Node.js ]
```
// A simple REQUEST authorizer example to demonstrate how to use request
// parameters to allow or deny a request. In this example, a request is
// authorized if the client-supplied HeaderAuth1 header and QueryString1 query parameter
// in the request context match the specified values of
// of 'headerValue1' and 'queryValue1' respectively.
export const handler = function(event, context, callback) {
console.log('Received event:', JSON.stringify(event, null, 2));
// Retrieve request parameters from the Lambda function input:
var headers = event.headers;
var queryStringParameters = event.queryStringParameters;
var stageVariables = event.stageVariables;
var requestContext = event.requestContext;
// Parse the input for the parameter values
var tmp = event.methodArn.split(':');
var apiGatewayArnTmp = tmp[5].split('/');
var awsAccountId = tmp[4];
var region = tmp[3];
var ApiId = apiGatewayArnTmp[0];
var stage = apiGatewayArnTmp[1];
var route = apiGatewayArnTmp[2];
// Perform authorization to return the Allow policy for correct parameters and
// the 'Unauthorized' error, otherwise.
var authResponse = {};
var condition = {};
condition.IpAddress = {};
if (headers.HeaderAuth1 === "headerValue1"
&& queryStringParameters.QueryString1 === "queryValue1") {
callback(null, generateAllow('me', event.methodArn));
} else {
callback(null, generateDeny('me', event.methodArn));
}
}
// Helper function to generate an IAM policy
var generatePolicy = function(principalId, effect, resource) {
// Required output:
var authResponse = {};
authResponse.principalId = principalId;
if (effect && resource) {
var policyDocument = {};
policyDocument.Version = '2012-10-17 '; // default version
policyDocument.Statement = [];
var statementOne = {};
statementOne.Action = 'execute-api:Invoke'; // default action
statementOne.Effect = effect;
statementOne.Resource = resource;
policyDocument.Statement[0] = statementOne;
authResponse.policyDocument = policyDocument;
}
// Optional output with custom properties of the String, Number or Boolean type.
authResponse.context = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": true
};
return authResponse;
}
var generateAllow = function(principalId, resource) {
return generatePolicy(principalId, 'Allow', resource);
}
var generateDeny = function(principalId, resource) {
return generatePolicy(principalId, 'Deny', resource);
}
```
------
#### [ Python ]
```
# A simple REQUEST authorizer example to demonstrate how to use request
# parameters to allow or deny a request. In this example, a request is
# authorized if the client-supplied HeaderAuth1 header and QueryString1 query parameter
# in the request context match the specified values of
# of 'headerValue1' and 'queryValue1' respectively.
import json
def lambda_handler(event, context):
print(event)
# Retrieve request parameters from the Lambda function input:
headers = event['headers']
queryStringParameters = event['queryStringParameters']
stageVariables = event['stageVariables']
requestContext = event['requestContext']
# Parse the input for the parameter values
tmp = event['methodArn'].split(':')
apiGatewayArnTmp = tmp[5].split('/')
awsAccountId = tmp[4]
region = tmp[3]
ApiId = apiGatewayArnTmp[0]
stage = apiGatewayArnTmp[1]
route = apiGatewayArnTmp[2]
# Perform authorization to return the Allow policy for correct parameters
# and the 'Unauthorized' error, otherwise.
authResponse = {}
condition = {}
condition['IpAddress'] = {}
if (headers['HeaderAuth1'] ==
"headerValue1" and queryStringParameters["QueryString1"] == "queryValue1"):
response = generateAllow('me', event['methodArn'])
print('authorized')
return json.loads(response)
else:
response = generateDeny('me', event['methodArn'])
print('unauthorized')
return json.loads(response)
# Help function to generate IAM policy
def generatePolicy(principalId, effect, resource):
authResponse = {}
authResponse['principalId'] = principalId
if (effect and resource):
policyDocument = {}
policyDocument['Version'] = '2012-10-17 '
policyDocument['Statement'] = []
statementOne = {}
statementOne['Action'] = 'execute-api:Invoke'
statementOne['Effect'] = effect
statementOne['Resource'] = resource
policyDocument['Statement'] = [statementOne]
authResponse['policyDocument'] = policyDocument
authResponse['context'] = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": True
}
authResponse_JSON = json.dumps(authResponse)
return authResponse_JSON
def generateAllow(principalId, resource):
return generatePolicy(principalId, 'Allow', resource)
def generateDeny(principalId, resource):
return generatePolicy(principalId, 'Deny', resource)
```
------
[Pour configurer la fonction Lambda précédente en tant que fonction d'`REQUEST`autorisation pour une WebSocket API, suivez la même procédure que pour REST. APIs](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console)
Pour configurer la route `$connect` afin qu’elle utilise ce mécanisme d’autorisation Lambda dans la console, sélectionnez ou créez la route `$connect`. Dans la section **Paramètres de la demande de route**, choisissez **Modifier**. Sélectionnez votre mécanisme d’autorisation dans le menu déroulant **Autorisation**, puis choisissez **Enregistrer les modifications**.
Pour tester le mécanisme d’autorisation, vous devez créer une nouvelle connexion. La modification du mécanisme d’autorisation dans `$connect` n’affecte pas le client déjà connecté. Lorsque vous vous connectez à votre WebSocket API, vous devez fournir des valeurs pour toutes les sources d'identité configurées. Par exemple, vous pouvez vous connecter en envoyant une chaîne de requête et un en-tête en utilisant `wscat` comme dans l’exemple suivant :
```
wscat -c 'wss://myapi.execute-api.us-east-1.amazonaws.com/beta?QueryString1=queryValue1' -H HeaderAuth1:headerValue1
```
Si vous tentez de vous connecter sans valeur d’identité valide, vous recevrez une réponse `401` :
```
wscat -c wss://myapi.execute-api.us-east-1.amazonaws.com/beta
error: Unexpected server response: 401
```
# Intégrations pour WebSocket APIs in API Gateway
Après avoir configuré une route d’API, vous devez l’intégrer avec un point de terminaison dans le serveur principal. Un point de terminaison principal est également appelé point de terminaison d'intégration et peut être une fonction Lambda, un point de terminaison HTTP ou AWS une action de service. L’intégration de l’API a une demande d’intégration et une réponse d’intégration.
Dans cette section, vous découvrirez comment configurer les demandes d'intégration et les réponses d'intégration pour votre WebSocket API.
**Topics**
+ [Configurer une demande d'intégration d' WebSocket API dans API Gateway](apigateway-websocket-api-integration-requests.md)
+ [Configurer une réponse d'intégration d' WebSocket API dans API Gateway](apigateway-websocket-api-integration-responses.md)
# Configurer une demande d'intégration d' WebSocket API dans API Gateway
La configuration d’une demande d’intégration comprend les opérations suivantes :
+ La sélection d’une clé de routage à intégrer avec le serveur principal.
+ Spécifier le point de terminaison du backend à appeler. WebSocket APIs prennent en charge les types d'intégration suivants :
+ `AWS_PROXY`
+ `AWS`
+ `HTTP_PROXY`
+ `HTTP`
+ `MOCK`
Pour plus d'informations sur les types d'intégration, consultez [IntegrationType](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)l'API REST API Gateway V2.
+ La configuration de la transformation des données de la demande de routage, si nécessaire, en données de demande d’intégration en spécifiant un ou plusieurs modèles de demande.
## Configuration d'une demande d'intégration d' WebSocket API à l'aide de la console API Gateway
**Pour ajouter une demande d'intégration à un itinéraire dans une WebSocket API à l'aide de la console API Gateway**
1. Connectez-vous à la console API Gateway et choisissez l’API, puis choisissez **Routes**.
1. Sous **Routes**, choisissez la route.
1. Choisissez l’onglet **Demande d’intégration**, puis dans la section **Paramètres de la demande d’intégration**, choisissez **Modifier**.
1. Pour **Type d’intégration**, sélectionnez l’une des valeurs suivantes :
+ Choisissez la **fonction Lambda** uniquement si votre API doit être intégrée à une AWS Lambda fonction que vous avez déjà créée dans ce compte ou dans un autre compte.
**Pour créer une nouvelle fonction Lambda dans AWS Lambda, pour définir une autorisation de ressource sur la fonction Lambda ou pour effectuer toute autre action de service Lambda, choisissez plutôt Service.AWS **
+ Sélectionnez **HTTP** si votre API doit être intégrée avec un point de terminaison HTTP existant. Pour de plus amples informations, veuillez consulter [Intégrations HTTP pour REST APIs dans API Gateway](setup-http-integrations.md).
+ Choisissez **Mock** si vous souhaitez générer des réponses d’API directement depuis API Gateway, sans recourir à un backend d’intégration. Pour de plus amples informations, veuillez consulter [Intégrations fictives pour REST APIs dans API Gateway](how-to-mock-integration.md).
+ Choisissez **AWS un service** si votre API doit être intégrée à un AWS service.
+ Choisissez **Lien VPC** si votre API doit utiliser un `VpcLink` en tant que point de terminaison d’intégration privé. Pour de plus amples informations, veuillez consulter [Configurez une intégration privée](set-up-private-integration.md).
1. Si vous avez sélectionné **Fonction Lambda**, procédez comme suit :
1. Pour **Utiliser une intégration proxy Lambda**, cochez la case si vous avez l’intention d’utiliser [Intégration proxy Lambda](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy) ou [Intégration proxy Lambda entre comptes](apigateway-cross-account-lambda-integrations.md).
1. Pour **Fonction Lambda**, spécifiez la fonction de l’une des manières suivantes :
+ Si votre Fonction Lambda se trouve dans le même compte, entrez le nom de la fonction, puis sélectionnez la fonction dans la liste déroulante.
**Note**
Le nom de la fonction peut éventuellement inclure son alias ou sa spécification de version, comme dans `HelloWorld`, `HelloWorld:1` ou `HelloWorld:alpha`.
+ Si la fonction se trouve dans un autre compte, tapez l’ARN de la fonction.
1. Pour utiliser la valeur de délai d'expiration par défaut de 29 secondes, gardez **Délai d'expiration** activé. Pour définir un délai d'expiration personnalisé, choisissez **Délai d'expiration** et entrez une valeur de délai d'expiration comprise entre `50` et `29000` millisecondes.
1. Si vous avez sélectionné **HTTP**, suivez les instructions de l’étape 4 de la section [Configuration d’une demande d’intégration d’API à l’aide de la console API Gateway](how-to-method-settings-console.md).
1. Si vous avez sélectionné **Mock (Fictif)**, passez à l’étape **Request Templates (Modèles de demande)**.
1. Si vous avez choisi **Service AWS **, suivez les instructions de l’étape 6 de [Configuration d’une demande d’intégration d’API à l’aide de la console API Gateway](how-to-method-settings-console.md).
1. Si vous avez sélectionné **Lien VPC**, procédez comme suit :
1. Pour **Intégration proxy au VPC**, sélectionnez la case à cocher si vous souhaitez que vos demandes soient traitées par proxy vers le point de terminaison de votre `VPCLink`.
1. Dans le champ **Méthode HTTP**, sélectionnez le type de méthode HTTP qui correspond le mieux au service backend HTTP.
1. Dans la liste déroulante **Lien VPC**, sélectionnez un lien VPC. Vous pouvez sélectionner `[Use Stage Variables]` et entrer **\$1\$1stageVariables.vpcLinkId\$1** dans la zone de texte en dessous de la liste.
Vous pouvez définir la variable d’étape `vpcLinkId` après le déploiement de l’API dans une étape et définir sa valeur sur l’ID du `VpcLink`.
1. Pour **URL du point de terminaison**, entrez l’URL du back-end HTTP que cette intégration doit utiliser.
1. Pour utiliser la valeur de délai d'expiration par défaut de 29 secondes, gardez **Délai d'expiration** activé. Pour définir un délai d'expiration personnalisé, choisissez **Délai d'expiration** et entrez une valeur de délai d'expiration comprise entre `50` et `29000` millisecondes.
1. Sélectionnez **Enregistrer les modifications**.
1. Sous **Modèles de demande**, procédez comme suit :
1. Pour entrer une **Expression de sélection de modèle**, sous **Modèles de demande**, choisissez **Modifier**.
1. Entrez une **Expression de sélection de modèle**. Utilisez une expression qu’API Gateway recherche dans la charge utile du message. S’il la trouve, il l’évalue, et le résultat est une valeur de clé de modèle qui est utilisée pour sélectionner le modèle de mappage de données à appliquer aux données dans la charge utile du message. Vous créez le modèle de mappage de données à la prochaine étape. Choisissez **Modifier** pour enregistrer vos modifications.
1. Choisissez **Créer un modèle** pour créer le modèle de mappage de données. Pour **Clé de modèle**, entrez une valeur de clé de modèle qui est utilisée pour sélectionner le modèle de mappage de données à appliquer aux données dans la charge utile du message. Entrez ensuite un modèle de mappage. Sélectionnez **Create template (Créer un modèle)**.
Pour plus d’informations sur les expressions de sélection du modèle, consultez la section [Expressions de sélection du modèle](websocket-api-data-transformations.md#apigateway-websocket-api-template-selection-expressions).
## Configurez une demande d'intégration à l'aide du AWS CLI
Vous pouvez configurer une demande d'intégration pour un itinéraire dans une WebSocket API en utilisant l' AWS CLI exemple suivant, qui crée une intégration fictive :
1. Créez un fichier nommé `integration-params.json`, avec le contenu suivant :
```
{"PassthroughBehavior": "WHEN_NO_MATCH", "TimeoutInMillis": 29000, "ConnectionType": "INTERNET", "RequestTemplates": {"application/json": "{\"statusCode\":200}"}, "IntegrationType": "MOCK"}
```
1. Utilisez la commande [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) suivante pour créer l’intégration simulée.
```
aws apigatewayv2 --region us-east-1 create-integration --api-id aabbccddee --cli-input-json file://integration-params.json
```
Le résultat se présente comme suit :
```
{
"PassthroughBehavior": "WHEN_NO_MATCH",
"TimeoutInMillis": 29000,
"ConnectionType": "INTERNET",
"IntegrationResponseSelectionExpression": "${response.statuscode}",
"RequestTemplates": {
"application/json": "{\"statusCode\":200}"
},
"IntegrationId": "0abcdef",
"IntegrationType": "MOCK"
}
```
Vous pouvez également configurer une demande d'intégration pour une intégration par proxy en utilisant le AWS CLI.
1. Créez une fonction Lambda dans la console Lambda et attribuez-lui un rôle d’exécution Lambda de base.
1. Utilisez la commande [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) suivante pour créer l’intégration.
```
aws apigatewayv2 create-integration --api-id aabbccddee --integration-type AWS_PROXY --integration-method POST --integration-uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations
```
Le résultat se présente comme suit :
```
{
"PassthroughBehavior": "WHEN_NO_MATCH",
"IntegrationMethod": "POST",
"TimeoutInMillis": 29000,
"ConnectionType": "INTERNET",
"IntegrationUri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations",
"IntegrationId": "abcdefg",
"IntegrationType": "AWS_PROXY"
}
```
## Format d'entrée d'une fonction Lambda pour l'intégration de proxy pour WebSocket APIs
Avec l’intégration de proxy Lambda, API Gateway mappe l’intégralité de la demande du client avec le paramètre `event` en entrée de la fonction Lambda du backend. L’exemple suivant montre la structure de l’événement d’entrée de la route `$connect` et de l’événement d’entrée de la route `$disconnect` qu’API Gateway envoie à une intégration de proxy Lambda.
------
#### [ Input from the \$1connect route ]
```
{
headers: {
Host: 'abcd123.execute-api.us-east-1.amazonaws.com',
'Sec-WebSocket-Extensions': 'permessage-deflate; client_max_window_bits',
'Sec-WebSocket-Key': '...',
'Sec-WebSocket-Version': '13',
'X-Amzn-Trace-Id': '...',
'X-Forwarded-For': '192.0.2.1',
'X-Forwarded-Port': '443',
'X-Forwarded-Proto': 'https'
},
multiValueHeaders: {
Host: [ 'abcd123.execute-api.us-east-1.amazonaws.com' ],
'Sec-WebSocket-Extensions': [ 'permessage-deflate; client_max_window_bits' ],
'Sec-WebSocket-Key': [ '...' ],
'Sec-WebSocket-Version': [ '13' ],
'X-Amzn-Trace-Id': [ '...' ],
'X-Forwarded-For': [ '192.0.2.1' ],
'X-Forwarded-Port': [ '443' ],
'X-Forwarded-Proto': [ 'https' ]
},
requestContext: {
routeKey: '$connect',
eventType: 'CONNECT',
extendedRequestId: 'ABCD1234=',
requestTime: '09/Feb/2024:18:11:43 +0000',
messageDirection: 'IN',
stage: 'prod',
connectedAt: 1707502303419,
requestTimeEpoch: 1707502303420,
identity: { sourceIp: '192.0.2.1' },
requestId: 'ABCD1234=',
domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com',
connectionId: 'AAAA1234=',
apiId: 'abcd1234'
},
isBase64Encoded: false
}
```
------
#### [ Input from the \$1disconnect route ]
```
{
headers: {
Host: 'abcd1234.execute-api.us-east-1.amazonaws.com',
'x-api-key': '',
'X-Forwarded-For': '',
'x-restapi': ''
},
multiValueHeaders: {
Host: [ 'abcd1234.execute-api.us-east-1.amazonaws.com' ],
'x-api-key': [ '' ],
'X-Forwarded-For': [ '' ],
'x-restapi': [ '' ]
},
requestContext: {
routeKey: '$disconnect',
disconnectStatusCode: 1005,
eventType: 'DISCONNECT',
extendedRequestId: 'ABCD1234=',
requestTime: '09/Feb/2024:18:23:28 +0000',
messageDirection: 'IN',
disconnectReason: 'Client-side close frame status not set',
stage: 'prod',
connectedAt: 1707503007396,
requestTimeEpoch: 1707503008941,
identity: { sourceIp: '192.0.2.1' },
requestId: 'ABCD1234=',
domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com',
connectionId: 'AAAA1234=',
apiId: 'abcd1234'
},
isBase64Encoded: false
}
```
------
# Configurer une réponse d'intégration d' WebSocket API dans API Gateway
La section suivante fournit un bref aperçu des réponses d'intégration pour une WebSocket API et explique comment configurer une réponse d'intégration pour une WebSocket API.
**Topics**
+ [Présentation des réponses d’intégration](#apigateway-websocket-api-integration-response-overview)
+ [Réponses d’intégration pour une communication bidirectionnelle](#apigateway-websocket-api-integration-response-for-two-way-communication)
+ [Configuration d’une réponse d’intégration à l’aide de la console API Gateway](#apigateway-websocket-api-integration-response-using-console)
+ [Configurez une réponse d'intégration à l'aide du AWS CLI](#apigateway-websocket-api-integration-response-using-awscli)
## Présentation des réponses d’intégration
La réponse d’intégration d’API Gateway permet de modéliser et de manipuler la réponse reçue d’un service backend. Il existe certaines différences entre la configuration d'une API REST et une réponse d'intégration d' WebSocket API, mais le comportement est conceptuellement le même.
WebSocket les itinéraires peuvent être configurés pour une communication bidirectionnelle ou unidirectionnelle.
+ Lorsqu'un itinéraire est configuré pour une communication bidirectionnelle, une réponse d'intégration vous permet de configurer des transformations sur la charge utile du message renvoyé, de la même manière que les réponses d'intégration pour REST. APIs
+ Si un itinéraire est configuré pour une communication unidirectionnelle, quelle que soit la configuration de réponse d'intégration, aucune réponse ne sera renvoyée sur le WebSocket canal une fois le message traité.
API Gateway ne transmet pas la réponse du backend à la réponse de routage, sauf si vous avez configuré une réponse de routage. Pour en savoir plus sur la configuration d’une réponse de routage, consultez [Configuration des réponses d'itinéraire pour WebSocket APIs dans API Gateway](apigateway-websocket-api-route-response.md).
## Réponses d’intégration pour une communication bidirectionnelle
Les intégrations peuvent être divisées en intégrations de *proxy* et *autres que de proxy*.
**Important**
Pour les *intégrations de proxy*, API Gateway transmet automatiquement la sortie du backend à l’appelant en tant que charge utile complète. Il n’y a pas de réponse d’intégration.
Pour les *intégrations autres que de proxy*, vous devez configurer au moins une réponse d’intégration :
+ Idéalement, une de vos réponses d’intégration doit servir de fourre-tout lorsqu’aucun choix explicite ne peut être effectué. Ce cas par défaut est représenté en définissant une clé de réponse d’intégration `$default`.
+ Dans tous les autres cas, la clé de réponse d’intégration fonctionne en tant qu’expression régulière. Elle doit suivre le format `"/expression/"`.
Pour les intégrations HTTP autres que de proxy :
+ API Gateway tente de mettre en correspondance le code de statut HTTP de la réponse du backend. Dans ce cas, la clé de réponse d’intégration fonctionne en tant qu’expression régulière. Si aucune correspondance n’est trouvée, `$default` est choisi en tant que réponse d’intégration.
+ L’expression de sélection du modèle décrite ci-dessus fonctionne de manière identique. Exemples :
+ `/2\d\d/` : reçoit et transforme les réponses fructueuses
+ `/4\d\d/` : reçoit et transforme les erreurs de demande incorrecte
+ `$default` : reçoit et transforme toutes les réponses inattendues
Pour en savoir plus sur les expressions de sélection de modèle, consultez [Expressions de sélection du modèle](websocket-api-data-transformations.md#apigateway-websocket-api-template-selection-expressions).
## Configuration d’une réponse d’intégration à l’aide de la console API Gateway
Pour configurer une réponse d'intégration d'itinéraires pour une WebSocket API à l'aide de la console API Gateway :
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez votre WebSocket API et votre itinéraire.
1. Choisissez l’onglet **Demande d’intégration**, puis dans la section **Paramètres de la réponse d’intégration**, choisissez **Créer une réponse d’intégration**.
1. Pour **Clé de réponse**, saisissez une valeur qui sera trouvée dans la clé de réponse trouvée dans le message sortant après avoir évalué l’expression de sélection de réponse. Par exemple, vous pouvez entrer **/4\$1d\$1d/** pour recevoir et transformer les erreurs de mauvaise demande ou entrer **\$1default** pour recevoir et transformer toutes les réponses qui correspondent à l’expression de sélection du modèle.
1. Pour **Expression de sélection du modèle**, entrez une expression de sélection pour évaluer le message sortant.
1. Choisissez **Créer une réponse**.
1. Vous pouvez également définir un modèle de mappage pour configurer les transformations de votre charge utile de message renvoyé. Sélectionnez **Create template (Créer un modèle)**.
1. Saisissez un nom de clé. Si vous choisissez l’expression de sélection de modèle par défaut, saisissez **\$1\$1default**.
1. Pour **Modèle de réponse**, entrez votre modèle de mappage dans l’éditeur de code.
1. Sélectionnez **Create template (Créer un modèle)**.
1. Choisissez **Déployer l’API** pour déployer votre API.
Utilisez la commande [wscat](https://www.npmjs.com/package/wscat) suivante pour vous connecter à votre API. Pour plus d’informations sur `wscat`, consultez [`wscat`À utiliser pour se connecter à une WebSocket API et y envoyer des messages](apigateway-how-to-call-websocket-api-wscat.md).
```
wscat -c wss://api-id.execute-api.us-east-2.amazonaws.com/test
```
Lorsque vous appelez votre route, la charge utile de message renvoyé est renvoyée.
## Configurez une réponse d'intégration à l'aide du AWS CLI
La [create-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration-response.html)commande suivante crée une réponse `$default` d'intégration :
```
aws apigatewayv2 create-integration-response \
--api-id vaz7da96z6 \
--integration-id a1b2c3 \
--integration-response-key '$default'
```
# Demande de validation pour WebSocket APIs in API Gateway
Vous pouvez configurer API Gateway afin qu’il exécute la validation d’une requête de routage avant de continuer avec la demande d’intégration. Si la validation échoue, API Gateway échoue à la demande sans appeler votre backend, envoie une réponse de passerelle « Bad request body » au client et publie les résultats de la validation dans les CloudWatch journaux. L’utilisation de la validation de cette façon réduit les appels inutiles vers votre back-end d’API.
## Expressions de sélection du modèle
Vous pouvez utiliser une expression de sélection de modèle pour valider dynamiquement les requêtes au sein d’une même route. La validation du modèle se produit si vous fournissez une expression de sélection de modèle pour les intégrations proxy ou autres que de proxy. Vous devrez peut-être définir le modèle `$default` comme solution de secours si aucun modèle correspondant n’est trouvé. S’il n’y a pas de modèle correspondant et que `$default` n’est pas défini, la validation échoue. L’expression de sélection ressemble à `Route.ModelSelectionExpression` et évalue à la clé pour `Route.RequestModels`.
Lorsque vous définissez un itinéraire pour une WebSocket API, vous pouvez éventuellement spécifier une *expression de sélection de modèle*. Cette expression est évaluée pour sélectionner le modèle à utiliser pour la validation du corps lors de la réception d’une requête. L’expression correspond à l’une des entrées de l’élément d’une route [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes.html#apis-apiid-routes-prop-route-requestmodels](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes.html#apis-apiid-routes-prop-route-requestmodels).
Un modèle est exprimé sous forme de [schéma JSON](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) et décrit la structure des données du corps de la requête. La nature de ces expressions de sélection vous permet de choisir de manière dynamique le modèle à utiliser pour la validation lors de l’exécution pour une route particulière. Pour plus d’informations sur la création d’un modèle, consultez la section [Modèles de données pour REST APIs](models-mappings-models.md).
## Configuration de la validation des requêtes à l’aide de la console API Gateway
L’exemple suivant vous montre comment configurer une validation des demandes sur une route.
Vous devez d’abord créer un modèle, puis une route. Ensuite, vous devez configurer la validation des demandes sur la route que vous venez de créer. Enfin, vous devez déployer et tester votre API. Pour terminer ce didacticiel, vous avez besoin d'une WebSocket API `$request.body.action` servant d'expression de sélection d'itinéraire et d'un point de terminaison d'intégration pour votre nouvel itinéraire.
Vous avez également besoin de `wscat` pour vous connecter à votre API. Pour de plus amples informations, veuillez consulter [`wscat`À utiliser pour se connecter à une WebSocket API et y envoyer des messages](apigateway-how-to-call-websocket-api-wscat.md).
**Pour créer un modèle**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une WebSocket API.
1. Dans le volet de navigation principal, choisissez **Modèles**.
1. Sélectionnez **Créer un modèle**.
1. Pour **Nom**, saisissez **emailModel**.
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Schéma du modèle**, saisissez le modèle qui suit :
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type" : "object",
"required" : [ "address"],
"properties" : {
"address": {
"type": "string"
}
}
}
```
Ce modèle nécessite que la requête contienne une adresse e-mail.
1. Choisissez **Enregistrer**.
Au cours de cette étape, vous allez créer un itinéraire pour votre WebSocket API.
**Pour créer une route**
1. Dans le volet de navigation principal, sélectionnez **Routes**.
1. Choisissez **Create Route (Créer un itinéraire)**.
1. Pour **Route key (Clé de route)**, entrez **sendMessage**.
1. Choisissez un type d’intégration et spécifiez un point de terminaison d’intégration. Pour plus d’informations, consultez [Intégrations pour WebSocket APIs in API Gateway](apigateway-websocket-api-integrations.md).
1. Choisissez **Create Route (Créer un itinéraire)**.
Au cours de cette étape, vous allez configurer la validation des demandes pour la route `sendMessage`.
**Pour configurer une validation des demandes**
1. Dans l’onglet **Requête de routage**, sous **Paramètres de requête de routage**, choisissez **Modifier**.
1. Pour **Expression de sélection de modèle**, saisissez **\$1\$1request.body.messageType\$1**.
API Gateway utilise la propriété `messageType` pour valider la requête entrante.
1. Choisissez **Ajouter un modèle de requête**.
1. Pour **Clé de modèle**, saisissez **email**.
1. Pour **Modèle**, choisissez **emailModel**.
API Gateway valide les messages entrants avec la propriété `messageType` définie sur `email` pour ce modèle.
**Note**
Si API Gateway ne parvient pas à faire correspondre l’expression de sélection du modèle à une clé de modèle, le modèle `$default` est sélectionné. S’il n’y a pas de modèle `$default`, la validation échoue. Pour la production APIs, nous vous recommandons de créer un `$default` modèle.
1. Sélectionnez **Enregistrer les modifications**.
Au cours de cette étape, vous allez déployer et tester votre API.
**Pour déployer et tester votre API**
1. Sélectionnez **Deploy API (Déployer une API)**.
1. Choisissez l’étape souhaitée dans la liste déroulante ou saisissez le nom d’une nouvelle étape.
1. Choisissez **Déployer**.
1. Dans le volet de navigation principal, choisissez **Étapes**.
1. Copiez l' WebSocket URL de votre API. L’URL doit ressembler à `wss://abcdef123.execute-api.us-east-2.amazonaws.com/production`.
1. Ouvrez un nouveau terminal et exécutez la commande **wscat** avec les paramètres suivants.
```
wscat -c wss://abcdef123.execute-api.us-west-2.amazonaws.com/production
```
```
Connected (press CTRL+C to quit)
```
1. Utilisez la commande suivante pour tester votre API.
```
{"action": "sendMessage", "messageType": "email"}
```
```
{"message": "Invalid request body", "connectionId":"ABCD1=234", "requestId":"EFGH="}
```
API Gateway rejettera la requête.
Utilisez la commande suivante pour envoyer une demande valide à votre API.
```
{"action": "sendMessage", "messageType": "email", "address": "mary_major@example.com"}
```
# Transformations de données pour WebSocket APIs dans API Gateway
Dans API Gateway, la demande de méthode d'une WebSocket API peut prendre une charge utile dans un format différent de la charge utile de la demande d'intégration correspondante, comme l'exige le backend. De même, le serveur principal peut renvoyer une charge utile de réponse d’intégration différente de la charge utile de réponse de méthode attendue par le serveur frontal.
API Gateway vous permet d’utiliser les transformations de modèles de mappage pour mapper les données utiles d’une demande de méthode à la demande d’intégration correspondante, et d’une réponse d’intégration à la réponse de méthode correspondante. Vous allez créer un modèle de mappage et spécifier une expression de sélection de modèle afin de déterminer le modèle à utiliser pour effectuer les transformations de données nécessaires.
Vous pouvez utiliser des mappages de données pour mapper des données d’une [demande de routage](api-gateway-basic-concept.md#apigateway-definition-route-request) à une intégration backend. Pour en savoir plus, consultez la section [Configurer le mappage des données pour WebSocket APIs dans API Gateway](websocket-api-data-mapping.md).
## Modèles et modèles de mappage
[Un *modèle de mappage* est un script exprimé dans le [langage VTL (Velocity Template Language)](https://velocity.apache.org/engine/devel/vtl-reference.html) et appliqué à la charge utile à l'aide d'JSONPath expressions.](https://goessner.net/articles/JsonPath/) Pour plus d’informations sur les modèles de mappage API Gateway, consultez [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
La charge utile peut comporter un *modèle de données* en fonction du [schéma JSON version 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04). Vous n’avez pas besoin de définir un modèle pour créer un modèle de mappage. Toutefois, un modèle peut vous aider à créer un modèle de mappage, car API Gateway génère un plan de modèle en fonction du modèle fourni. Pour plus d’informations sur les modèles API Gateway, consultez [Modèles de données pour REST APIs](models-mappings-models.md).
## Expressions de sélection du modèle
Pour transformer une charge utile à l'aide d'un modèle de mappage, vous devez spécifier une expression de sélection de modèle d' WebSocket API dans une [demande d'intégration](apigateway-websocket-api-integration-requests.md) ou une [réponse d'intégration](apigateway-websocket-api-integration-responses.md). Cette expression est évaluée pour déterminer le modèle d’entrée ou de sortie (le cas échéant) à utiliser pour transformer le corps de la demande en corps de demande d’intégration (via un modèle d’entrée) ou le corps de la réponse au corps de la réponse de routage (via un modèle de sortie).
`Integration.TemplateSelectionExpression` prend en charge `${request.body.jsonPath}` et les valeurs statiques.
`IntegrationResponse.TemplateSelectionExpression` prend en charge `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}` et des valeurs statiques.
## Expressions de sélection de la réponse d’intégration
Lorsque vous [configurez une réponse d'intégration](apigateway-websocket-api-integration-responses.md) pour une WebSocket API, vous pouvez éventuellement spécifier une expression de sélection de réponse d'intégration. Cette expression détermine quelle `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html)` doit être sélectionnée lorsqu’une intégration est renvoyée. La valeur de cette expression est actuellement restreinte par API Gateway, comme défini ci-dessous. Gardez à l’esprit que cette expression est uniquement pertinente pour des *intégrations autres que de proxy*. Une intégration de proxy transmet simplement la charge utile de la réponse à l’appelant sans modélisation ni modification.
Contrairement aux autres expressions de sélection précédentes, cette expression prend actuellement en charge un format de *correspondance de modèle*. L’expression doit être encapsulée avec des barres obliques.
Actuellement, la valeur est fixée en fonction de l’élément `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)`:
+ Pour les intégrations basées sur Lambda, la valeur est `$integration.response.body.errorMessage`.
+ Pour les intégrations `HTTP` et `MOCK`, la valeur est `$integration.response.statuscode`.
+ Pour `HTTP_PROXY` et `AWS_PROXY`, l’expression n’est pas utilisée, car vous demandez que la charge utile soit transmise à l’appelant.
# Configurer le mappage des données pour WebSocket APIs dans API Gateway
Le *mappage de données* vous permet de mapper des données d’une [demande de routage](api-gateway-basic-concept.md#apigateway-definition-route-request) vers une intégration backend.
**Note**
Le mappage de données pour WebSocket APIs n'est pas pris en charge dans le AWS Management Console. Vous devez utiliser le AWS CLI AWS CloudFormation, ou un SDK pour configurer le mappage des données.
**Topics**
+ [Mappage des données de demande de routage à des paramètres de demande d’intégration](#websocket-mapping-request-parameters)
+ [Exemples](#websocket-data-mapping-examples)
## Mappage des données de demande de routage à des paramètres de demande d’intégration
Les paramètres de demande d’intégration peuvent être mappés à partir de n’importe quels paramètres de demande de routage défini, du corps de la demande, des variables [`context` ou ](api-gateway-mapping-template-reference.md#context-variable-reference) [`stage`](api-gateway-mapping-template-reference.md#stagevariables-template-reference), ainsi que des valeurs statiques.
Le tableau suivant présente les expressions de mappage des données des demandes d’intégration. Dans le tableau, *`PARAM_NAME`* est le nom d’un paramètre de demande de routage du type de paramètre donné. Elle doit correspondre à l'expression régulière`'^[a-zA-Z0-9._$-]+$]'`. *JSONPath\$1EXPRESSION*est une JSONPath expression pour un champ JSON du corps de la requête.
| Source de données mappée | Expression de mappage |
| --- | --- |
| Chaîne de requête de demande (prise en charge uniquement pour le routage \$1connect) | route.request.querystring.PARAM\$1NAME |
| En-tête de demande (prise en charge uniquement pour le routage \$1connect) | route.request.header.PARAM\$1NAME |
| Chaîne de demande à plusieurs valeurs (prise en charge uniquement pour le routage \$1connect) | route.request.multivaluequerystring.PARAM\$1NAME |
| En-tête de demande à plusieurs valeurs (prise en charge uniquement pour le routage \$1connect) | route.request.multivalueheader.PARAM\$1NAME |
| Corps de la demande | route.request.body.JSONPath\$1EXPRESSION |
| Variables d’étape | stageVariables.VARIABLE\$1NAME |
| Variables de contexte | context.VARIABLE\$1NAME qui doit être l’une des [variables de contexte prises en charge](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Valeur statique | 'STATIC\$1VALUE'. STATIC\$1VALUEIl s'agit d'une chaîne littérale qui doit être placée entre guillemets simples. |
Lorsque vous créez un mappage de données, AWS CLI assurez-vous de suivre le format correct pour utiliser des littéraux avec des chaînes dans le AWS CLI. Pour plus d’informations, consultez [Using quotation marks and literals with strings in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html) dans le *Guide d’utilisateur AWS Command Line Interface *.
## Exemples
Les AWS CLI exemples suivants configurent les mappages de données. Pour un exemple CloudFormation de modèle, voir [samples/websocket-data-mapping.zip](samples/websocket-data-mapping.zip).
### Mapper ConnectionID d’un client à un en-tête dans une demande d’intégration
La commande [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) suivante mappe l’`connectionId` d’un client à un en-tête `connectionId` de la demande adressée à une intégration backend :
```
aws apigatewayv2 update-integration \
--integration-id abc123 \
--api-id a1b2c3d4 \
--request-parameters 'integration.request.header.connectionId'='context.connectionId'
```
### Mapper un paramètre de chaîne de demande à un en-tête dans une demande d’intégration
L’exemple suivant mappe un paramètre de chaîne de requête `authToken` à un en-tête `authToken` de la demande d’intégration.
1. Utilisez la commande [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) suivante pour ajouter le paramètre de chaîne de requête `authToken` aux paramètres de demande de la route.
```
aws apigatewayv2 update-route --route-id 0abcdef \
--api-id a1b2c3d4 \
--request-parameters '{"route.request.querystring.authToken": {"Required": false}}'
```
1. Utilisez la commande [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) suivante pour mapper le paramètre de chaîne de requête à l’en-tête `authToken` de la demande adressée à l’intégration backend.
```
aws apigatewayv2 update-integration \
--integration-id abc123 \
--api-id a1b2c3d4 \
--request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken'
```
1. (Facultatif) Si nécessaire, utilisez ce qui suit [delete-route-request-parameter](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-route-request-parameter.html)pour supprimer le paramètre de chaîne de `authToken` requête des paramètres de demande de l'itinéraire.
```
aws apigatewayv2 delete-route-request-parameter \
--route-id 0abcdef \
--api-id a1b2c3d4 \
--request-parameter-key 'route.request.querystring.authToken'
```
# WebSocket Référence du modèle de mappage d'API pour API Gateway
Cette section résume l'ensemble des variables actuellement prises en charge WebSocket APIs dans API Gateway.
| Paramètre | Description |
| --- | --- |
| \$1context.connectionId | ID unique pour la connexion qui peut être utilisé pour effectuer un rappel au client. |
| \$1context.connectedAt | Temps de connexion au format [Epoch](https://en.wikipedia.org/wiki/Unix_time). |
| \$1context.domainName | Nom de domaine pour l' WebSocket API. Ce nom peut être utilisé pour effectuer un rappel au client (au lieu d’une valeur codée en dur). |
| \$1context.eventType | Type d’événement : `CONNECT`, `MESSAGE` ou `DISCONNECT`. |
| \$1context.messageId | ID côté serveur unique pour un message. Uniquement disponible lorsque `$context.eventType` est défini sur `MESSAGE`. |
| \$1context.routeKey | Clé de routage sélectionnée. |
| \$1context.requestId | Identique à `$context.extendedRequestId`. |
| \$1context.extendedRequestId | ID généré automatiquement pour l’appel d’API, qui contient d’autres informations utiles pour le débogage et le dépannage. |
| \$1context.apiId | Identifiant qu’API Gateway attribue à votre API. |
| \$1context.authorizer.principalId | Identification de l’utilisateur principal associée au jeton envoyé par le client et retourné par une fonction Lambda du mécanisme d’autorisation Lambda API Gateway (anciennement appelé mécanisme d’autorisation personnalisée). |
| \$1context.authorizer.property | Valeur obtenue à l’aide de stringify de la paire clé-valeur spécifiée du mappage `context` renvoyé par une fonction du mécanisme d’autorisation Lambda API Gateway. Par exemple, si le mécanisme d’autorisation retourne le mappage `context` suivant : "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} l’appel de `$context.authorizer.key` renvoie la chaîne `"value"`, l’appel de `$context.authorizer.numKey` renvoie la chaîne `"1"` et l’appel de `$context.authorizer.boolKey` renvoie la chaîne `"true"`. |
| \$1context.error.messageString | Valeur entre guillemets de \$1context.error.message, à savoir "\$1context.error.message". |
| \$1context.error.validationErrorString | Chaîne contenant un message d’erreur de validation détaillé. |
| \$1context.identity.accountId | L'ID de AWS compte associé à la demande. |
| \$1context.identity.apiKey | Clé du propriétaire d’API associée à la demande d’API activée par clé. |
| \$1context.identity.apiKeyId | ID de clé du propriétaire d’API associée à la demande d’API activée par clé |
| \$1context.identity.caller | Identifiant principal de l’appelant effectuant la demande. |
| \$1context.identity.cognitoAuthenticationProvider | Liste séparée par des virgules de tous les fournisseurs d’authentification Amazon Cognito utilisés par l’appelant à l’origine de la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. Par exemple, pour une identité provenant d’un groupe d’utilisateurs Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Pour plus d’informations sur les fournisseurs d’authentification Amazon Cognito disponibles, consultez [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) dans le *Guide du développeur Amazon Cognito*. |
| \$1context.identity.cognitoAuthenticationType | Type d’authentification Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. Les valeurs possibles incluent `authenticated` pour les identités authentifiées et `unauthenticated` pour les identités non authentifiées. |
| \$1context.identity.cognitoIdentityId | ID d’identité Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | ID de groupe d’identités Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d'identification Amazon Cognito. |
| \$1context.identity.sourceIp | Adresse IP source de la connexion TCP envoyant la demande au point de terminaison de l’API Gateway. |
| \$1context.identity.user | Identifiant principal de l’utilisateur effectuant la demande. |
| \$1context.identity.userAgent | Agent utilisateur de l’appelant de l’API. |
| \$1context.identity.userArn | ARN (Amazon Resource Name) de l’utilisateur identifié après l’authentification. |
| \$1context.requestTime | Durée des demandes au format [CLF](https://httpd.apache.org/docs/current/logs.html#common) (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | Heure de la demande au format [Epoch](https://en.wikipedia.org/wiki/Unix_time), en millisecondes. |
| \$1context.stage | Étape de déploiement de l’appel d’API (par exemple, bêta ou production). |
| \$1context.status | Statut de la réponse. |
| \$1input.body | Renvoie la charge utile brute sous forme de chaîne. |
| \$1input.json(x) | Cette fonction évalue une JSONPath expression et renvoie les résultats sous forme de chaîne JSON. Par exemple, `$input.json('$.pets')` renvoie une chaîne JSON représentant la structure pets. Pour plus d'informations sur JSONPath, voir [JSONPath](https://goessner.net/articles/JsonPath/)ou [JSONPath pour Java](https://github.com/json-path/JsonPath). |
| \$1input.path(x) | Prend une chaîne JSONPath d'expression (`x`) et renvoie une représentation du résultat sous forme d'objet JSON. Cela vous permet d’accéder aux éléments de la charge utile et de les manipuler en mode natif en [langage VTL (Apache Velocity Template Language)](https://velocity.apache.org/engine/devel/vtl-reference.html). Par exemple, si l’expression `$input.path('$.pets')` renvoie un objet comme suit : [
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
`$input.path('$.pets').count()` renvoie `"3"`. Pour plus d'informations sur JSONPath, voir [JSONPath](http://goessner.net/articles/JsonPath/)ou [JSONPath pour Java](https://github.com/jayway/JsonPath). |
| \$1stageVariables. | **représente le nom d'une variable d'étape. |
| \$1stageVariables[''] | **représente n'importe quel nom de variable d'étape. |
| \$1\$1stageVariables['']\$1 | **représente n'importe quel nom de variable d'étape. |
| \$1util.escapeJavaScript() | Échape les caractères d'une chaîne en utilisant des règles de JavaScript chaîne. Cette fonction convertit tout guillemet simple (`'`) en guillemet d’échappement (`\'`). Cependant, les guillemets simples d’échappement ne sont pas valides en JSON. Par conséquent, lorsque la sortie de cette fonction est utilisée dans une propriété JSON, vous devez reconvertir les guillemets simples d’échappement (`\'`) en guillemets simples (`'`), comme illustré dans l’exemple suivant : $util.escapeJavaScript(data).replaceAll("\\'","'") |
| \$1util.parseJson() | Prend la chaîne JSON (obtenue à l’aide de stringify) et renvoie une représentation objet du résultat. Vous pouvez utiliser le résultat de cette fonction pour accéder aux éléments de la charge utile et les manipuler en mode natif en langage VTL (Apache Velocity Template Language). Par exemple, si vous avez la charge utile suivante : {"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"} et utilisez le modèle de mappage suivant : #set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
"errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
vous obtenez la sortie suivante : {
"errorMessageObjKey2ArrVal" : 1
}
|
| \$1util.urlEncode() | Convertit une chaîne au format « application/ x-www-form-urlencoded ». |
| \$1util.urlDecode() | Décode une chaîne « application/ x-www-form-urlencoded ». |
| \$1util.base64Encode() | Encode les données dans une chaîne encodée en base64. |
| \$1util.base64Decode() | Décode les données d’une chaîne encodée en base64. |
# Types de supports binaires pour les API WebSocket dans API Gateway
Les API WebSocket d’API Gateway ne prennent actuellement pas en charge les trames binaires dans les charges utiles des messages entrants. Si une application client envoie une trame binaire, API Gateway la rejette et déconnecte le client avec le code 1003.
Il existe une solution pour contourner ce comportement. Si le client envoie des données binaires encodées au format texte (par exemple, base64) en tant que trame de texte, vous pouvez définir la propriété `contentHandlingStrategy` de l’intégration sur `CONVERT_TO_BINARY` pour convertir la charge utile de la chaîne encodée en base64 au format binaire.
Pour renvoyer une réponse de routage pour une charge utile binaire dans des intégrations autres que de proxy, vous pouvez définir la propriété `contentHandlingStrategy` de la réponse d’intégration sur `CONVERT_TO_TEXT` pour convertir la charge utile du format binaire en chaîne encodée en base64.
# Invoquer WebSocket APIs
Une fois que vous avez déployé votre WebSocket API, les applications clientes peuvent s'y connecter et lui envoyer des messages, et votre service principal peut envoyer des messages aux applications clientes connectées :
+ Vous pouvez l'utiliser `wscat` pour vous connecter à votre WebSocket API et lui envoyer des messages afin de simuler le comportement du client. Voir [`wscat`À utiliser pour se connecter à une WebSocket API et y envoyer des messages](apigateway-how-to-call-websocket-api-wscat.md).
+ Vous pouvez utiliser l’API @connections à partir de votre service backend pour envoyer un message de rappel à un client connecté, obtenir des informations de connexion ou déconnecter le client. Voir [Utilisation des commandes `@connections` dans votre service backend](apigateway-how-to-call-websocket-api-connections.md).
+ Une application cliente peut utiliser sa propre WebSocket bibliothèque pour appeler votre WebSocket API.
# `wscat`À utiliser pour se connecter à une WebSocket API et y envoyer des messages
Cet `[wscat](https://www.npmjs.com/package/wscat)` utilitaire est un outil pratique pour tester une WebSocket API que vous avez créée et déployée dans API Gateway. Vous pouvez installer et utiliser `wscat` comme suit :
1. Téléchargez `wscat` depuis [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat).
1. Installez `wscat` en exécutant les commandes suivantes.
```
npm install -g wscat
```
1. Pour vous connecter à votre API, exécutez la commande `wscat` comme illustré dans l’exemple suivant. Notez que cet exemple part du principe que le paramètre `Authorization` est défini sur `NONE`.
```
wscat -c wss://aabbccddee.execute-api.us-east-1.amazonaws.com/test/
```
Vous devez remplacer `aabbccddee` par l’ID réel de l’API qui est affiché dans la console API Gateway ou renvoyé par la commande [https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) de l’ AWS CLI .
En outre, si votre API se trouve dans une région autre que `us-east-1`, vous devez remplacer la région par la région correcte.
1. Pour tester votre API, entrez un message tel que le suivant une fois connecté :
```
{"{jsonpath-expression}":"{route-key}"}
```
où *\$1jsonpath-expression\$1* est une JSONPath expression et *\$1route-key\$1* une clé de route pour l'API. Par exemple :
```
{"action":"action1"}
{"message":"test response body"}
```
Pour plus d'informations sur JSONPath, voir [JSONPath](https://goessner.net/articles/JsonPath/)ou [JSONPath pour Java](https://github.com/json-path/JsonPath).
1. Pour vous déconnecter de votre API, entrez `ctrl-C`.
# Utilisation des commandes `@connections` dans votre service backend
Votre service principal peut utiliser les requêtes HTTP de WebSocket connexion suivantes pour envoyer un message de rappel à un client connecté, obtenir des informations de connexion ou déconnecter le client.
**Important**
Ces demandes utilisent l’[autorisation IAM](apigateway-websocket-control-access-iam.md). Vous devez donc les signer avec [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). Pour ce faire, vous pouvez utiliser l’API de gestion API Gateway. Pour de plus amples informations, veuillez consulter [ApiGatewayManagementApi](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigatewaymanagementapi.html).
Dans la commande suivante, vous devez le `{api-id}` remplacer par l'identifiant d'API réel, qui est affiché dans la console API Gateway ou renvoyé par la commande AWS CLI [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html). Vous devez établir la connexion avant d’utiliser cette commande.
Pour envoyer un message de rappel au client, utilisez :
```
POST https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Vous pouvez tester cette demande en utilisant `[Postman](https://www.postman.com/)` ou en appelant `[awscurl](https://github.com/okigan/awscurl)` comme dans l’exemple suivant :
```
awscurl --service execute-api -X POST -d "hello world" https://{prefix}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Vous avez besoin de coder la commande en URL comme dans l’exemple suivant :
```
awscurl --service execute-api -X POST -d "hello world" https://aabbccddee.execute-api.us-east-1.amazonaws.com/prod/%40connections/R0oXAdfD0kwCH6w%3D
```
Pour obtenir le dernier état de connexion du client, utilisez :
```
GET https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Pour déconnecter le client, utilisez :
```
DELETE https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Vous pouvez générer dynamiquement une URL de rappel en utilisant les variables `$context` dans votre intégration. Par exemple, si vous utilisez l’intégration de proxy Lambda avec une fonction Lambda `Node.js`, vous pouvez générer l’URL et envoyer un message à un client connecté comme suit :
```
import {
ApiGatewayManagementApiClient,
PostToConnectionCommand,
} from "@aws-sdk/client-apigatewaymanagementapi";
export const handler = async (event) => {
const domain = event.requestContext.domainName;
const stage = event.requestContext.stage;
const connectionId = event.requestContext.connectionId;
const callbackUrl = `https://${domain}/${stage}`;
const client = new ApiGatewayManagementApiClient({ endpoint: callbackUrl });
const requestParams = {
ConnectionId: connectionId,
Data: "Hello!",
};
const command = new PostToConnectionCommand(requestParams);
try {
await client.send(command);
} catch (error) {
console.log(error);
}
return {
statusCode: 200,
};
};
```
Si vous utilisez un nom de domaine personnalisé pour votre WebSocket API, supprimez la `stage` variable de votre code de fonction.
Lorsque vous envoyez un message de rappel, votre fonction Lambda doit être autorisée à appeler l’API de gestion d’API Gateway. Vous pouvez recevoir un message d’erreur contenant `GoneException` si vous publiez un message avant l’établissement de la connexion ou après la déconnexion du client.
# Publication d’API WebSocket invocables par les clients
Le simple fait de créer et le développer une API API Gateway ne la rend pas automatiquement appelable par vos utilisateurs. Pour la rendre appelable, vous devez déployer votre API dans une étape. En outre, vous pouvez personnaliser l’URL que vos utilisateurs utiliseront pour accéder à votre API. Vous pouvez lui attribuer un domaine cohérent avec votre marque ou plus facilement mémorisable que l’URL par défaut de votre API.
Dans cette section, vous pouvez apprendre à déployer votre API et à personnaliser l’URL que vous fournissez aux utilisateurs pour y accéder.
**Note**
Pour renforcer la sécurité de vos API API Gateway, le domaine `execute-api.{region}.amazonaws.com` est enregistré dans la [liste des suffixes publics (PSL](https://publicsuffix.org/)). Pour plus de sécurité, nous vous recommandons d’utiliser des cookies avec un préfixe `__Host-` si vous devez définir des cookies sensibles dans le nom de domaine par défaut de vos API API Gateway. Cette pratique vous aidera à protéger votre domaine contre les tentatives de falsification de requêtes intersites (CSRF). Pour plus d’informations, consultez la page [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) du Mozilla Developer Network.
**Topics**
+ [Création d'étapes pour WebSocket APIs in API Gateway](websocket-api-stages.md)
+ [Déploiement WebSocket APIs dans API Gateway](apigateway-set-up-websocket-deployment.md)
+ [Politique de sécurité pour WebSocket APIs in API Gateway](websocket-api-ciphers.md)
+ [Noms de domaine personnalisés pour les API WebSocket dans API Gateway](websocket-api-custom-domain-names.md)
# Création d'étapes pour WebSocket APIs in API Gateway
Une étape d’API est une référence logique à un état du cycle de vie de votre API (par exemple, `dev`, `prod`, `beta` ou `v2`). Les étapes API sont identifiées par leur ID d’API et leur nom d’étape, et elles sont incluses dans l’URL que vous utilisez pour appeler l’API. Chaque étape est une référence nommée à un déploiement de l’API et elle est mise à la disposition des applications clientes à appeler.
Un déploiement est un instantané de la configuration de votre API. Après que vous avez déployé une API dans une étape, les clients peuvent l’appeler. Vous devez déployer une API pour que les modifications prennent effet.
## Variables d’étape
Les variables d'étape sont des paires clé-valeur que vous pouvez définir pour une étape d'une WebSocket API. Elles se comportent comme les variables d’environnement et peuvent être utilisées dans votre configuration d’API.
Par exemple, vous pouvez définir une variable d’étape, puis définir sa valeur en tant que point de terminaison HTTP pour une intégration de proxy HTTP. Par la suite, vous pouvez référencer le point de terminaison à l’aide du nom de la variable d’étape associée. Ce faisant, vous pouvez utiliser la même configuration d’API avec un point de terminaison différent à chaque étape. De même, vous pouvez utiliser des variables d'étape pour spécifier une intégration de AWS Lambda fonction différente pour chaque étape de votre API.
**Note**
Les variables d’étape ne sont pas destinées à être utilisées pour des données sensibles, telles que les informations d’identification. Pour transmettre des données sensibles aux intégrations, utilisez un AWS Lambda autorisateur. Vous pouvez transmettre des données sensibles aux intégrations dans la sortie du mécanisme d’autorisation Lambda. Pour en savoir plus, consultez la section [Format de réponse du mécanisme d’autorisation Lambda](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response).
### Exemples
Pour utiliser une variable d’étape afin de personnaliser le point de terminaison d’intégration HTTP, vous devez d’abord définir le nom et la valeur de la variable stage (par exemple, `url`) avec la valeur `example.com`. Ensuite, configurez une intégration de proxy HTTP. Au lieu d’entrer l’URL du point de terminaison, vous pouvez demander à API Gateway d’utiliser la valeur de la variable d’étape, **http://\$1\$1stageVariables.url\$1**. Cette valeur demande à API Gateway de remplacer votre variable d’étape `${}` au moment de l’exécution, en fonction de l’étape à laquelle se trouve votre API.
Vous pouvez référencer les variables d'étape de la même manière pour spécifier un nom de fonction Lambda ou un AWS ARN de rôle.
Lorsque vous spécifiez un nom de fonction Lambda en tant que valeur de variable d’étape, vous devez configurer les autorisations sur cette fonction Lambda manuellement. La commande [add permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) suivante ajoute les autorisations requises :
```
aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
## Référence des variables d’étape API Gateway
### Intégration HTTP URIs
Une variable d’étape peut être utilisée dans une URI d’intégration HTTP, comme illustré dans les exemples suivants.
+ URI complet sans protocole – `http://${stageVariables.}`
+ Domaine complet – `http://${stageVariables.}/resource/operation`
+ Sous-domaine – `http://${stageVariables.}.example.com/resource/operation`
+ Chemin – `http://example.com/${stageVariables.}/bar`
+ Chaîne de requête – `http://example.com/foo?q=${stageVariables.}`
### Fonctions Lambda
Vous pouvez utiliser une variable d’étape à la place d’un nom de fonction Lambda ou d’un alias, comme illustré dans les exemples suivants.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**Note**
Pour utiliser une variable d’étape pour une fonction Lambda, la fonction doit se trouver dans le même compte que l’API. Les variables d’étape ne prennent pas en charge les fonctions Lambda inter-comptes.
### AWS informations d'identification d'intégration
Vous pouvez utiliser une variable d'étape dans le cadre de l'ARN d'identification AWS d'un utilisateur ou d'un rôle, comme illustré dans l'exemple suivant.
+ `arn:aws:iam:::${stageVariables.}`
# Déploiement WebSocket APIs dans API Gateway
Après avoir créé votre WebSocket API, vous devez la déployer pour que vos utilisateurs puissent l'invoquer.
Pour déployer une API, vous devez créer un [déploiement d’API](api-gateway-basic-concept.md#apigateway-definition-api-deployment) et l’associer à une [étape](api-gateway-basic-concept.md#apigateway-definition-api-stage). Chaque étape est un instantané de l’API et peut être appelée par les applications client.
**Important**
Chaque fois que vous mettez à jour une API, vous devez la redéployer. Les modifications apportées à tout autre élément que les paramètres d’étape nécessitent un redéploiement, notamment des modifications des ressources suivantes :
Routes
Intégrations
Mécanismes d’autorisation
Par défaut, vous êtes limité à 10 étapes pour chaque API. Nous recommandons de réutiliser les étapes pour vos déploiements.
Pour appeler une WebSocket API déployée, le client envoie un message à l'URL de l'API. L’URL est déterminée par le nom d’hôte et le nom de l’étape de l’API.
**Note**
API Gateway prend en charge des charges utiles jusqu’à 128 Ko, avec une taille de trame maximale de 32 Ko. Si un message dépasse 32 Ko, il devra être scindé en plusieurs trames, chacune de 32 Ko ou moins.
En utilisant le nom de domaine par défaut de l'API, l'URL (par exemple) d'une WebSocket API dans une étape donnée (`{stageName}`) est au format suivant :
```
wss://{api-id}.execute-api.{region}.amazonaws.com/{stageName}
```
Pour rendre l'URL de l' WebSocket API plus conviviale, vous pouvez créer un nom de domaine personnalisé (par exemple,`api.example.com`) pour remplacer le nom d'hôte par défaut de l'API. Le processus de configuration est le même que pour REST APIs. Pour de plus amples informations, veuillez consulter [Nom de domaine personnalisé pour le REST public APIs dans API Gateway](how-to-custom-domains.md).
Les étapes permettent un contrôle de version solide de votre API. Par exemple, vous pouvez déployer une API dans une étape `test` et une étape `prod`, puis utiliser l’étape `test` comme version de test et l’étape `prod` comme version stable. Une fois que les mises à jour passent le test, vous pouvez migrer l’étape `test` vers l’étape `prod`. La promotion peut être effectuée en redéployant l’API à l’étape `prod`. Pour plus d’informations sur les étapes, consultez [Configuration d’une étape pour une API REST dans API Gateway](set-up-stages.md).
**Topics**
+ [Créez un déploiement d' WebSocket API à l'aide du AWS CLI](#apigateway-create-websocket-deployment-using-awscli)
+ [Création d'un déploiement d' WebSocket API à l'aide de la console API Gateway](#apigateway-create-websocket-deployment-using-console)
## Créez un déploiement d' WebSocket API à l'aide du AWS CLI
La commande [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) suivante crée un déploiement :
```
aws apigatewayv2 --region us-east-1 create-deployment --api-id aabbccddee
```
Le résultat se présente comme suit :
```
{
"DeploymentId": "fedcba",
"DeploymentStatus": "DEPLOYED",
"CreatedDate": "2018-11-15T06:49:09Z"
}
```
L’API déployée ne peut pas être appelée tant que vous n’associez pas le déploiement à une étape. Vous pouvez créer une nouvelle étape ou réutiliser une étape créée précédemment.
La commande [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-stage.html) suivante crée une étape et l’associe au déploiement :
```
aws apigatewayv2 --region us-east-1 create-stage --api-id aabbccddee --deployment-id fedcba --stage-name test
```
Le résultat se présente comme suit :
```
{
"StageName": "test",
"CreatedDate": "2018-11-15T06:50:28Z",
"DeploymentId": "fedcba",
"DefaultRouteSettings": {
"MetricsEnabled": false,
"ThrottlingBurstLimit": 5000,
"DataTraceEnabled": false,
"ThrottlingRateLimit": 10000.0
},
"LastUpdatedDate": "2018-11-15T06:50:28Z",
"StageVariables": {},
"RouteSettings": {}
}
```
Vous pouvez également réutiliser une étape existante en mettant à jour la `deploymentId` propriété de l'étape avec le nouvel ID de déploiement (*deployment-id*). La commande [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) suivante met à jour l’ID de déploiement de l’étape :
```
aws apigatewayv2 update-stage --region region \
--api-id api-id \
--stage-name stage-name \
--deployment-id deployment-id
```
## Création d'un déploiement d' WebSocket API à l'aide de la console API Gateway
Pour utiliser la console API Gateway afin de créer un déploiement pour une WebSocket API :
1. Connectez-vous à la console API Gateway et choisissez l’API.
1. Sélectionnez **Deploy API (Déployer une API)**.
1. Choisissez l’étape souhaitée dans la liste déroulante ou saisissez le nom d’une nouvelle étape.
# Politique de sécurité pour WebSocket APIs in API Gateway
API Gateway applique une politique de sécurité `TLS_1_2` pour tous les points de terminaison de WebSocket l'API.
Une *politique de sécurité* est une combinaison prédéfinie d’une version minimale du protocole TLS et de suites de chiffrement offerte par Amazon API Gateway. Le protocole TLS résout les problèmes de sécurité de réseau tels que la falsification et le risque d’écoute illicite entre un client et un serveur. Lorsque vos clients établissent une liaison TLS vers votre API via le domaine personnalisé, la politique de sécurité applique les options de version TLS et de suite de chiffrement que vos clients peuvent choisir d’utiliser. Cette politique de sécurité accepte le trafic TLS 1.2 et TLS 1.3 et rejette le trafic TLS 1.0.
## Protocoles et chiffrements TLS pris en charge pour WebSocket APIs
Le tableau suivant décrit les protocoles TLS pris en charge pour WebSocket APIs.
| **Protocoles TLS** | **Politique de sécurité TLS\$11\$12** |
| --- | --- |
| TLSv13. | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| TLSv12. | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
Le tableau suivant décrit les chiffrements TLS disponibles pour la politique de sécurité TLS 1\$12 pour. WebSocket APIs
| **Chiffrements TLS** | **Politique de sécurité TLS\$11\$12** |
| --- | --- |
| TLS\$1AES\$1128\$1GCM\$1 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| TLS\$1AES\$1256\$1GCM\$1 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| TLS\$1 \$1 \$1 CHACHA20 POLY1305 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-ECDSA- -GCM- AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-RSA- -GCM- AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-ECDSA- - AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-RSA- - AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-ECDSA- -GCM- AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-RSA- -GCM- AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-ECDSA- - AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-RSA- - AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| AES128-GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| AES256-GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
## Noms de chiffrement OpenSSL et RFC
OpenSSL et IETF RFC 5246 utilisent des noms différents pour les mêmes chiffrements. Pour obtenir la liste des noms de chiffrement, consultez [Noms de chiffrement OpenSSL et RFC](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names).
## Informations sur REST APIs et HTTP APIs
Pour plus d'informations sur REST APIs et HTTP APIs, consultez [Choisissez une politique de sécurité pour votre domaine personnalisé dans API Gateway](apigateway-custom-domain-tls-version.md) et[Politique de sécurité pour le protocole HTTP APIs dans API Gateway](http-api-ciphers.md).
# Noms de domaine personnalisés pour les API WebSocket dans API Gateway
Les *noms de domaine personnalisés* sont des URL plus simples et plus intuitives que vous pouvez fournir à vos utilisateurs d’API.
Après avoir déployé votre API, vous (et vos clients) pouvez appeler cette API à l’aide de l’URL de base par défaut au format suivant :
```
https://api-id.execute-api.region.amazonaws.com/stage
```
où *api-id* est généré par API Gateway, *region* est la région AWS et *stage* est spécifié par vous lors du déploiement de l’API.
La partie nom d’hôte de l’URL, `api-id.execute-api.region.amazonaws.com`, fait référence à un point de terminaison de l’API. Le nom par défaut du point de terminaison de l’API est généré de manière aléatoire, difficile à mémoriser et peu convivial.
Avec des noms de domaine personnalisés, vous pouvez configurer le nom d’hôte de votre API et choisir un chemin de base (par exemple, `myservice`) pour mapper l’URL alternative à votre API. Par exemple, une URL de base de l’API plus conviviale peut devenir :
```
https://api.example.com/myservice
```
## Considérations
Les considérations suivantes peuvent avoir une incidence sur votre utilisation d’un nom de domaine personnalisé.
+ Si vous mappez un nom de domaine personnalisé à une API WebSocket, vous ne pouvez pas le mapper à une API REST ou à une API HTTP.
+ Seuls les noms de domaine personnalisés régionaux sont pris en charge.
+ Pour la version TLS minimale, seule la version TLS 1.2 est prise en charge.
+ Vous devez créer ou mettre à jour l’enregistrement de ressource de votre fournisseur DNS pour le mapper au point de terminaison de votre API. Sans ce mappage, les demandes d’API destinées au nom de domaine personnalisé ne peuvent pas atteindre API Gateway.
+ Vous pouvez prendre en charge un nombre presque infini de noms de domaine sans dépasser le quota par défaut en utilisant un certificat générique. Pour de plus amples informations, consultez [Noms de domaine personnalisés génériques](http-api-custom-domain-names.md#http-wildcard-custom-domain-names).
## Prérequis
Les conditions suivantes sont requises pour créer un nom de domaine personnalisé.
### Enregistrement d’un nom de domaine
Pour pouvoir configurer des noms de domaine personnalisés pour vos API, vous devez avoir enregistré un nom de domaine Internet. Vous pouvez enregistrer votre nom de domaine Internet avec [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) ou utiliser un bureau d’enregistrement de domaine tiers de votre choix. Votre nom de domaine personnalisé peut être le nom d’un sous-domaine ou le domaine racine (également nommé « zone apex ») d’un domaine Internet enregistré.
Votre nom de domaine doit respecter la spécification [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) et peut comporter un maximum de 63 octets par étiquette et 255 octets au total.
### Certificats pour les noms de domaine personnalisés
Avant de configurer un nom de domaine personnalisé pour une API, vous devez avoir un certificat SSL/TLS prêt dans ACM. Si ACM n’est pas disponible dans la région AWS où vous créez votre nom de domaine personnalisé, vous devez importer un certificat dans API Gateway dans cette région.
Pour importer un certificat SSL/TLS, vous devez fournir le corps du certificat SSL/TLS au format PEM, sa clé privée, ainsi que la chaîne de certificats du nom de domaine personnalisé.
Chaque certificat stocké dans ACM est identifié par son ARN. Avec les certificats émis par ACM, vous n’avez pas à vous inquiéter d’une éventuelle exposition des informations sensibles du certificat, par exemple sa clé privée. Pour utiliser un certificat géré par AWS pour un nom de domaine, indiquez simplement son ARN.
Si votre application utilise l’épinglage de certificat, parfois appelé épinglage SSL, pour épingler un certificat ACM, l’application ne pourra peut-être pas se connecter à votre domaine une fois qu’AWS aura renouvelé le certificat. Pour plus d’informations, consultez la section [Problèmes d’épinglage de certificat](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) dans le *Guide de l’utilisateur AWS Certificate Manager*.
## Noms de domaine personnalisés génériques
Avec les noms de domaine personnalisés génériques, vous pouvez prendre en charge un nombre presque infini de noms de domaine sans dépasser le [quota par défaut](limits.md). Par exemple, vous pouvez donner à chacun de vos clients son propre nom de domaine, `customername.api.example.com`.
Pour créer un nom de domaine personnalisé générique, vous pouvez spécifier un caractère générique (`*`) comme premier sous-domaine d’un domaine personnalisé qui représente tous les sous-domaines possibles d’un domaine racine.
Par exemple, le nom de domaine personnalisé générique `*.example.com` se traduit par des sous-domaines tels que `a.example.com`, `b.example.com` et `c.example.com`, qui effectuent tous un routage vers le même domaine.
Les noms de domaine personnalisés génériques prennent en charge des configurations distinctes des noms de domaine personnalisés standard d’API Gateway. Par exemple, dans un seul compte AWS, vous pouvez configurer `*.example.com` et `a.example.com` pour qu’ils se comportent différemment.
Vous pouvez utiliser les variables de contexte `$context.domainName` et `$context.domainPrefix` pour déterminer le nom de domaine utilisé par un client pour appeler votre API. Pour en savoir plus sur les variables de contexte, consultez [Variables pour les transformations de données pour API Gateway](api-gateway-mapping-template-reference.md).
Pour créer un nom de domaine personnalisé générique, vous devez fournir un certificat émis par ACM qui a été validé à l’aide du DNS ou de la méthode de validation par e-mail.
**Note**
Vous ne pouvez pas créer un nom de domaine personnalisé générique si un autre compte AWS a créé un nom de domaine personnalisé en conflit avec ce nom. Par exemple, si le compte A a créé `a.example.com`, le compte B ne peut pas créer le nom de domaine personnalisé générique `*.example.com`.
Si les comptes A et B ont le même propriétaire, vous pouvez contacter le [AWSCentre de support](https://console.aws.amazon.com/support/home#/) pour demander une exception.
## Étapes suivantes pour les noms de domaine personnalisés
Pour configurer un nom de domaine personnalisé pour une API HTTP, utilisez la documentation de la section API REST du Guide du développeur API Gateway.
D’abord, spécifiez un certificat pour votre nom de domaine personnalisé. Pour de plus amples informations, consultez [Préparez les certificats dans AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Ensuite, créez un nom de domaine personnalisé régional. Pour de plus amples informations, consultez [Configuration d’un nom de domaine personnalisé régional dans API Gateway](apigateway-regional-api-custom-domain-create.md).
# Mappage des étapes d’API à un nom de domaine personnalisé pour les API WebSocket
Les mappages d’API vous permettent de connecter des étapes d’API à un nom de domaine personnalisé. Après avoir créé un nom de domaine et configuré les enregistrements DNS, vous pouvez utiliser les mappages d’API pour envoyer le trafic vers vos API via votre nom de domaine personnalisé.
Un mappage d’API spécifie une API, une étape et éventuellement un chemin à utiliser pour le mappage. Par exemple, vous pouvez mapper l’étape `production` d’une API à `wss://api.example.com/orders`.
Avant de créer un mappage d’API, vous devez disposer d’une API, d’une étape et d’un nom de domaine personnalisé. Pour plus d’informations sur la création d’un nom de domaine personnalisé, consultez [Configuration d’un nom de domaine personnalisé régional dans API Gateway](apigateway-regional-api-custom-domain-create.md).
## Restrictions
+ Dans un mappage d’API, le nom de domaine personnalisé et les API mappées doivent se trouver sur le même compte AWS.
+ Les mappages d’API ne doivent contenir que des lettres, des chiffres et les caractères suivants : `$-_.+!*'()`.
+ La longueur maximale du chemin d’un mappage d’API est de 300 caractères.
+ Vous ne pouvez pas mapper les API WebSocket au même nom de domaine personnalisé qu’une API HTTP ou une API REST.
+ Si vous créez un mappage d’API à plusieurs niveaux, API Gateway convertit tous les noms d’en-tête en minuscules.
## Création d’un mappage d’API
Pour créer un mappage d’API, vous devez d’abord créer un nom de domaine personnalisé, une API et une étape. Pour plus d’informations sur la création d’un nom de domaine personnalisé, consultez [Configuration d’un nom de domaine personnalisé régional dans API Gateway](apigateway-regional-api-custom-domain-create.md).
------
#### [ AWS Management Console ]
**Pour créer un mappage d’API**
1. Connectez-vous à la console API Gateway à l’adresse : [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choisissez **Noms de domaine personnalisés**.
1. Sélectionnez un nom de domaine personnalisé que vous avez déjà créé.
1. Choisissez **Mappages d’API**.
1. Choisissez **Configurer les mappages d’API**.
1. Choisissez **Ajouter un nouveau mappage**.
1. Entrez une **API**, une **Étape** et, éventuellement, un **Chemin d’accès**.
1. Choisissez **Save (Enregistrer)**.
------
#### [ AWS CLI ]
La commande [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) suivante crée un mappage d’API. Dans cet exemple, API Gateway envoie des demandes `api.example.com/v1` à l’API et à l’étape spécifiés.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1 \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
L’exemple CloudFormation suivant crée un mappage d’API.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'v1'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# Types d’adresses IP des noms de domaine personnalisés pour les API WebSocket
Lorsque vous créez un domaine personnalisé, vous devez spécifier le type d’adresse IP pouvant invoquer votre domaine. Vous avez le choix entre IPv4 (pour autoriser les adresses IPv4 à invoquer votre domaine) et Dualstack (pour autoriser les adresses IPv4 et IPv6 à invoquer votre domaine). Nous vous recommandons de définir le type d’adresse IP sur Dualstack pour éviter l’épuisement de l’espace IP ou renforcer votre niveau de sécurité. Pour plus d’informations sur les avantages d’un type d’adresse IP à double pile, consultez [IPv6 sur AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Considérations relatives aux types d’adresses IP
Les considérations suivantes peuvent avoir une incidence sur votre utilisation des types d’adresses IP.
+ Le type d’adresse IP par défaut des noms de domaine personnalisés API Gateway est IPv4.
+ Il n’est pas nécessaire que votre nom de domaine personnalisé possède le même type d’adresse IP pour toutes les API qui y sont mappées. La désactivation du point de terminaison de votre API par défaut peut avoir une incidence sur la manière dont les appelants peuvent invoquer votre API.
## Modification du type d’adresse IP d’un nom de domaine personnalisé
Vous pouvez modifier le type d’adresse IP en mettant à jour la configuration de point de terminaison du nom de domaine. Vous pouvez mettre à jour la configuration du point de terminaison à l’aide de la AWS Management Console, de l’AWS CLI, d’CloudFormation ou d’un kit SDK AWS.
------
#### [ AWS Management Console ]
**Pour modifier le type d’adresse IP d’un nom de domaine personnalisé**
1. Connectez-vous à la console API Gateway à l’adresse : [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choisissez un nom de domaine personnalisé public.
1. Sélectionnez **Configuration du point de terminaison**.
1. Pour Type d’adresse IP, choisissez **IPv4** ou **Dualstack**.
1. Choisissez **Save (Enregistrer)**.
------
#### [ AWS CLI ]
La commande [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) suivante met à jour une API pour qu’elle possède le type d’adresse IP Dualstack :
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
Le résultat se présente comme suit :
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------
# Désactiver le point de terminaison par défaut pour WebSocket APIs
Par défaut, les clients peuvent appeler votre API en utilisant le point de terminaison `execute-api` généré par API Gateway pour votre API. Pour vous assurer que les clients peuvent accéder à votre API en utilisant uniquement un nom de domaine personnalisé, désactivez le point de terminaison par défaut `execute-api`. Lorsque vous désactivez le point de terminaison par défaut, toutes les étapes d’une API sont affectées.
La procédure suivante montre comment désactiver le point de terminaison par défaut pour une WebSocket API.
------
#### [ AWS Management Console ]
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une WebSocket API.
1. Choisissez **Paramètres de l’API**.
1. Dans l’onglet **Détails de l’API**, choisissez **Modifier**.
1. Pour **Point de terminaison par défaut**, sélectionnez **Inactif**.
1. Sélectionnez **Enregistrer les modifications**.
1. Dans le volet de navigation principal, sélectionnez **Routes**.
1. Choisissez **Déployer**, puis redéployez votre API ou créez une étape pour que la modification prenne effet.
------
#### [ AWS CLI ]
La commande [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) suivante désactive le point de terminaison par défaut d'une API : WebSocket
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
Après avoir désactivé le point de terminaison par défaut, vous devez déployer votre API pour que la modification prenne effet.
La AWS CLI commande suivante crée un déploiement.
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# Protégez votre WebSocket APIs API Gateway
API Gateway fournit un certain nombre de façons de protéger votre API contre certaines menaces, comme les utilisateurs malveillants ou les pics de trafic. Vous pouvez protéger votre API à l’aide de stratégies telles que la génération de certificats SSL ou la définition de limitations. Pour plus d’informations sur la génération de certificats SSL, consultez [Génération et configuration d’un certificat SSL pour l’authentification backend dans API Gateway](getting-started-client-side-ssl-authentication.md). Le reste de cette section porte sur la définition de limitations.
Vous pouvez configurer la régulation pour éviter qu'ils ne soient submergés par un trop grand nombre de demandes. APIs Les limitations sont appliquées dans la mesure du possible et doivent être considérées comme des cibles plutôt que des plafonds de demandes garantis.
API Gateway régule les demandes de limitations soumises à votre API à l’aide de l’algorithme de compartiment de jetons, où un jeton compte pour une demande. Plus précisément, API Gateway examine le taux et le nombre de demandes soumises par rapport APIs à l'ensemble de votre compte, par région. Dans l’algorithme de compartiment de jetons, une rafale peut permettre un dépassement prédéfini de ces limites, mais d’autres facteurs peuvent également entraîner le dépassement des limites dans certains cas.
Lorsque les soumissions de demandes dépassent les limites de taux régulier et en mode rafale des demandes, API Gateway commence à limiter les demandes. Les clients peuvent recevoir des réponses aux erreurs `429 Too Many Requests` à ce stade. Lors de la capture de ces exceptions, le client peut renvoyer les demandes en échec de façon à limiter le débit tout en respectant les limitations.
En tant que développeur d'API, vous pouvez définir les limites cibles pour les différentes étapes ou itinéraires d'API afin d'améliorer les APIs performances globales de l'ensemble de votre compte.
## Limitation au niveau du compte par région
Par défaut, API Gateway limite le nombre de demandes stables par seconde (RPS) sur l'ensemble APIs d'un AWS compte, par région. Cela limite également la rafale (c'est-à-dire la taille maximale du bucket) sur l'ensemble APIs du AWS compte, par région. Dans API Gateway, la limite en mode rafale correspond au nombre maximal d’envois de demandes simultanés qu’API Gateway peut traiter à tout moment sans renvoyer de réponses d’erreur `429 Too Many Requests`. Pour plus d’informations sur les quotas de limitation, consultez [Quotas Amazon API Gateway](limits.md).
Les limites par compte sont appliquées à tous les APIs membres d'un compte dans une région spécifiée. La limite de débit au niveau du compte peut être augmentée sur demande. Des limites plus élevées sont possibles avec APIs des délais d'attente plus courts et des charges utiles plus faibles. Pour demander une augmentation des limitations au niveau du compte par Région, contactez le [Centre de support AWS](https://console.aws.amazon.com/support/home#/). Pour de plus amples informations, veuillez consulter [Quotas Amazon API Gateway](limits.md). Notez que ces limites ne peuvent pas être supérieures aux limites d' AWS étranglement.
## Limitation au niveau de l’acheminement
Vous pouvez définir une limitation au niveau des acheminements, afin de remplacer les limitations de requêtes au niveau du compte pour une étape spécifique ou pour des acheminements particuliers de votre API. Les limites de limitation d’acheminement par défaut ne peuvent pas dépasser les limites de débit au niveau du compte.
Vous pouvez configurer la limitation au niveau des acheminements à l’aide de AWS CLI. La commande [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) suivante configure une limitation personnalisée pour l’étape et la route spécifiées d’une API :
```
aws apigatewayv2 update-stage \
--api-id a1b2c3d4 \
--stage-name dev \
--route-settings '{"messages":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'
```
# Surveillance des API WebSocket dans API Gateway
Vous pouvez utiliser les métriques CloudWatch et CloudWatch Logs pour surveiller les API WebSocket. En combinant les journaux et les métriques, vous pouvez enregistrer les erreurs et surveiller les performances de votre API.
**Note**
API Gateway peut ne pas générer de journaux et de métriques dans les cas suivants :
Nombre d’erreurs de demande d’entité 413 trop important
Nombre d’erreurs de demande 429 trop important
Erreurs de la série 400 provenant de demandes envoyées à un domaine personnalisé qui n’a pas de mappage d’API
Erreurs de la série 500 causées par des défaillances internes
**Topics**
+ [Surveillez WebSocket l'exécution des API à l'aide de CloudWatch métriques](apigateway-websocket-api-logging.md)
+ [Configuration de la journalisation WebSocket APIs dans API Gateway](websocket-api-logging.md)
# Surveillez WebSocket l'exécution des API à l'aide de CloudWatch métriques
Vous pouvez utiliser les CloudWatch métriques [Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) pour effectuer un suivi WebSocket APIs. La configuration est similaire à celle utilisée pour REST APIs. Pour de plus amples informations, veuillez consulter [Surveillez l'exécution de l'API REST avec CloudWatch les métriques Amazon](monitoring-cloudwatch.md).
Les mesures suivantes sont prises en charge pour WebSocket APIs :
| Métrique | Description |
| --- | --- |
| ConnectCount | Nombre de messages envoyés à l’intégration de route \$1connect. |
| MessageCount | Le nombre de messages envoyés à l' WebSocket API, depuis ou vers le client. |
| IntegrationError | Nombre de demandes qui renvoient une réponse 4XX/5XX depuis l’intégration. |
| ClientError | Nombre de demandes pour lesquelles API Gateway renvoie une réponse 4XX avant l’invocation de l’intégration. |
| ExecutionError | Erreurs survenues lors de l’appel de l’intégration. |
| IntegrationLatency | Différence de temps entre l’envoi de la demande à l’intégration par API Gateway et la réception de la réponse de l’intégration par API Gateway. Supprimé pour les rappels et les intégrations simulées. |
Vous pouvez utiliser les dimensions du tableau suivant pour filtrer les métriques API Gateway.
| Dimension | Description |
| --- | --- |
| ApiId | Filtre les métriques API Gateway pour une API avec l’ID d’API spécifié. |
| ApiId, Scène | Filtre les métriques API Gateway pour trouver une étape d’API portant l’ID d’API et l’ID d’étape spécifiés. |
| ApiId, Méthode, ressource, étape | Filtre les métriques API Gateway pour trouver une méthode d’API portant l’ID d’API, l’ID d’étape, le chemin de ressource et l’ID de routage spécifiés. API Gateway n'enverra pas ces métriques à moins que vous n'ayez explicitement activé CloudWatch les métriques détaillées. Vous pouvez le faire en appelant l'[UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html)action de l'API REST API Gateway V2 pour mettre à jour la `detailedMetricsEnabled` propriété sur`true`. Vous pouvez également appeler la AWS CLI commande [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) pour mettre à jour la `DetailedMetricsEnabled` propriété en. `true` L’activation de ces métriques implique des frais supplémentaires pour votre compte. Pour plus d'informations sur les tarifs, consultez [Amazon CloudWatch Pricing](https://aws.amazon.com/cloudwatch/pricing/). |
# Configuration de la journalisation WebSocket APIs dans API Gateway
Vous pouvez activer la journalisation pour écrire des CloudWatch journaux dans Logs. Il existe deux types de connexion à l'API CloudWatch : la journalisation de l'exécution et la journalisation des accès. Lors de la journalisation de l'exécution, API Gateway gère les CloudWatch journaux. Le processus comprend la création de groupes de journaux et de flux de journaux, et la génération de rapports dans les flux de journaux sur toutes les demandes et réponses des utilisateurs.
Pour renforcer votre niveau de sécurité, nous vous recommandons d’utiliser la journalisation des exécutions au niveau `ERROR` ou `INFO`. Vous devrez peut-être le faire pour vous conformer aux différents cadres de conformité. Pour plus d’informations, consultez [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) dans le *Guide de l’utilisateur AWS Security Hub *.
Dans la journalisation des accès, vous, en tant que développeur d’API, souhaitez enregistrer qui a accédé à votre API et comment l’appelant à eu accès à l’API. Vous pouvez créer votre propre groupe de journaux ou en choisir un existant, qui peut être géré par API Gateway. Pour spécifier les détails d’accès, vous sélectionnez des variables `$context` (exprimées au format de votre choix) et vous choisissez un groupe de journaux comme destination.
Pour obtenir des instructions sur la configuration de la CloudWatch journalisation, consultez[Configuration de la journalisation des CloudWatch API à l'aide de la console API Gateway](set-up-logging.md#set-up-access-logging-using-console).
Lorsque vous spécifiez **Log Format (Format de journal)**, vous pouvez choisir les variables de contexte à journaliser. Les variables suivantes sont prises en charge.
| Paramètre | Description |
| --- | --- |
| \$1context.apiId | Identifiant qu’API Gateway attribue à votre API. |
| \$1context.authorize.error | Message d’erreur d’autorisation. |
| \$1context.authorize.latency | Latence d’autorisation en millisecondes. |
| \$1context.authorize.status | Code de statut renvoyé à la suite d’une tentative d’autorisation. |
| \$1context.authorizer.error | Message d’erreur renvoyé par un mécanisme d’autorisation. |
| \$1context.authorizer.integrationLatency | Latence de l’autorisation Lambda en ms. |
| \$1context.authorizer.integrationStatus | Code de statut renvoyé par un mécanisme d’autorisation Lambda. |
| \$1context.authorizer.latency | Latence du mécanisme d’autorisation en millisecondes (ms). |
| \$1context.authorizer.requestId | ID de demande du AWS point de terminaison. |
| \$1context.authorizer.status | Code de statut renvoyé par un mécanisme d’autorisation. |
| \$1context.authorizer.principalId | L’identifiant utilisateur principal qui est associé au jeton envoyé par le client et retourné par une fonction Lambda du mécanisme d’autorisation API Gateway Lambda. (Un mécanisme d’autorisation Lambda était auparavant connu sous le nom de mécanisme d’autorisation personnalisé.) |
| \$1context.authorizer.property | Valeur obtenue à l’aide de stringify de la paire clé-valeur spécifiée du mappage `context` renvoyé par une fonction du mécanisme d’autorisation Lambda API Gateway. Par exemple, si le mécanisme d’autorisation retourne le mappage `context` suivant : "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} l’appel de `$context.authorizer.key` renvoie la chaîne `"value"`, l’appel de `$context.authorizer.numKey` renvoie la chaîne `"1"` et l’appel de `$context.authorizer.boolKey` renvoie la chaîne `"true"`. |
| \$1context.authenticate.error | Message d’erreur renvoyé à la suite d’une tentative d’authentification. |
| \$1context.authenticate.latency | Latence d’authentification en millisecondes. |
| \$1context.authenticate.status | Code de statut renvoyé à la suite d’une tentative d’authentification. |
| \$1context.connectedAt | Temps de connexion au format [Epoch](https://en.wikipedia.org/wiki/Unix_time). |
| \$1context.connectionId | ID unique pour la connexion qui peut être utilisé pour effectuer un rappel au client. |
| \$1context.domainName | Nom de domaine pour l' WebSocket API. Ce nom peut être utilisé pour effectuer un rappel au client (au lieu d’une valeur codée en dur). |
| \$1context.error.message | Chaîne contenant un message d’erreur API Gateway. |
| \$1context.error.messageString | La valeur entre guillemets de \$1context.error.message, à savoir "\$1context.error.message". |
| \$1context.error.responseType | Type de réponse d’erreur. |
| \$1context.error.validationErrorString | Chaîne contenant un message d’erreur de validation détaillé. |
| \$1context.eventType | Type d'événement : `CONNECT`, `MESSAGE` ou `DISCONNECT` |
| \$1context.extendedRequestId | Équivalent à \$1context.requestId. |
| \$1context.identity.accountId | L'ID de AWS compte associé à la demande. |
| \$1context.identity.apiKey | Clé du propriétaire d’API associée à la demande d’API activée par clé. |
| \$1context.identity.apiKeyId | ID de clé du propriétaire d’API associée à la demande d’API activée par clé |
| \$1context.identity.caller | Identifiant principal de l’appelant qui a signé la demande. Pris en charge pour les routes qui utilisent l’autorisation IAM. |
| \$1context.identity.cognitoAuthenticationProvider | Liste séparée par des virgules de tous les fournisseurs d’authentification Amazon Cognito utilisés par l’appelant à l’origine de la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. Par exemple, pour une identité provenant d’un groupe d’utilisateurs Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Pour plus d’informations sur les fournisseurs d’authentification Amazon Cognito disponibles, consultez [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) dans le *Guide du développeur Amazon Cognito*. |
| \$1context.identity.cognitoAuthenticationType | Type d’authentification Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. Les valeurs possibles incluent `authenticated` pour les identités authentifiées et `unauthenticated` pour les identités non authentifiées. |
| \$1context.identity.cognitoIdentityId | ID d’identité Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | ID de groupe d’identités Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. |
| \$1context.identity.principalOrgId | [ID d’organisation AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). Pris en charge pour les routes qui utilisent l’autorisation IAM. |
| \$1context.identity.sourceIp | Adresse IP source de la connexion TCP envoyant la demande à API Gateway. |
| \$1context.identity.user | Identifiant principal de l’utilisateur qui sera autorisé à accéder aux ressources. Pris en charge pour les routes qui utilisent l’autorisation IAM. |
| \$1context.identity.userAgent | Agent utilisateur de l’appelant de l’API. |
| \$1context.identity.userArn | ARN (Amazon Resource Name) de l’utilisateur identifié après l’authentification. |
| \$1context.integration.error | Message d’erreur renvoyé à partir d’une intégration. |
| \$1context.integration.integrationStatus | Pour l'intégration du proxy Lambda, le code d'état est renvoyé par le code de fonction Lambda principal AWS Lambda, et non par le code de fonction Lambda principal. |
| \$1context.integration.latency | Latence d’intégration en millisecondes (ms). Équivalent à \$1context.integrationLatency. |
| \$1context.integration.requestId | ID de demande du AWS point de terminaison. Équivalent à \$1context.awsEndpointRequestId. |
| \$1context.integration.status | Code de statut renvoyé à partir d’une intégration. Pour les intégrations de proxy Lambda, code de statut que votre code de fonction Lambda renvoie. Équivalent à \$1context.integrationStatus. |
| \$1context.integrationLatency | Latence d’intégration en ms, disponible pour la journalisation des accès uniquement. |
| \$1context.messageId | ID côté serveur unique pour un message. Uniquement disponible lorsque `$context.eventType` est défini sur `MESSAGE`. |
| \$1context.requestId | Identique à `$context.extendedRequestId`. |
| \$1context.requestTime | Durée des demandes au format [CLF](https://httpd.apache.org/docs/current/logs.html#common) (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | Heure de la demande au format [Epoch](https://en.wikipedia.org/wiki/Unix_time), en millisecondes. |
| \$1context.routeKey | Clé de routage sélectionnée. |
| \$1context.stage | Étape de déploiement de l’appel d’API (par exemple, bêta ou production). |
| \$1context.status | Statut de la réponse. |
| \$1context.waf.error | Le message d'erreur renvoyé par AWS WAF. |
| \$1context.waf.latency | La AWS WAF latence en ms. |
| \$1context.waf.status | Le code d'état renvoyé par AWS WAF. |
Quelques exemples de certains formats de journaux d’accès utilisés couramment sont affichés dans la console API Gateway et répertoriés ci-dessous.
+ `CLF` ([Format de journal commun](https://httpd.apache.org/docs/current/logs.html#common)):
```
$context.identity.sourceIp $context.identity.caller \
$context.identity.user [$context.requestTime] "$context.eventType $context.routeKey $context.connectionId" \
$context.status $context.requestId
```
Les caractères de continuation (`\`) sont destinés à être une aide visuelle. Le format du journal doit être une seule ligne. Vous pouvez ajouter un caractère de nouvelle ligne (`\n`) à la fin du format du journal pour inclure une nouvelle ligne à la fin de chaque entrée du journal.
+ `JSON`:
```
{
"requestId":"$context.requestId", \
"ip": "$context.identity.sourceIp", \
"caller":"$context.identity.caller", \
"user":"$context.identity.user", \
"requestTime":"$context.requestTime", \
"eventType":"$context.eventType", \
"routeKey":"$context.routeKey", \
"status":"$context.status", \
"connectionId":"$context.connectionId"
}
```
Les caractères de continuation (`\`) sont destinés à être une aide visuelle. Le format du journal doit être une seule ligne. Vous pouvez ajouter un caractère de nouvelle ligne (`\n`) à la fin du format du journal pour inclure une nouvelle ligne à la fin de chaque entrée du journal.
+ `XML`:
```
\
$context.identity.sourceIp \
$context.identity.caller \
$context.identity.user \
$context.requestTime \
$context.eventType \
$context.routeKey \
$context.status \
$context.connectionId \
```
Les caractères de continuation (`\`) sont destinés à être une aide visuelle. Le format du journal doit être une seule ligne. Vous pouvez ajouter un caractère de nouvelle ligne (`\n`) à la fin du format du journal pour inclure une nouvelle ligne à la fin de chaque entrée du journal.
+ `CSV` (valeurs séparées par des virgules) :
```
$context.identity.sourceIp,$context.identity.caller, \
$context.identity.user,$context.requestTime,$context.eventType, \
$context.routeKey,$context.connectionId,$context.status, \
$context.requestId
```
Les caractères de continuation (`\`) sont destinés à être une aide visuelle. Le format du journal doit être une seule ligne. Vous pouvez ajouter un caractère de nouvelle ligne (`\n`) à la fin du format du journal pour inclure une nouvelle ligne à la fin de chaque entrée du journal.