# Descripción general de las API de WebSocket en API Gateway
En API Gateway puede crear una API de WebSocket como un frontend con estado para un servicio de AWS (como Lambda o DynamoDB) o para un punto de enlace HTTP. La API de WebSocket invoca al backend en función del contenido de los mensajes que recibe de las aplicaciones cliente.
A diferencia de una API de REST, que recibe las solicitudes y responde a ellas, una API de WebSocket admite la comunicación bidireccional entre las aplicaciones cliente y el backend. El backend puede enviar mensajes de devolución de llamada a los clientes conectados.
En la API de WebSocket, los mensajes JSON entrantes se dirigen a las integraciones de backend en función de las rutas que se hayan configurado. (Los mensajes que no son de JSON se dirigen a la ruta `$default` que se configure).
Una *ruta* incluye una *clave de ruta*, que es el valor que se espera una vez que se evalúa una *expresión de selección de ruta*. `routeSelectionExpression` es un atributo definido en el nivel de API. Especifica una propiedad JSON cuya presencia se espera en la carga del mensaje. Para obtener más información sobre las expresiones de selección de ruta, consulte [Expresiones de selección de ruta](websocket-api-develop-routes.md#apigateway-websocket-api-route-selection-expressions).
Por ejemplo, si los mensajes JSON contienen una propiedad `action` y desea realizar diferentes acciones en función de esta propiedad, la expresión de selección de ruta podría ser `${request.body.action}`. La tabla de enrutamiento especificaría la acción que se debe realizar comparando el valor de la propiedad `action` con los valores de clave de ruta personalizados que se han definido en la tabla.
## Uso de rutas para una API de WebSocket
Existen tres rutas predefinidas que se pueden utilizar: `$connect`, `$disconnect` y `$default`. Además, es posible crear rutas personalizadas.
+ API Gateway llama a la ruta `$connect` al iniciarse una conexión persistente entre el cliente y una API de WebSocket.
+ API Gateway llama a la ruta `$disconnect` cuando el cliente o el servidor se desconecta de la API.
+ API Gateway llama a una ruta personalizada después de evaluar la expresión de selección de ruta con respecto al mensaje si se encuentra una ruta coincidente; esta coincidencia determina qué integración se invoca.
+ API Gateway llama a la ruta `$default` si la expresión de selección de ruta no puede evaluarse con respecto al mensaje o no se encuentra ninguna ruta coincidente.
Para obtener más información sobre las rutas `$connect` y `$disconnect`, consulte [Administración de usuarios conectados y aplicaciones cliente: rutas `$connect` y `$disconnect`](apigateway-websocket-api-route-keys-connect-disconnect.md).
Para obtener más información sobre la ruta `$default` y las rutas personalizadas, consulte [Invocación de la integración de backend con la ruta `$default` y las rutas personalizadas en API Gateway](apigateway-websocket-api-routes-integrations.md).
## Envío de datos a las aplicaciones cliente conectadas
Los servicios de backend pueden enviar datos a las aplicaciones cliente conectadas. Puede enviar datos si hace lo siguiente:
+ Use una integración puede enviar una respuesta, que se devuelve al cliente mediante una respuesta de ruta que usted haya definido.
+ Puede utilizar la API `@connections` para enviar una solicitud POST. Para obtener más información, consulte [Uso de comandos de `@connections` en el servicio de backend](apigateway-how-to-call-websocket-api-connections.md).
## Códigos de estado de la API de WebSocket
Las API de WebSocket de API Gateway utilizan los siguientes códigos de estado para la comunicación del servidor al cliente, tal y como se describe en el [registro de números de códigos de cierre de WebSocket](https://www.iana.org/assignments/websocket/websocket.xhtml#close-code-number):
1001
API Gateway devuelve este código de estado cuando el cliente permanece inactivo durante 10 minutos o alcanza el tiempo de conexión máximo de 2 horas.
1003
API Gateway devuelve este código de estado cuando un punto de conexión recibe un tipo de medio binario. Los tipos de medios binarios no se admiten en las API de WebSocket.
1005
API Gateway devuelve este código de estado si el cliente envía una trama de cierre sin un código de cierre.
1006
API Gateway devuelve este código de estado si se produce un cierre inesperado de la conexión, como el cierre de la conexión TCP sin una trama de cierre de WebSocket.
1008
API Gateway devuelve este código de estado cuando un punto de conexión recibe demasiadas solicitudes de un cliente concreto.
1009
API Gateway devuelve este código de estado cuando un punto de conexión recibe un mensaje demasiado grande para procesarlo.
1011
API Gateway devuelve este código de estado cuando se produce un error interno del servidor.
1012
API Gateway devuelve este código de estado si el servicio se reinicia.
# Administración de usuarios conectados y aplicaciones cliente: rutas `$connect` y `$disconnect`
En la siguiente sección se describe cómo utilizar las rutas `$connect` y `$disconnect` para la API de WebSocket.
**Topics**
+ [La ruta `$connect`](#apigateway-websocket-api-routes-about-connect)
+ [Transmitir información de conexión de la ruta `$connect`](#apigateway-websocket-api-passing-connectionId-on-connect)
+ [La ruta `$disconnect`](#apigateway-websocket-api-routes-about-disconnect)
## La ruta `$connect`
Las aplicaciones cliente se conectan a la API de WebSocket enviando una solicitud de actualización de WebSocket. Si la solicitud se realiza correctamente, la ruta `$connect` se ejecuta mientras se establece la conexión.
Dado que la conexión de WebSocket es una conexión con estado, solo se puede configurar la autorización en la ruta `$connect`. `AuthN`/`AuthZ` solo se realizará en el momento de la conexión.
Hasta que se complete la ejecución de la integración asociada a la ruta `$connect`, la solicitud de actualización está pendiente y la conexión real no se establece. Si la solicitud `$connect` da error (por ejemplo, debido a un error de `AuthN`/`AuthZ` o de integración), la conexión no se realizará.
**nota**
Si se produce un error en la autorización en `$connect`, la conexión no se establece y el cliente recibirá una respuesta `401` o `403`.
La configuración de una integración para `$connect` es opcional. Considere la posibilidad de configurar una integración `$connect` si:
+ Desea habilitar a los clientes para especificar subprotocolos mediante el campo `Sec-WebSocket-Protocol`. Para ver código de ejemplo, consulte [Configuración de una ruta `$connect` que requiere un subprotocolo WebSocket](websocket-connect-route-subprotocol.md).
+ Desea recibir una notificación cuando los clientes se conectan.
+ Desea limitar las conexiones o controlar quién se conecta.
+ Desea que el backend envíe mensajes de respuesta a los clientes mediante una URL de devolución de llamada.
+ Desea almacenar los ID de conexión y otra información en una base de datos (por ejemplo, Amazon DynamoDB).
## Transmitir información de conexión de la ruta `$connect`
Puede utilizar integraciones con y sin proxy para transferir información de la ruta `$connect` a una base de datos u otro Servicio de AWS.
### Para transferir información de conexión mediante una integración de proxy
En ese caso, puede acceder a la información de conexión desde una integración de proxy de Lambda. Utilice otro Servicio de AWS o función de AWS Lambda para publicar en la conexión.
La siguiente función de Lambda muestra cómo utilizar el objeto `requestContext` para registrar el ID de conexión, el nombre de dominio, el nombre de etapa y las cadenas de consulta.
------
#### [ Node.js ]
```
export const handler = async(event, context) => {
const connectId = event["requestContext"]["connectionId"]
const domainName = event["requestContext"]["domainName"]
const stageName = event["requestContext"]["stage"]
const qs = event['queryStringParameters']
console.log('Connection ID: ', connectId, 'Domain Name: ', domainName, 'Stage Name: ', stageName, 'Query Strings: ', qs )
return {"statusCode" : 200}
};
```
------
#### [ Python ]
```
import json
import logging
logger = logging.getLogger()
logger.setLevel("INFO")
def lambda_handler(event, context):
connectId = event["requestContext"]["connectionId"]
domainName = event["requestContext"]["domainName"]
stageName = event["requestContext"]["stage"]
qs = event['queryStringParameters']
connectionInfo = {
'Connection ID': connectId,
'Domain Name': domainName,
'Stage Name': stageName,
'Query Strings': qs}
logging.info(connectionInfo)
return {"statusCode": 200}
```
------
### Para transferir información de conexión mediante una integración que no sea de proxy
+ Puede acceder a la información de conexión con una integración que no sea de proxy. Configure la solicitud de integración y proporcione una plantilla de solicitud de API de WebSocket. La siguiente plantilla de mapeo [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) proporciona una solicitud de integración. Esta solicitud envía los siguientes detalles a una integración que no sea de proxy:
+ ID de la conexión
+ Nombre del dominio
+ Nombre de la fase
+ Ruta
+ Encabezados
+ Cadenas de consulta
Esta solicitud envía el ID de conexión, el nombre de dominio, el nombre de etapa, las rutas, los encabezados y las cadenas de consulta a una integración que no sea de proxy.
```
{
"connectionId": "$context.connectionId",
"domain": "$context.domainName",
"stage": "$context.stage",
"params": "$input.params()"
}
```
Para obtener más información sobre la configuración de transformaciones de datos, consulte [Transformaciones de datos para las API de WebSocket en API Gateway](websocket-api-data-transformations.md).
Para completar la solicitud de integración, establezca `StatusCode: 200` para la respuesta de integración. Para obtener más información sobre la configuración de una respuesta de integración, consulte [Configuración de una respuesta de integración mediante la consola de API Gateway](apigateway-websocket-api-integration-responses.md#apigateway-websocket-api-integration-response-using-console).
## La ruta `$disconnect`
La ruta `$disconnect` se ejecuta una vez que se ha cerrado la conexión.
La conexión la puede cerrar el servidor o el cliente. Como la conexión ya está cerrada cuando se ejecuta, `$disconnect` es un evento de mejor esfuerzo. API Gateway hará todo lo posible para entregar el evento `$disconnect` a su integración, pero no puede garantizar la entrega.
El backend puede iniciar la desconexión mediante la API `@connections`. Para obtener más información, consulte [Uso de comandos de `@connections` en el servicio de backend](apigateway-how-to-call-websocket-api-connections.md).
# 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.
**Topics**
+ [Uso de rutas para procesar mensajes](#apigateway-websocket-api-overview-routes)
+ [La ruta `$default`](#apigateway-websocket-api-routes-about-default)
+ [Rutas personalizadas](#apigateway-websocket-api-routes-about-custom)
+ [Uso de las integraciones de API de WebSocket de API Gateway para conectarse a la lógica de negocio](#apigateway-websocket-api-overview-integrations)
+ [Diferencias importantes entre las API de WebSocket y las API de REST](#apigateway-websocket-api-overview-integrations-differences)
## 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](websocket-api-develop-binary-media-types.md).
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](apigateway-websocket-api-overview.md).)
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](apigateway-websocket-api-integrations.md).
## 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/{integration-id}"`, donde `{integration-id}"` es el ID exclusivo de la integración que se va a asociar a la ruta.
+ API Gateway ofrece varias [expresiones de selección](apigateway-websocket-api-selection-expressions.md) 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.` y valores estáticos.
+ En las respuestas de integración, la expresión de selección de plantillas admite `$request.body.`, `$integration.response.statuscode` y `$integration.response.header.`, 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 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.
# Expresiones de selección de WebSocket
API Gateway utiliza expresiones de selección como forma de evaluar el contexto de solicitud y respuesta y producir una clave. La clave se utiliza para seleccionar un valor de un conjunto de valores posibles, normalmente proporcionados por el desarrollador de la API. El conjunto exacto de variables admitidas variará en función de la expresión dada. A continuación se describe con más detalle cada expresión.
En todas las expresiones, el lenguaje sigue el mismo conjunto de reglas:
+ Las variables tienen el prefijo `"$"`.
+ Se pueden utilizar llaves para definir explícitamente los límites de las variables, por ejempl., `"${request.body.version}-beta"`.
+ Se admite el uso de varias variables, pero la evaluación solo se produce una vez (sin evaluación recursiva).
+ A los signos de dólar (`$`) se les puede aplicar una secuencia de escape con `"\"`. Esto resulta muy útil al definir una expresión que se asigna a la clave `$default` reservada, como, por ejemplo, `"\$default"`.
+ En algunos casos, se requiere un patrón de formato. En este caso, la expresión debe encerrarse entre barras inclinadas (`"/"`), por ejemplo `"/2\d\d/"`, para que coincida con los códigos de estado `2XX`.
**Topics**
+ [Expresiones de selección de respuesta de ruta](#apigateway-websocket-api-route-response-selection-expressions)
+ [Expresiones de selección de clave de API](#apigateway-websocket-api-apikey-selection-expressions)
+ [Expresiones de selección de asignación de API](#apigateway-websocket-api-mapping-selection-expressions)
+ [Resumen de expresiones de selección de WebSocket](#apigateway-websocket-api-selection-expression-table)
## Expresiones de selección de respuesta de ruta
Las [respuestas de ruta](apigateway-websocket-api-route-response.md) se utilizan para modelar una respuesta desde el backend al cliente. En la API de WebSocket, la respuesta de ruta es opcional. Si se define, indica a API Gateway que debe devolver una respuesta a un cliente al recibir un mensaje de WebSocket.
La evaluación de la *expresión de selección de respuesta de ruta* produce una clave de respuesta de ruta. Con el tiempo, esta clave se utilizará para elegir una de las respuestas [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html) asociadas a la API. Sin embargo, actualmente solo se admite la clave `$default`.
## Expresiones de selección de clave de API
Esta expresión se evalúa cuando el servicio determina que la solicitud dada debe continuar solo si el cliente proporciona una [clave de API](api-gateway-basic-concept.md#apigateway-definition-api-key) válida.
Actualmente, los únicos dos valores admitidos son `$request.header.x-api-key` y `$context.authorizer.usageIdentifierKey`.
## Expresiones de selección de asignación de API
Esta expresión se evalúa para determinar qué etapa de API está seleccionada cuando se realiza una solicitud mediante un dominio personalizado.
Actualmente el único valor admitido es `$request.basepath`.
## Resumen de expresiones de selección de WebSocket
En la tabla siguiente, se resumen los casos de uso de las expresiones de selección en las API de WebSocket:
| Expresión de selección | Se evalúa como la clave para | Notas | Ejemplo de caso de uso |
| --- | --- | --- | --- |
| Api.RouteSelectionExpression | Route.RouteKey | \$1default se admite como una ruta catch-all. | Direccionar los mensajes de WebSocket en función del contexto de una solicitud de cliente. |
| Route.ModelSelectionExpression | Clave para Route.RequestModels | Opcional. Si se proporciona para una integración que no sea de proxy, se produce la validación del modelo. `$default` se admite como método catch-all. | Realizar la validación de solicitudes de forma dinámica dentro de la misma ruta. |
| Integration.TemplateSelectionExpression | Clave para Integration.RequestTemplates | Opcional. Se puede proporcionar para la integración que no sea de proxy con el fin de manipular las cargas entrantes. `${request.body.jsonPath}`Se admiten y valores estáticos. `$default` se admite como método catch-all. | Manipular la solicitud del intermediario en función de las propiedades dinámicas de la solicitud. |
| Integration.IntegrationResponseSelectionExpression | IntegrationResponse.IntegrationResponseKey | Opcional. Se puede proporcionar para una integración que no sea de proxy. Actúa como una coincidencia de patrones para los mensajes de error (de Lambda) o los códigos de estado (de las integraciones HTTP). `$default` es necesario en las integraciones que no sean de proxy para que actúe como el método catch-all para las respuestas correctas. | Manipular la respuesta del backend. Elegir la acción que debe realizarse en función de la respuesta dinámica del backend (por ejemplo, controlar de forma inequívoca determinados errores). |
| IntegrationResponse.TemplateSelectionExpression | Clave para IntegrationResponse.ResponseTemplates | Opcional. Se puede proporcionar para una integración que no sea de proxy. Se admite \$1default. | En algunos casos, una propiedad dinámica de la respuesta puede dictar la necesidad de transformaciones diferentes dentro de la misma ruta y la integración asociada. `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}`, Se admiten , , , y valores estáticos. `$default` se admite como método catch-all. |
| Route.RouteResponseSelectionExpression | RouteResponse.RouteResponseKey | Debe proporcionarse para iniciar la comunicación bidireccional en una ruta de WebSocket. Actualmente, este valor está restringido únicamente a `$default`. | |
| RouteResponse.ModelSelectionExpression | Clave para RouteResponse.RequestModels | No se admite actualmente. | |