Invoquez l'intégration de votre backend avec la $default Route et les routes personnalisées dans Gateway API

La section suivante décrit comment invoquer votre intégration principale en utilisant la $default route ou une route personnalisée pour un WebSocket API.

Utilisation de routes pour traiter les messages

Dans API Gateway WebSocket APIs, les messages peuvent être envoyés du client à votre service principal et vice versa. Contrairement au modèle HTTP de demande/réponse, WebSocket le backend peut envoyer des messages au client sans que le client n'entreprenne aucune action.

Les messages peuvent être JSON ou nonJSON. Toutefois, seuls JSON les messages peuvent être routés vers des intégrations spécifiques en fonction du contenu des messages. Les JSON non-messages sont transmis au backend par la $default route.

Note

APIGateway prend en charge des charges utiles de messages allant jusqu'à 128 Ko avec une taille de trame maximale de 32 Ko. Si un message dépasse 32 Ko, vous devez le diviser en plusieurs trames, chacune de 32 Ko ou moins. Si un message (ou trame) plus grand est reçu, la connexion se ferme avec le code 1009.

À l'heure actuelle, les charges utiles binaires ne sont pas prises en charge. Si une trame binaire est reçue, la connexion se ferme avec le code 1003. Il est toutefois possible de convertir les charges utiles binaires en texte. Voir Types de supports binaires pour WebSocket les API dans API Gateway.

WebSocket APIsDans API Gateway, JSON les messages peuvent être routés pour exécuter un service principal spécifique en fonction du contenu du message. Lorsqu'un client envoie un message via sa WebSocket connexion, cela entraîne une demande de route vers le WebSocket API. La demande sera mise en correspondance avec l'itinéraire avec la clé de route correspondante dans API Gateway. Vous pouvez configurer une demande de route pour un WebSocket API dans la console API Gateway, en utilisant le AWS CLI, ou en utilisant un AWS SDK.

Note

Dans le AWS CLI and AWS SDKs, vous pouvez créer des itinéraires avant ou après avoir créé des intégrations. À l'heure actuelle, la console ne prend pas en charge la réutilisation d'intégrations. Par conséquent, vous devez d'abord créer la route, puis l'intégration pour cette route.

Vous pouvez configurer API Gateway pour effectuer la validation d'une demande de route avant de procéder à la demande d'intégration. Si la validation échoue, API Gateway échoue à la demande sans appeler votre backend, envoie une réponse de "Bad request body" passerelle similaire à la suivante au client et publie les résultats de la validation dans les CloudWatch journaux :

{"message" : "Bad request body", "connectionId": "{connectionId}", "messageId": "{messageId}"}

Cela réduit les appels inutiles vers votre backend et vous permet de vous concentrer sur les autres exigences de votre API système.

Vous pouvez également définir une réponse d'itinéraire pour vos itinéraires afin API de permettre une communication bidirectionnelle. Une réponse de routage indique quelles données seront envoyées à votre client à la fin de l'intégration d'une route particulière. Il n'est pas nécessaire de définir une réponse pour une route si, par exemple, vous souhaitez qu'un client envoie des messages à votre serveur principal sans recevoir de réponse (communication unidirectionnelle). Toutefois, si vous ne fournissez pas de réponse d'itinéraire, API Gateway n'enverra aucune information sur le résultat de votre intégration à vos clients.

Route $default

Chaque API passerelle WebSocket API peut avoir un $default itinéraire. Il s'agit d'une valeur de routage spéciale qui peut être utilisée de différentes manières :

• Vous pouvez l'utiliser conjointement avec les clés de routage définies, pour spécifier une route « de secours » (par exemple, une intégration fictive générique qui renvoie un message d'erreur spécifique) pour des messages entrants qui ne correspondent à aucune des clés de routage définies.

• Vous pouvez l'utiliser sans clés de routage définies pour spécifier un modèle de proxy qui délègue le routage à un composant backend.

• Vous pouvez l'utiliser pour spécifier un itinéraire pour les JSON charges non utiles.

Routes personnalisées

Si vous souhaitez invoquer une intégration spécifique sur la base du contenu du message, vous pouvez le faire en créant une route personnalisée.

Une route personnalisée utilise une clé de routage et l'intégration que vous spécifiez. Lorsqu'un message entrant contient une JSON propriété et que cette propriété est évaluée à une valeur correspondant à la valeur de la clé de route, API Gateway invoque l'intégration. (Pour plus d'informations, consultez Présentation de WebSocket APIs in API Gateway.)

