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é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. routeSelectionExpression
Il 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 JSONPathrequest.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'$default
itiné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
-
Connectez-vous à la console API Gateway, choisissez leAPI, puis choisissez Routes.
Choisissez Créer une route.
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.-
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-route
comme 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'$connect
itiné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_IAM
pour utiliser des AWS IAM politiques standard afin de contrôler l'accès à votreAPI. -
CUSTOM
pour 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'
$connect
itiné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'
$connect
itiné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'$connect
itinéraire à l'aide de la console API Gateway
Pour configurer la demande d'$connect
itinéraire pour un à WebSocket API l'aide de la console API Gateway :
-
Connectez-vous à la console API Gateway, choisissez leAPI, puis choisissez Routes.
-
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. Dans la section Paramètres de la demande de route, choisissez Modifier.
Pour Autorisation, sélectionnez un type d'autorisation.
Pour demander une clé API pour l'
$connect
itinéraire, sélectionnez Exiger une API clé.Sélectionnez Enregistrer les modifications.