Appel de votre intégration backend : route $default et routes personnalisées - Amazon API Gateway

Si nous fournissons une traduction de la version anglaise du guide, la version anglaise du guide aura préséance en cas de contradiction. La traduction sera une traduction automatique.

Appel de votre intégration backend : route $default et routes personnalisées

Utilisation de routes pour traiter les messages

Dans les API WebSocket d'API Gateway, les messages peuvent être envoyés depuis le client vers votre service backend et vice versa. À la différence du modèle de demande/réponse HTTP, dans WebSocket, le serveur principal peut envoyer des messages au client sans intervention de celui-ci.

Les messages peuvent être de type JSON ou autre que JSON. Toutefois, seuls les messages JSON peuvent être acheminés vers des intégrations spécifiques en fonction du contenu du message. Les messages autres que JSON sont transmis au serveur principal par la route $default.

Note

API Gateway prend en charge des charges utiles de messages 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 Utilisation des types de médias binaires pour les WebSocket APIs.

Avec les API WebSocket d'API Gateway, il est possible d'acheminer des messages JSON pour exécuter un service backend spécifique en fonction du contenu du message. Lorsqu'un client envoie un message sur sa connexion WebSocket, une demande de routage est transmise à l'API WebSocket. La demande est mise en correspondance avec la route à l'aide de la clé de routage correspondante dans API Gateway. Vous pouvez configurer une demande de routage pour une API WebSocket dans la console API Gateway, en utilisant l'AWS CLI ou le kit SDK AWS.

Note

Dans l’AWS CLI et les kits SDK AWS, vous pouvez créer des routes 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 afin qu'il exécute la validation d'une demande de routage avant de continuer avec la demande d'intégration. Si la validation échoue, API Gateway rejette la demande sans appeler votre service backend, envoie une réponse de passerelle "Bad request body" similaire à la suivante au client, et publie les résultats de la validation dans CloudWatch Logs :

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

Cela réduit les appels inutiles à votre serveur principal et vous permet de vous concentrer sur les autres exigences de votre API.

Vous pouvez également définir une réponse de routage pour les routes de votre API afin d'activer la 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 de routage, API Gateway ne renverra aucune information sur le résultat de votre intégration à vos clients.

Route $default

Chacune des API WebSocket d'API Gateway peut avoir une route $default. 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 une route pour des charges utiles autres que JSON.

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 propriété JSON et que cette propriété équivaut à une valeur qui correspond à la valeur de la clé de routage, API Gateway invoque l'intégration. (Pour plus d'informations, consultez À propos des API WebSocket dans API Gateway.)

Par exemple, supposons que vous vouliez créer une application de conversation. Vous pouvez commencer par créer une API WebSocket dont l'expression de sélection de la route 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 intégrations d'API WebSocket d'API Gateway pour la connexion à votre logique métier

Après avoir configuré une route pour une API WebSocket d'API Gateway, 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 serveur principal renvoie à API Gateway, et qui peuvent être utilisées pour construire un message à envoyer au client (si une réponse de routage est définie).

Pour plus d'informations sur la configuration d'intégrations, consultez la section Configuration des intégrations WebSocket API.

Différences majeures entre les API WebSocket et les API REST

Les intégrations d'API WebSocket sont similaires aux intégrations d'API REST, hormis les différences suivantes :

  • Actuellement, dans la API Gateway console, vous devez d'abord créer une route, puis une intégration en tant que cible de cette route. En revanche, dans l'API et l'interface de ligne de commande, vous pouvez créer des routes et des intégrations en toute indépendance et 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 l'AWS CLI et les kits SDK AWS, vous pouvez réutiliser une intégration en définissant la cible de la route sur une valeur de "integrations/{integration-id}", où {integration-id}" est l'ID unique de l'intégration à associer à la route.

  • API Gateway propose plusieurs expressions de sélection, que vous pouvez utiliser dans vos routes 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. De même que pour les expressions de sélection de la route, vous pouvez définir une expression de sélection qui sera évaluée par API Gateway afin de choisir l'élément adéquat. 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 et $integration.response.header.<headerName>.

Dans le protocole HTTP, dans lequel les demandes et les réponses sont envoyées de manière synchrone, la communication est essentiellement unidirectionnelle. Dans le protocole WebSocket, 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 qui est configurée pour utiliser l'intégration AWS_PROXY ou LAMBDA_PROXY, la communication est unidirectionnelle, et API Gateway ne transmet pas automatiquement la réponse du serveur principal par le biais de la réponse de routage. 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.