Création de routes pour les API WebSocket dans API Gateway

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.

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.

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’AWS CLI. Si vous le souhaitez, vous pouvez créer des routes personnalisées. Pour plus d’informations, consultez Présentation des API WebSocket dans API Gateway.

Création d’une route à l’aide de la console API Gateway

Création d’une route à l’aide de la AWS CLI

Pour créer une route à l’aide de la AWS CLI, 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 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.

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 :