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
Siga estos temas en el orden indicado para empezar a WebSockets utilizarlos:
Temas
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.
-
Utilizar GetMessagingSessionEndpointAPI para recuperar el WebSocket punto final.
-
Utilice la URL devuelta por el GetMessagingSessionEndpointAPI para crear una WebSocket URL firmada de la versión 4 de la firma. Si necesita ayuda para hacerlo, puede seguir las instrucciones de Establecimiento de la conexión.
nota
WebSocket URLs tienen el siguiente formulario:
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.
nota
Para recuperar el punto final, puede invocar la GetMessagingSessionEndpointAPI. 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
%2Fregion
%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 la 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 versión más reciente de/. https://docs.aws.amazon.com/STS/ APIReference
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 ChannelMessageSummaryobjetos, ordenados por
CreatedTimestamp
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 booleanoChannelMessagesHasMore
se establecerá como verdadero para indicar que hay más mensajes. Límite flexible, ajustable a nivel de AWS cuenta.ChannelMemberships— Lista de ChannelMembershipSummaryobjetos. 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
%2F20201214
%2Fregion
%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: ChannelSummary ChannelMessages: List of ChannelMessageSummary ChannelMemberships: List of ChannelMembershipSummary 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 el CreateChannelMembershipAPI.
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.
Una AppInstanceAdmin
y otra ChannelModerator
no reciben mensajes en un canal a menos que utilices la CreateChannelMembershipAPI para añadirlos de forma explícita.
En los siguientes temas se explica cómo procesar eventos.
Descripción de las estructuras de los mensajes
Todos los WebSocket mensajes que recibas tienen 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
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:
EventType | Formato de cargas |
---|---|
|
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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
x-amz-chime-message-tipo
En la tabla siguiente se enumeran los tipos de mensajes de x-amz-chime-message-type
.
Tipo de mensaje | Descripción |
---|---|
|
Se envía cuando el websocket recibe un mensaje de canal ESTÁNDAR. |
|
Se envía cuando WebSocket recibe un mensaje del canal CONTROL. |
|
Todos los demás mensajes de websocket enviados por la mensajería de Amazon Chime SDK. |
x-amz-chime-event-motivo
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 | Descripción |
---|---|
subchannel_DELETED |
|
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:
-
Llama al GetMessagingSessionEndpointVuelva a la API para obtener una nueva URL base.
Actualice las credenciales de IAM si han caducado.
-
Conéctese a través del WebSocket.
Si usa la amazon-chime-sdk-js biblioteca, esto se gestiona automáticamente si implementa la propiedad NeedsRefresh () y el método refresh (). Para ver un ejemplo práctico, consulte https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx