Créer des itinéraires pour WebSocket APIs dans API Gateway

Dans votre WebSocket API, les JSON messages entrants sont dirigés vers des intégrations de backend en fonction des itinéraires que vous configurez. (Les JSON messages non électroniques sont dirigés vers un $default itinéraire 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. routeSelectionExpressionIl s'agit d'un attribut défini au API niveau. Il spécifie une JSON propriété qui devrait être présente 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 JSON messages contiennent une action propriété et que vous souhaitez effectuer différentes actions en fonction de cette propriété, votre expression de sélection d'itinéraire 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.

• APILa passerelle appelle la $connect route lorsqu'une connexion persistante entre le client et un WebSocket API est initiée.

• APILa passerelle appelle la $disconnect route lorsque le client ou le serveur se déconnecte duAPI.

• APIGateway appelle une route personnalisée une fois que l'expression de sélection de route a été évaluée par rapport au message si une route correspondante est trouvée ; la correspondance détermine quelle intégration est invoquée.

• APILa passerelle appelle la $default route si l'expression de sélection de 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 basedAPIs, l'expression doit être de la forme$request.body.{path_to_body_element}.

Supposons, par exemple, que vous envoyiez le JSON message suivant :

{
    "service" : "chat",
    "action" : "join",
    "data" : {
        "room" : "room1234"
   }
}

Vous souhaiterez peut-être sélectionner votre API comportement en fonction de la action propriété. 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 JSON charge utile de votre message et .action est une JSONPathexpression. Vous pouvez utiliser n'importe quelle expression de JSON chemin par la suiterequest.body, mais gardez à l'esprit que le résultat sera stringifié. 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
$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 le n'JSONPathest pas trouvé, la variable est résolue sous la forme « ».
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 aucun itinéraire correspondant n'est trouvé, API Gateway essaie de le $default trouver s'il est disponible. Si l'$defaultitinéraire n'est pas défini, API Gateway renvoie une erreur.

Configurer des itinéraires pour une WebSocket API API passerelle intégrée

Lorsque vous en créez un nouveau pour la première fois WebSocket API, il existe trois itinéraires prédéfinis : $connect$disconnect, et$default. Vous pouvez les créer à l'aide de la consoleAPI, ou AWS CLI. Si vous le souhaitez, vous pouvez créer des routes personnalisées. Pour plus d’informations, consultez Présentation de WebSocket APIs in API Gateway.

Note

Dans leCLI, vous pouvez créer des itinéraires avant ou après avoir créé des intégrations, et vous pouvez réutiliser la même intégration pour plusieurs itinéraires.

Création d'un itinéraire à l'aide de la console API Gateway

Pour créer un itinéraire à l'aide de la console API Gateway

1. Connectez-vous à la console API Gateway, choisissez leAPI, puis choisissez Routes.

2. Choisissez Créer une route.

3. 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.

4. Sélectionnez et configurez le type d'intégration pour la route. Pour plus d’informations, consultez Configuration d'une demande d'intégration d' WebSocket API à l'aide de la console API Gateway.

Créez un itinéraire à l'aide du AWS CLI

Pour créer un itinéraire à l'aide du AWS CLI, appelez create-routecomme indiqué 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 l'$connectitinéraire pour votreAPI, les paramètres facultatifs suivants sont disponibles pour activer l'autorisation pour votreAPI. 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_IAMpour utiliser des AWS IAM politiques standard afin de contrôler l'accès à votreAPI.

  • CUSTOMpour implémenter l'autorisation pour et API en spécifiant une fonction 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 de plus amples informations sur les mécanismes d'autorisation Lambda, veuillez consulter Utiliser les API autorisateurs Gateway Lambda.

    Note

    Dans la console API Gateway, le CUSTOM paramètre n'est visible qu'une fois que vous avez configuré une fonction d'autorisation, comme décrit dansConfiguration d'un autorisateur Lambda (console).

  Important

  Le paramètre d'autorisation est appliqué à l'ensembleAPI, pas seulement à l'$connectitinéraire. La route $connect protège les autres routes, car elle est appelée sur chaque connexion.

• APIClé requise : vous pouvez éventuellement demander une API clé pour API l'$connectitinéraire d'un. Vous pouvez utiliser API des clés ainsi que des plans d'utilisation pour contrôler et suivre l'accès à votreAPIs. Pour plus d’informations, consultez Plans d'utilisation et API clés pour REST APIs in API Gateway .

Configuration de la demande d'$connectitinéraire à l'aide de la console API Gateway

Pour configurer la demande d'$connectitinéraire pour un à WebSocket API l'aide de la console API Gateway :

1. Connectez-vous à la console API Gateway, choisissez leAPI, puis choisissez Routes.

2. Sous Routes, choisissez $connect ou créez une route $connect en suivant Création d'un itinéraire à l'aide de la console API Gateway.

3. Dans la section Paramètres de la demande de route, choisissez Modifier.

4. Pour Autorisation, sélectionnez un type d'autorisation.

5. Pour demander une clé API pour l'$connectitinéraire, sélectionnez Exiger une API clé.

6. Sélectionnez Enregistrer les modifications.