Invocación de la integración del backend: ruta $default y rutas personalizadas

Uso de rutas para procesar mensajes

En las API de WebSocket API Gateway, los mensajes se pueden enviar desde el cliente a tu servicio de backend y viceversa. A diferencia del modelo de solicitud/respuesta de HTTP, en WebSocket el backend se pueden enviar mensajes al cliente sin que el cliente 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 Trabajar con tipos de medios binarios para API de WebSocket.

Con WebSocket las API de API Gateway, los mensajes JSON se pueden enrutar 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 WebSocket conexión, se genera una solicitud de enrutamiento a la WebSocket API. La solicitud se emparejará con la ruta que tenga la clave de ruta correspondiente en API Gateway. Puedes configurar una solicitud de ruta para una WebSocket API en la consola de API Gateway AWS CLI, mediante o mediante un AWS SDK.

nota

En los AWS SDK AWS CLI y, puedes crear rutas antes o después de crear 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 la validación falla, API Gateway no aprueba la solicitud sin llamar al backend, envía una respuesta de "Bad request body" puerta de enlace 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 API Gateway puede tener una $default ruta. 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 Acerca de WebSocket las API en API Gateway.)

Por ejemplo, supongamos que desea crear una aplicación de sala de chat. Puedes empezar por crear una WebSocket API cuya expresión de selección de rutas 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 WebSocket de API de API Gateway para conectarse a su lógica empresarial

Tras configurar una ruta para una API de WebSocket API Gateway, debes especificar la integración que quieres usar. 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 Configuración de integraciones WebSocket de API.

Diferencias importantes entre las WebSocket API y las API REST

Las integraciones de las WebSocket API son similares a las integraciones de las API de REST, con la salvedad de las siguientes diferencias:

• 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 los AWS SDK AWS CLI y, puedes reutilizar una integración estableciendo el objetivo de la ruta en un valor de"integrations/{integration-id}", donde {integration-id}" es el ID único de la integración que se va a asociar a la ruta.

• 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 $default si no se encuentra una plantilla coincidente.

  • En las solicitudes de integración, la expresión de selección de plantillas admite $request.body.<json_path_expression> y valores estáticos.

  • En las respuestas de integración, la expresión de selección de plantillas admite $request.body.<json_path_expression>, $integration.response.statuscode y $integration.response.header.<headerName>, además de valores estáticos.

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 WebSocket protocolo, 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.