Par exemple, supposons que vous vouliez créer une application de conversation. Vous pouvez commencer par créer une expression de sélection d'itinéraire WebSocket API dont l'expression est$request.body.action. Vous pouvez ensuite définir deux routes : joinroom et sendmessage. Une application client peut invoquer la route joinroom en envoyant un message similaire au suivant :

{"action":"joinroom","roomname":"developers"}

Elle peut également invoquer la route sendmessage en envoyant un message similaire au suivant :

{"action":"sendmessage","message":"Hello everyone"}

Utilisation des WebSocket API intégrations API Gateway pour vous connecter à votre logique métier

Après avoir configuré un itinéraire pour une API passerelle WebSocket API, vous devez spécifier l'intégration que vous souhaitez utiliser. Comme pour une route, qui peut faire l'objet d'une demande et d'une réponse de routage, une intégration peut être associée à une demande d'intégration et à une réponse d'intégration. Une demande d'intégration contient les informations attendues par votre serveur principal pour traiter la demande provenant de votre client. Une réponse d'intégration contient les données que votre backend renvoie à API Gateway et qui peuvent être utilisées pour créer un message à envoyer au client (si une réponse de route est définie).

Pour plus d'informations sur la configuration d'intégrations, consultez la section Intégrations pour WebSocket API in Gateway API.

Différences importantes entre WebSocket APIs et REST APIs

Les intégrations pour WebSocket APIs sont similaires aux intégrations pour RESTAPIs, à l'exception des différences suivantes :

• Actuellement, dans la console API Gateway, vous devez d'abord créer un itinéraire, puis créer une intégration en tant que cible de cet itinéraire. Cependant, dans le API andCLI, vous pouvez créer des itinéraires et des intégrations indépendamment, dans n'importe quel ordre.

• Vous pouvez utiliser une même intégration pour plusieurs routes. Par exemple, si vous avez un ensemble d'actions étroitement liées entre elles, vous souhaiterez peut-être intégrer toutes ces routes dans une Fonction Lambda unique. Au lieu de définir les détails de l'intégration plusieurs fois, vous pouvez spécifier celle-ci une seule fois et l'affecter à chacune des routes connexes.

  Note

  À l'heure actuelle, la console ne prend pas en charge la réutilisation d'intégrations. Par conséquent, vous devez d'abord créer la route, puis l'intégration pour cette route.

  Dans le AWS CLI et AWS SDKs, vous pouvez réutiliser une intégration en définissant la cible de l'itinéraire sur une valeur de"integrations/{integration-id}", où {integration-id}" est l'identifiant unique de l'intégration à associer à l'itinéraire.

• APIGateway fournit plusieurs expressions de sélection que vous pouvez utiliser dans vos itinéraires et intégrations. Vous n'avez pas besoin de vous appuyer sur le type de contenu pour sélectionner un modèle d'entrée ou un mappage de sortie. Comme pour les expressions de sélection d'itinéraires, vous pouvez définir une expression de sélection à évaluer par API Gateway afin de choisir le bon élément. si aucun modèle correspondant n'est trouvé, le modèle $default est utilisé.

  • Dans les demandes d'intégration, l'expression de sélection du modèle prend en charge $request.body.<json_path_expression> et les valeurs statiques.

  • Dans les réponses d’intégration, l’expression de sélection du modèle prend en charge $request.body.<json_path_expression>, $integration.response.statuscode, $integration.response.header.<headerName> et les valeurs statiques.

Dans le HTTP protocole, dans lequel les demandes et les réponses sont envoyées de manière synchrone, la communication est essentiellement unidirectionnelle. Dans le WebSocket protocole, la communication est bidirectionnelle. Les réponses sont asynchrones et ne sont pas nécessairement reçues par le client dans l'ordre où les messages du client ont été envoyés. De plus, le serveur principal peut envoyer des messages au client.

Note

Pour une route configurée pour être utilisée AWS_PROXY ou LAMBDA_PROXY intégrée, la communication est unidirectionnelle et API Gateway ne transmettra pas automatiquement la réponse du backend à la réponse de route. Par exemple, dans le cas de l'intégration LAMBDA_PROXY, le corps de message renvoyé par la fonction Lambda n'est pas renvoyé au client. Si vous voulez que le client reçoive les réponses de l'intégration, vous devez définir une réponse de routage pour permettre la communication bidirectionnelle.