Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Uso WebSockets para recibir mensajes en la mensajería del SDK de Amazon Chime Puede usar el [Amazon Chime JS SDK](https://github.com/aws/amazon-chime-sdk-js) para recibir mensajes o puede usar WebSockets la biblioteca de WebSocket clientes que prefiera. Siga estos temas en el orden indicado para empezar a WebSockets utilizarlos: **Topics** + [Definición de una política de IAM](#define-iam-policy) + [Recuperación del punto de conexión](#retrieve-endpoint) + [Establecimiento de la conexión](#connect-api) + [Uso de la captura previa para entregar los detalles del canal](#prefetch) + [Procesamiento de eventos](#process-events) ## Definición de una política de IAM Para empezar, defina una política de IAM que le dé permiso para establecer una WebSocket conexión. El siguiente ejemplo de política otorga un `AppInstanceUser` permiso para establecer una WebSocket conexión. ``` "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action: [ "chime:Connect" ], "Resource": [ "arn:aws:chime:{{region}}:{{{aws_account_id}}}:app-instance/{{{app_instance_id}}}/user/{{{app_instance_user_id}}}" ] }, { "Effect": "Allow", "Action: [ "chime:GetMessagingSessionEndpoint" ], "Resource": [ "*" ] } ] } ``` ## Recuperación del punto de conexión En los siguientes pasos se explica cómo recuperar el punto final utilizado en una WebSocket conexión. 1. Usa la [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html)API para recuperar el WebSocket punto final. 1. Usa la URL devuelta por la [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html)API para crear una WebSocket URL firmada con la versión 4 de Signature. Si necesita ayuda para hacerlo, puede seguir las instrucciones de [Establecimiento de la conexión](#connect-api). **nota** WebSocket Las URL tienen el siguiente formato: `{{id}}.{{region}}.ws-messaging.chime.aws` ## Establecimiento de la conexión Después de recuperar un punto de conexión, utiliza la API de conexión para establecer una WebSocket conexión con el servidor back-end del SDK de Amazon Chime y recibir mensajes para un. `AppInstanceUser` Debe usar la versión 4 de AWS Signature para firmar las solicitudes. Para más información sobre la firma de una solicitud, consulte [Firma de solicitudes de AWS con la versión 4 de la firma](https://docs.aws.amazon.com/general/latest/gr/Signature Version 4_signing.html). **nota** Para recuperar el punto de conexión, puede invocar la API [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html). Puede usar la biblioteca WebSocket cliente que prefiera para conectarse al punto final. **Sintaxis de la solicitud** ``` GET /connect ?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential={{AKIARALLEXAMPLE%2F20201214}}%2F{{region}}%2Fchime%2Faws4_request &X-Amz-Date={{20201214T171359Z}} &X-Amz-Expires={{10}} &X-Amz-SignedHeaders=host &sessionId={{{sessionId}}} &userArn={{{appInstanceUserArn}}} &X-Amz-Signature={{db75397d79583EXAMPLE}} ``` **Parámetros de solicitud del URI** Todos los parámetros de consulta de solicitud de URI deben estar codificados en URL. **X-Amz-Algorithm** Identifica la versión de AWS Signature y el algoritmo que utilizó para calcular la firma. Amazon Chime SDK solo admite la autenticación con la versión 4 de firma de AWS , por lo que su valor es `AWS4-HMAC-SHA256`. **X-Amz-Credential** Además del identificador de la clave de acceso, este parámetro también proporciona la AWS región y el servicio (el ámbito) para los que es válida la firma. Este valor debe coincidir con el ámbito que utilice en los cálculos de la firma. La forma general para el valor de este parámetro es la siguiente: `<{{yourAccessKeyId}}>/<{{date}}>/<{{awsRegion}}>/<{{awsService}} >/aws4_request` Por ejemplo: `AKIAIOSFODNN7EXAMPLE/20201214/us-east-1/chime/aws4_request` **X-Amz-Date** El formato de fecha y hora debe seguir la norma ISO 8601, y tener el formato `yyyyMMddTHHmmssZ`. Por ejemplo, debe convertir **08/01/2020 15:32:41 .982-700** a Hora universal coordinada (UTC) y enviarla como. `20200801T083241Z` **X-Amz-Signed-Headers** Muestra los encabezados que utilizó para calcular la firma. Los siguientes encabezados son obligatorios para los cálculos de firmas: + El encabezado del host HTTP. + Cualquier encabezado x-amz-\* que planee agregar a la solicitud. **nota** Para mayor seguridad, debe firmar todos los encabezados de solicitud que planea incluir en su solicitud. **X-Amz-Signatures** Proporciona la firma para autenticar la solicitud. Esta firma debe coincidir con la firma que calcula Amazon Chime SDK. Si no lo hace, Amazon Chime SDK deniega la solicitud. Por ejemplo, `733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7`. **X-Amz-Security-Token** Parámetro de credenciales opcional si se utilizan credenciales procedentes del servicio de token de seguridad. Para obtener más información sobre el servicio, consulta la. [https://docs.aws.amazon.com/STS/latest/APIReference/](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html) **SessionId** Indica un identificador único para la WebSocket conexión que se está estableciendo. **UserArn** Indica la identidad del `AppInstanceUser` que intenta establecer una conexión. El valor debe ser el ARN de `AppInstanceUser`. Por ejemplo, `arn:aws:chime:{{us%2Deast%2D1}}:{{123456789012}}:app%2Dinstance/{{694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e}}/user/{{johndoe}}` ## Uso de la captura previa para entregar los detalles del canal Al establecer una WebSocket conexión, puede especificar `prefetch-on=connect` en la consulta los parámetros para entregar `CHANNEL_DETAILS` los eventos. La característica de captura previa viene con la API de conexión y permite a los usuarios ver una vista de chat enriquecida sin llamadas a la API adicionales. Los usuarios pueden: + Ver una vista previa del último mensaje del canal, además de su fecha y hora. + Consultar los miembros de un canal. + Consultar los marcadores no leídos de un canal. Cuando un usuario se conecta con el parámetro de captura previa especificado, recibe el evento de sesión establecida, que indica que se ha establecido la conexión. A continuación, el usuario recibe hasta 50 eventos de `CHANNEL_DETAILS`. Si el usuario tiene menos de 50 canales, la API de conexión busca previamente todos los canales mediante eventos de `CHANNEL_DETAILS`. Si el usuario tiene más de 50 canales, la API busca previamente los 50 canales principales que contienen mensajes no leídos y los valores más recientes de `LastMessageTimestamp`. Los eventos de `CHANNEL_DETAILS` aparecen en orden aleatorio y recibe los eventos de los 50 canales. Además, la captura previa devuelve lo siguiente para `ChannelMessages` y `ChannelMemberships`: + **ChannelMessages**: lista de objetos [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html), ordenados por `CreatedTimestamp` en orden descendente. Solo incluye los últimos 20 mensajes visibles para el usuario. Si hay mensajes segmentados en el canal que el usuario actual no puede ver, es posible que se devuelvan menos de 20 mensajes. El booleano `ChannelMessagesHasMore` se establecerá como verdadero para indicar que hay más mensajes. Límite flexible, ajustable a nivel de AWS cuenta. + **ChannelMemberships**: lista de objetos [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html). Incluye un máximo de 30 miembros del canal. Límite flexible, ajustable a nivel de AWS cuenta. En este ejemplo, puede ver cómo usar `prefetch-on=connect`. ``` GET /connect ?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential={{AKIARALLEXAMPLE}}%2F{{20201214}}%2F{{region}}%2Fchime%2Faws4_request &X-Amz-Date={{20201214T171359Z}} &X-Amz-Expires={{10}} &X-Amz-SignedHeaders=host &sessionId={{sessionId}} &prefetch-on=connect &userArn={{appInstanceUserArn}} &X-Amz-Signature={{db75397d79583EXAMPLE}} ``` Este ejemplo muestra la respuesta de un canal. Recibirá respuestas para los 50 canales. ``` { "Headers": { "x-amz-chime-event-type": "CHANNEL_DETAILS", "x-amz-chime-message-type": "SYSTEM" }, "Payload": JSON.stringify"({ Channel: [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html) ChannelMessages: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html) ChannelMemberships: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html ](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html ) ReadMarkerTimestamp: Timestamp ChannelMessagesHasMore: Boolean }) } ``` ## Procesamiento de eventos Para que un `AppInstanceUser` reciba mensajes después de establecer una conexión, debe añadirlos a un canal. Para ello, utilice la API [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html). **nota** Un `AppInstanceUser` siempre recibe mensajes de todos los canales a los que pertenece. La mensajería se detiene cuando el usuario de `AppInstance` se desconecta. Un `AppInstanceAdmin` y un `ChannelModerator` no reciben mensajes en un canal, a menos que utilice la API [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) para añadirlos de forma explícita. En los siguientes temas se explica cómo procesar eventos. **Topics** + [Descripción de las estructuras de los mensajes](#message-structures) + [Gestión de desconexiones](#handle-disconnects) ### Descripción de las estructuras de los mensajes Todos los WebSocket mensajes que recibas siguen este formato: ``` { "Headers": {"{{key}}": "{{value}}"}, "Payload": "{\"{{key}}\": \"{{value}}\"}" } ``` **Encabezados** Los mensajes de Amazon Chime SDK utilizan las siguientes claves de encabezado: + `x-amz-chime-event-type` + `x-amz-chime-message-type` + `x-amz-chime-event-reason` En la siguiente sección, se enumeran y describen los posibles valores y cargas útiles del encabezado. **Carga útil** Los mensajes de Websocket devuelven cadenas JSON. La estructura de las cadenas JSON depende de los encabezados `x-amz-event-type`. En la siguiente tabla se enumeran los posibles valores de `x-amz-chime-event-type` y cargas:
EventTypeFormato de cargas
`SESSION_ESTABLISHED`N/A. Este mensaje se envía una vez que el usuario se conecta al WebSocket. Indica que se garantiza que cualquier mensaje o evento de un canal que llegue después de que el usuario reciba el `SESSION_ESTABLISHED` mensaje se entregará al usuario mientras WebSocket permanezca abierto.
`CREATE_CHANNEL_MESSAGE` [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessage.html)
`REDACT_CHANNEL_MESSAGE`
`UPDATE_CHANNEL_MESSAGE`
`DELETE_CHANNEL_MESSAGE`
`PENDING_CREATE_CHANNEL_MESSAGE`
`PENDING_UPDATE_CHANNEL_MESSAGE`
`FAILED_CREATE_CHANNEL_MESSAGE`
`FAILED_UPDATE_CHANNEL_MESSAGE`
`DENIED_CREATE_CHANNEL_MESSAGE`
`DENIED_UPDATE_CHANNEL_MESSAGE`
`CHANNEL_DETAILS`[See the AWS documentation website for more details](http://docs.aws.amazon.com/es_es/chime-sdk/latest/dg/websockets.html)
`UPDATE_CHANNEL` [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Channel.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Channel.html)
`DELETE_CHANNEL`
`BATCH_CREATE_CHANNEL_MEMBERSHIP` [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_BatchChannelMemberships.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_BatchChannelMemberships.html)
`CREATE_CHANNEL_MEMBERSHIP`[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembership.html)
`DELETE_CHANNEL_MEMBERSHIP`
`UPDATE_CHANNEL_MEMBERSHIP`
**x-amz-chime-message-type** En la tabla siguiente se enumeran los tipos de mensajes de `x-amz-chime-message-type`. | Tipo de mensaje | Description (Descripción) | | --- | --- | | `STANDARD` | Se envía cuando el websocket recibe un mensaje de canal ESTÁNDAR. | | `CONTROL` | Se envía cuando WebSocket recibe un mensaje del canal de CONTROL. | | `SYSTEM` | Todos los demás mensajes de websocket enviados por la mensajería de Amazon Chime SDK. | **x-amz-chime-event-reason** Se trata de un encabezado opcional compatible con un caso de uso específico. El encabezado proporciona información sobre el motivo por el que se recibió un evento específico. | Motivo de evento | Description (Descripción) | | --- | --- | | subchannel\_DELETED | `DELETE_CHANNEL_MEMBERSHIP` eventos recibidos por los moderadores del canal elástico. Los moderadores solo los ven después de equilibrar el número de miembros y eliminar un subcanal al que pertenecían. | ### Gestión de desconexiones Los Websockets se pueden desconectar debido a cambios en la conectividad de la red o cuando las credenciales caduquen. Tras abrir un WebSocket, el SDK de Amazon Chime envía pings periódicos al cliente de mensajería para garantizar que siga conectado. Si la conexión se cierra, el cliente recibe un código de WebSocket cierre. El cliente puede intentar volver a conectarse o no, según el código de cierre. En las siguientes tablas se muestran los códigos de cierre que el cliente puede usar para volver a conectarse. En el caso de códigos de cierre de 1000 a 4000, vuelva a conectarse únicamente para los siguientes mensajes: | Códigos de cierre | Se puede volver a conectar | Motivo | | --- | --- | --- | | 1001 | Sí | Cierre normal | | 1006 | Sí | Cierre anormal | | 1011 | Sí | Error del servidor interno | | 1012 | Sí | Reinicio del servicio | | 1013 | Sí | Inténtelo de nuevo más tarde | | 1014 | Sí | El servidor actuaba como puerta de enlace o proxy y recibió una respuesta no válida del servidor principal. Es similar al código de estado HTTP 502. | En el caso de los códigos 4XXX, vuelve a conectarte siempre, *excepto en el caso* de los siguientes mensajes: | Códigos de cierre | Se puede volver a conectar | Motivo | | --- | --- | --- | | 4002 | No | Iniciado por el cliente | | 4003 | No | Prohibido | | 4401 | No | No tiene autorización | Cuando la aplicación utiliza un código de cierre para volver a conectarse, debe: 1. Vuelva a llamar a la API [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) para obtener una nueva URL base. 1. Actualice las credenciales de IAM si han caducado. 1. Conéctese a través del WebSocket. Si utiliza la biblioteca amazon-chime-sdk-js, esta se gestionará automáticamente si implementa la propiedad [needsRefresh()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#needsRefresh-property) y el método [refresh()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#refresh-property). Para ver un ejemplo práctico, consulte [https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx\# L93-L101](https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx#L93-L101).