Definición de una política de IAM Recuperación del punto de conexión Establecimiento de la conexión Uso de la captura previa Procesamiento de eventos

Se utiliza WebSockets para recibir mensajes

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:

Temas

Definición de una política de IAM
Recuperación del punto de conexión
Establecimiento de la conexión
Uso de la captura previa para entregar los detalles del canal
Procesamiento de eventos

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.

Usa la GetMessagingSessionEndpointAPI para recuperar el WebSocket punto final.
Usa la URL devuelta por la GetMessagingSessionEndpointAPI 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.

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 obtener más información sobre la firma de una solicitud, consulte Firmar AWS solicitudes con la versión 4 de la firma.

nota

Para recuperar el punto final, puedes invocar la GetMessagingSessionEndpointAPI. Puede usar la biblioteca de WebSocket clientes 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, consulte https://docs.aws.amazon.com/STS/latest/APIReference/.

SessionId

Indica un identificador único para la conexión que se va a establecer WebSocket .

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 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 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, utiliza la 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.

A AppInstanceAdmin y a ChannelModerator no recibir 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.

Temas

Descripción de las estructuras de los mensajes
Gestión de desconexiones

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
`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`	ChannelMessage
`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`	Canal El objeto ChannelSummary. ChannelMessages Lista de ChannelMessageSummaryobjetos, ordenados por `CreatedTimestamp` orden descendente. Incluye los últimos 20 mensajes, pero puede ajustar ese límite a nivel de cuenta de AWS. ChannelMemberships Lista de objetos ChannelMembershipSummary. Devuelve un máximo de 30 miembros del canal, pero puede ajustar ese límite a nivel de cuenta de AWS. ReadMarkerMarca de tiempo La hora a la que el `AppInstanceUser` marcó el canal como leído por última vez.
`UPDATE_CHANNEL`	Channel
`DELETE_CHANNEL`	Channel
`BATCH_CREATE_CHANNEL_MEMBERSHIP`	BatchChannelMembership
`CREATE_CHANNEL_MEMBERSHIP`	ChannelMembership
`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.	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 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	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:

Vuelva a llamar a la GetMessagingSessionEndpointAPI 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 #L93 -L101.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Uso ExpirationSettings

Configurar los archivos adjuntos