Utilisation des routes pour les API WebSocket - Amazon API Gateway

Utilisation des routes pour les API WebSocket

Dans votre API WebSocket, les messages JSON entrants sont dirigés vers des intégrations 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.

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 route $connect lorsqu'une connexion persistante est établie entre le client et une API WebSocket.

  • 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 les API basées sur WebSocket, l'expression doit prendre 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, request.body fait référence à la charge utile JSON du message, et .action est une expression JSONPath. 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 expression JSONPath renvoie un ensemble de deux éléments, ceux-ci seront présentés 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
$request.body.action join Variable désencapsulée
${request.body.action} join Variable encapsulée
${request.body.service}/${request.body.action} chat/join Plusieurs variables avec des valeurs statiques
${request.body.action}-${request.body.invalidPath} join- Si JSONPath n'est pas trouvé, la variable est résolue en tant que «  ».
action action Valeur statique
\$default $default 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 API WebSocket dans API Gateway

Lorsque vous créez une nouvelle API WebSocket, trois routes prédéfinies sont disponibles : $connect, $disconnect et $default. Vous pouvez les créer à l'aide de la console, de l'API ou de l'interface de ligne de commande AWS. Si vous le souhaitez, vous pouvez créer des routes personnalisées. Pour de plus amples informations, veuillez consulter À propos des API WebSocket dans API Gateway.

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.

  2. Pour créer une des routes prédéfinies ($connect, $disconnect et $default), choisissez son nom.

  3. Si vous le souhaitez, vous pouvez créer des routes personnalisées. Pour ce faire, entrez le nom de la clé de routage dans la zone de texte New Route Key (Nouvelle clé de routage) et sélectionnez l'icône de la coche.

    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.

Création d'une route à l'aide de l'interface de ligne de commande AWS

Pour créer une route à l'aide de l'interface de ligne de commande AWS, appelez create-route comme illustré dans l'exemple suivant :

aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default

Exemple de sortie :

{ "ApiKeyRequired": false, "AuthorizationType": "NONE", "RouteKey": "$default", "RouteId": "1122334" }

Spécification des paramètres de la demande de route 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.

  • Authorization (Autorisation) : Si aucune autorisation n'est nécessaire, vous pouvez spécifier NONE. Sinon, vous pouvez spécifier :

    • AWS_IAM pour utiliser les stratégies IAM AWS standard pour 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. Le mécanisme d'autorisation peut résider dans votre propre compte AWS ou dans un autre compte AWS. Pour de plus amples informations sur les mécanismes d'autorisation Lambda, veuillez consulter Utilisation des mécanismes d'autorisation Lambda API Gateway.

      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 à l'aide de la console API Gateway.

    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.

  • API Key Required (Clé API requise) : Si vous le souhaitez, vous pouvez exiger une clé API pour une route $connect de l'API. Vous pouvez utiliser des clés API avec des plans d'utilisation pour contrôler et suivre l'accès à vos API. Pour plus d'informations, consultez Création et utilisation de plans d'utilisation avec des clés d'API.

Configuration de la demande de route $connect à l'aide de la console API Gateway

Pour configurer la demande de route $connect pour une API WebSocket à l'aide de la console API Gateway :

  1. Connectez-vous à la console API Gateway et choisissez l'API, puis choisissez Routes.

  2. Sous Routes, choisissez $connect.

  3. Dans le volet de présentation de la route, choisissez Route Request (Demande de route).

  4. Sous Access Settings (Paramètres d'accès), configurez les paramètres de la route comme suit :

    1. Pour modifier le paramètre Authorization (Autorisation), choisissez l'icône du crayon. Choisissez le paramètre souhaité dans le menu déroulant et choisissez l'icône de la coche pour enregistrer le nouveau paramètre.

    2. Pour modifier le paramètre API Key Required (Clé API requise), choisissez l'icône du crayon. Choisissez true ou false dans le menu déroulant et choisissez l'icône de la coche pour enregistrer le nouveau paramètre.