Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # 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).