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 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:

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.

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.

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:

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:

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:

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.

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:

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:

x-amz-chime-message-tipo

En la tabla siguiente se enumeran los tipos de mensajes de x-amz-chime-message-type.

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.

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:

En el caso de los códigos 4XXX, vuelve a conectarte siempre, excepto en el caso de los siguientes mensajes:

Cuando la aplicación utiliza un código de cierre para volver a conectarse, debe:

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 #L93 -L101.