Invocación de la integración de backend con la ruta $default y las rutas personalizadas en API Gateway
En la siguiente sección se describe cómo invocar su integración de backend mediante la ruta $default o una ruta personalizada para una API de WebSocket.
Temas
Uso de rutas para procesar mensajes
En las API de WebSocket de API Gateway, es posible enviar mensajes desde el cliente al servicio de backend y viceversa. A diferencia del modelo solicitud/respuesta de HTTP, en WebSocket el backend puede enviar mensajes al cliente sin que este realice ninguna acción.
Los mensajes pueden ser tener el formato JSON u otro distinto. Sin embargo, solo los mensajes JSON se pueden direccionar a integraciones específicas en función del contenido del mensaje. Los mensajes que no tienen el formato JSON se transmiten a través del backend por la ruta $default.
nota
API Gateway admite cargas de mensajes de hasta 128 KB con un tamaño máximo de trama de 32 KB. Si un mensaje supera los 32 KB, se debe dividir en varias tramas, cada una con tamaño máximo de 32 KB. Si se recibe un mensaje (o una trama) más grande, la conexión se cierra con el código 1009.
Actualmente, no se admiten cargas binarias. Si se recibe una trama binaria, la conexión se cierra con el código 1003. Sin embargo, es posible convertir cargas binarias a texto. Consulte Tipos de medios binarios para las API de WebSocket en API Gateway.
Con las API de WebSocket en API Gateway, los mensajes JSON se pueden direccionar para ejecutar un servicio de backend específico en función del contenido del mensaje. Cuando un cliente envía un mensaje a través de su conexión WebSocket, esto da lugar a una solicitud de ruta a la API de WebSocket. La solicitud se emparejará con la ruta que tenga la clave de ruta correspondiente en API Gateway. Puede configurar una solicitud de ruta para una API de WebSocket en la consola de API Gateway, mediante la AWS CLI o mediante un AWS SDK.
nota
Tanto la AWS CLI como los SDK de AWS le permiten crear rutas antes o después de generar las integraciones. Actualmente, la consola no admite la reutilización de integraciones, por lo que debe crear primero la ruta y, a continuación, la integración de dicha ruta.
Puede configurar API Gateway para que realice la validación en una solicitud de ruta antes de continuar con la solicitud de integración. Si no se supera la validación, API Gateway rechaza la solicitud sin llamar al backend, envía una respuesta de gateway "Bad request body" similar a la siguiente al cliente y publica los resultados de la validación en CloudWatch Logs:
{"message" : "Bad request body", "connectionId": "{connectionId}", "messageId": "{messageId}"}
Esto reduce las llamadas innecesarias al backend y le permite centrarse en los demás requisitos de la API.
También puede definir una respuesta de ruta para las rutas de la API con objeto de permitir la comunicación bidireccional. Una respuesta de ruta describe qué datos se enviarán al cliente al finalizar la integración de una ruta determinada. No es necesario definir una respuesta para una ruta si, por ejemplo, desea que un cliente envíe mensajes al backend sin recibir una respuesta (comunicación unidireccional). Sin embargo, si no se proporciona una respuesta de ruta, API Gateway no enviará ninguna información sobre el resultado de la integración a los clientes.
La ruta $default
Cada API de WebSocket de API Gateway puede tener una ruta $default. Se trata de un valor de direccionamiento especial que se puede utilizar de las siguientes formas:
-
Puede utilizarlo junto con claves de ruta definidas para especificar una ruta "alternativa" (por ejemplo, una integración simulada genérica que devuelve un mensaje de error determinado) para los mensajes entrantes que no coinciden con ninguna de las claves de ruta definidas.
-
Puede utilizarlo sin claves de ruta definidas para especificar un modelo de proxy que delega el direccionamiento en un componente del backend.
-
También puede usarlo si desea especificar una ruta para las cargas que no son JSON.
Rutas personalizadas
Si desea invocar una integración específica en función del contenido del mensaje, puede hacerlo mediante la creación de una ruta personalizada.
Una ruta personalizada utiliza la clave de ruta y la integración que se especifiquen. Si un mensaje entrante contiene una propiedad JSON y dicha propiedad toma un valor que coincide con el valor de la clave de ruta, API Gateway invoca la integración. (Para obtener más información, consulte Descripción general de las API de WebSocket en API Gateway.)
Por ejemplo, supongamos que desea crear una aplicación de sala de chat. Puede comenzar creando una API de WebSocket cuya expresión de selección de ruta sea $request.body.action. A continuación, puede definir dos rutas: joinroom y sendmessage. Una aplicación cliente podría invocar la ruta joinroom enviando un mensaje como el siguiente:
{"action":"joinroom","roomname":"developers"}
También podría invocar la ruta sendmessage enviando un mensaje como el siguiente:
{"action":"sendmessage","message":"Hello everyone"}
Uso de las integraciones de API de WebSocket de API Gateway para conectarse a la lógica de negocio
Después de configurar una ruta para una API de WebSocket de API Gateway, debe especificar la integración que desea utilizar. Al igual que ocurre con las rutas, que pueden tener una solicitud de ruta y una respuesta de ruta, las integraciones pueden tener una solicitud de integración y una respuesta de integración. Una solicitud de integración contiene la información que espera el backend para poder procesar la solicitud procedente del cliente. Una respuesta de integración contiene los datos que el backend devuelve a API Gateway y que se pueden utilizar para construir un mensaje que se envía al cliente (si se ha definido una respuesta de ruta).
Para obtener más información sobre la configuración de integraciones, consulte Integraciones de API de WebSocket en API Gateway.
Diferencias importantes entre las API de WebSocket y las API de REST
Las integraciones para las API de WebSocket son similares a las integraciones para las API de REST, con las siguientes salvedades:
-
Actualmente, se debe crear primero una ruta en la consola de API Gateway y, a continuación, crear una integración como destino de dicha ruta. Sin embargo, en la API y la CLI, es posible crear rutas e integraciones de forma independiente, en cualquier orden.
-
Puede utilizar una única integración para varias rutas. Por ejemplo, si dispone de un conjunto de acciones estrechamente relacionadas entre sí, podría ser conveniente que todas estas rutas vayan a una única función de Lambda. En lugar de definir los detalles de la integración varias veces, puede especificarla una vez y asignarla a cada una de las rutas relacionadas.
nota
Actualmente, la consola no admite la reutilización de integraciones, por lo que debe crear primero la ruta y, a continuación, la integración de dicha ruta.
En la AWS CLI y los SDK de AWS, se puede reutilizar una integración estableciendo el destino de la ruta en el valor
"integrations/, donde{integration-id}"{integration-id}" -
API Gateway ofrece varias expresiones de selección que se pueden utilizar en las rutas e integraciones. La selección de una plantilla de entrada o una asignación de salida no depende del tipo de contenido. Al igual que ocurre con las expresiones de selección de ruta, puede definir una expresión de selección que API Gateway evaluará para elegir el elemento correcto. Todas ellas recurrirán a la plantilla
$defaultsi no se encuentra una plantilla coincidente.-
En las solicitudes de integración, la expresión de selección de plantillas admite
$request.body.y valores estáticos.<json_path_expression> -
En las respuestas de integración, la expresión de selección de plantillas admite
$request.body.,<json_path_expression>$integration.response.statuscodey$integration.response.header., además de valores estáticos.<headerName>
-
En el protocolo HTTP, en el que se envían solicitudes y respuestas de forma síncrona, la comunicación es básicamente unidireccional. En el protocolo WebSocket, la comunicación es bidireccional. Las respuestas son asíncronas y el cliente no las recibe necesariamente en el mismo orden en el que se enviaron sus mensajes. Además, el backend puede enviar mensajes al cliente.
nota
En una ruta que se ha configurado para utilizar la integración AWS_PROXY o LAMBDA_PROXY, la comunicación es unidireccional y API Gateway no pasará la respuesta del backend a la respuesta de ruta de forma automática. Por ejemplo, en el caso de la integración LAMBDA_PROXY, el cuerpo que devuelve la función de Lambda no se enviará al cliente. Si desea que el cliente reciba respuestas de integración, debe definir una respuesta de ruta para posibilitar la comunicación bidireccional.
