Utilisation WebSockets pour recevoir des messages

Vous pouvez utiliser le SDK Amazon Chime JS pour recevoir des messages ou utiliser WebSockets la bibliothèque WebSocket cliente de votre choix.

Suivez ces rubriques dans l'ordre indiqué pour commencer à utiliser WebSockets :

Définition d'une politique IAM

Pour commencer, définissez une politique IAM qui vous autorise à établir une WebSocket connexion. L'exemple de politique suivant donne AppInstanceUser l'autorisation d'établir une WebSocket connexion.

"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": [
      "*"
    ]
 }
 ]
} 

Récupération du point de terminaison

Les étapes suivantes expliquent comment récupérer le point de terminaison utilisé dans une WebSocket connexion.

1. Utilisez l'GetMessagingSessionEndpointAPI pour récupérer le WebSocket point de terminaison.

2. Utilisez l'URL renvoyée par l'GetMessagingSessionEndpointAPI pour créer une WebSocket URL signée Signature Version 4. Si vous avez besoin d'aide pour cela, vous pouvez suivre les instructions duÉtablissement de la connexion.

   Note

   WebSocket Les URL ont la forme suivante : id.region.ws-messaging.chime.aws

Établissement de la connexion

Après avoir récupéré un point de terminaison, vous utilisez l'API de connexion pour établir une WebSocket connexion avec le serveur principal du SDK Amazon Chime et recevoir des messages pour un. AppInstanceUser Vous devez utiliser AWS la version 4 de Signature pour signer les demandes. Pour plus d'informations sur la signature d'une demande, voir Signature des AWS demandes avec signature version 4.

Note

Pour récupérer le point de terminaison, vous pouvez appeler l'GetMessagingSessionEndpointAPI. Vous pouvez utiliser la bibliothèque WebSocket client de votre choix pour vous connecter au point de terminaison.

Syntaxe de la demande

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

Paramètres de demande d'URI

Tous les paramètres de requête de demande d'URI doivent être codés en URL.

Algorithme X-Amz

Identifie la version de AWS Signature et l'algorithme que vous avez utilisé pour calculer la signature. Le SDK Amazon Chime prend uniquement en charge l'authentification AWS Signature version 4, ce qui en fait un avantage. AWS4-HMAC-SHA256

Identifiant X-Amz

Outre l'ID de votre clé d'accès, ce paramètre indique également la AWS région et le service (étendue) pour lesquels la signature est valide. Cette valeur doit correspondre à l'étendue que vous utilisez dans les calculs de signature. La forme générale de cette valeur de paramètre est la suivante :

<yourAccessKeyId>/<date>/<awsRegion>/<awsService >/aws4_request

Par exemple :

AKIAIOSFODNN7EXAMPLE/20201214/us-east-1/chime/aws4_request

X-Amz-Date

Le format de date et d'heure doit être conforme à la norme ISO 8601, et vous devez le formater comme yyyyMMddTHHmmssZ suit. Par exemple, vous devez convertir le 01/08/2020 15:32:41.982-700 en temps universel coordonné (UTC) et le soumettre sous le format. 20200801T083241Z

En-têtes signés X-Amz

Répertorie les en-têtes que vous avez utilisés pour calculer la signature. Les en-têtes suivants sont obligatoires pour les calculs de signature :

• L'en-tête de l'hôte HTTP.

• Tous les en-têtes x-amz-* que vous prévoyez d'ajouter à la demande.

Note

Pour plus de sécurité, signez tous les en-têtes de demande que vous comptez inclure dans votre demande.

Signatures X-Amz

Fournit la signature pour authentifier votre demande. Cette signature doit correspondre à celle calculée par le SDK Amazon Chime. Si ce n'est pas le cas, le SDK Amazon Chime refuse la demande. Par exemple, 733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7.

Jeton de sécurité X-Amz

Paramètre d'identification facultatif si vous utilisez des informations d'identification provenant du Security Token Service. Pour plus d'informations sur le service, consultez le site https://docs.aws.amazon.com/STS/latest/APIReference/.

SessionId

Indique un identifiant unique pour la WebSocket connexion en cours d'établissement.

UserArn

Indique l'identité de la AppInstanceUser personne qui tente d'établir une connexion. La valeur doit être l'ARN duAppInstanceUser. Par exemple, arn:aws:chime:us%2Deast%2D1:123456789012:app%2Dinstance/694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e/user/johndoe

Utilisation de prefetch pour fournir des informations sur les chaînes

Lorsque vous établissez une WebSocket connexion, vous pouvez spécifier prefetch-on=connect dans votre requête les paramètres de diffusion des CHANNEL_DETAILS événements. La fonction de prélecture est fournie avec l'API de connexion, et elle permet aux utilisateurs de voir une vue de discussion enrichie sans appels d'API supplémentaires. Les utilisateurs peuvent :

• Consultez un aperçu du dernier message de la chaîne, ainsi que son horodatage.

• Voir les membres d'une chaîne.

• Consultez les marqueurs non lus d'une chaîne.

Une fois qu'un utilisateur s'est connecté avec le paramètre de prélecture spécifié, il reçoit l'événement d'établissement de session, qui indique que la connexion a été établie. L'utilisateur reçoit ensuite jusqu'à 50 CHANNEL_DETAILS événements. Si l'utilisateur possède moins de 50 canaux, l'API de connexion préextrait tous les canaux via CHANNEL_DETAILS des événements. Si l'utilisateur possède plus de 50 canaux, l'API préextrait les 50 principaux canaux contenant des messages non lus et les dernières valeurs. LastMessageTimestamp Les CHANNEL_DETAILS événements arrivent dans un ordre aléatoire et vous recevez des événements pour les 50 chaînes.

De plus, prefetch renvoie les informations suivantes pour ChannelMessages et : ChannelMemberships

• ChannelMessages— Liste des ChannelMessageSummaryobjets, CreatedTimestamp triée par ordre décroissant. Inclut uniquement les 20 derniers messages visibles par l'utilisateur. Si certains messages ciblés du canal ne sont pas visibles pour l'utilisateur actuel, moins de 20 messages peuvent être renvoyés. Le ChannelMessagesHasMore booléen sera défini sur true pour indiquer qu'il y a d'autres messages. Limite souple, ajustable au niveau du AWS compte.

• ChannelMemberships— Liste des ChannelMembershipSummaryobjets Inclut un maximum de 30 membres de la chaîne. Limite souple, ajustable au niveau du AWS compte.

Cet exemple montre comment utiliserprefetch-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

Cet exemple montre la réponse pour un canal. Vous recevrez des réponses pour les 50 chaînes.

{
   "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 
    })
} 

Traitement des événements

Pour qu'un AppInstanceUser homme puisse recevoir des messages après avoir établi une connexion, vous devez les ajouter à une chaîne. Pour cela, utilisez l'CreateChannelMembershipAPI.

Note

An reçoit AppInstanceUser toujours des messages pour tous les canaux auxquels ils appartiennent. La messagerie s'arrête lorsque l'AppInstanceutilisateur se déconnecte.

An AppInstanceAdmin et a ChannelModerator ne reçoivent pas de messages sur un canal, sauf si vous utilisez l'CreateChannelMembershipAPI pour les ajouter explicitement.

Les rubriques suivantes expliquent comment traiter les événements.

Rubriques

• Comprendre les structures des messages
• Gestion des déconnexions

Comprendre les structures des messages

Chaque WebSocket message que vous recevez respecte le format suivant :

{
   "Headers": {"key": "value"},
   "Payload": "{\"key\": \"value\"}"
}

En-têtes

La messagerie du SDK Amazon Chime utilise les clés d'en-tête suivantes :

• x-amz-chime-event-type

• x-amz-chime-message-type

• x-amz-chime-event-reason

La section suivante répertorie et décrit les valeurs et charges utiles possibles de l'en-tête.

Charge utile

Les messages Websocket renvoient des chaînes JSON. La structure des chaînes JSON dépend des x-amz-event-type en-têtes. Le tableau suivant répertorie les x-amz-chime-event-type valeurs et les charges utiles possibles :

EventType	Format de charge utile
SESSION_ESTABLISHED	N/A. Ce message est envoyé une fois que l'utilisateur se connecte au WebSocket. Cela indique que tout message ou événement sur un canal qui arrive après que l'utilisateur a reçu le SESSION_ESTABLISHED message est garanti tant que le canal WebSocket reste ouvert.
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 Objet ChannelSummary. ChannelMessages Liste des ChannelMessageSummaryobjets, CreatedTimestamp triée par ordre décroissant. Inclut les 20 derniers messages, mais vous pouvez ajuster cette limite au niveau du compte AWS. ChannelMemberships Liste d'objets ChannelMembershipSummary. Renvoie un maximum de 30 membres de la chaîne, mais vous pouvez ajuster cette limite au niveau du compte AWS. ReadMarkerHorodatage Heure à laquelle le AppInstanceUser dernier a marqué le canal comme lu.
UPDATE_CHANNEL	Channel
DELETE_CHANNEL
BATCH_CREATE_CHANNEL_MEMBERSHIP	BatchChannelMembership
CREATE_CHANNEL_MEMBERSHIP	ChannelMembership
DELETE_CHANNEL_MEMBERSHIP
UPDATE_CHANNEL_MEMBERSHIP

type de message x-amz-carillon

Le tableau suivant répertorie les types de x-amz-chime-message-type messages.

Type de message	Description
STANDARD	Envoyé lorsque le websocket reçoit un message de canal STANDARD.
CONTROL	Envoyé lorsqu'il WebSocket reçoit un message du canal CONTROL.
SYSTEM	Tous les autres messages Websocket envoyés par Amazon Chime SDK Messaging.

Motif de l'événement X-AMZ-Chime-

Il s'agit d'un en-tête facultatif pris en charge pour un cas d'utilisation spécifique. L'en-tête fournit des informations sur la raison pour laquelle un événement spécifique a été reçu.

Motif de l'événement	Description
Sous-chaîne_supprimée	DELETE_CHANNEL_MEMBERSHIPévénements reçus par les modérateurs d'Elastic Channel. Visible uniquement par les modérateurs une fois que l'équilibrage des membres a supprimé une sous-chaîne à laquelle ils appartenaient.

Gestion des déconnexions

Les Websockets peuvent se déconnecter en raison de modifications de la connectivité réseau ou lorsque les informations d'identification expirent. Après avoir ouvert un WebSocket, le SDK Amazon Chime envoie régulièrement des pings au client de messagerie pour s'assurer qu'il est toujours connecté. Si la connexion se ferme, le client reçoit un code de WebSocket fermeture. Le client peut essayer de se reconnecter ou non, selon le code de fermeture. Les tableaux suivants indiquent les codes de fermeture que le client peut utiliser pour se reconnecter.

Pour 1 000 à 4 000 codes de fermeture, reconnectez-vous uniquement pour les messages suivants :

Codes de fermeture	Peut se reconnecter	Raison
1001	Oui	Fermeture normale
1006	Oui	Fermeture anormale
1011	Oui	Erreur interne du serveur
1012	Oui	Redémarrage du service
1013	Oui	Réessayez plus tard
1014	Oui	Le serveur agissait en tant que passerelle ou proxy et a reçu une réponse non valide du serveur en amont. Ceci est similaire au code d'état HTTP 502.

Pour les codes 4XXX, reconnectez-vous toujours, à l'exception des messages suivants :

Codes de fermeture	Peut se reconnecter	Raison
4002	Non	Initié par le client
4003	Non	Accès interdit
4401	Non	Non autorisé

Lorsque l'application utilise un code de fermeture pour se reconnecter, elle doit :

1. Appelez à nouveau l'GetMessagingSessionEndpointAPI pour obtenir une nouvelle URL de base.

2. Actualisez les informations d'identification IAM si elles ont expiré.

3. Connect via le WebSocket.

Si vous utilisez la amazon-chime-sdk-js bibliothèque, cela est géré pour vous si vous implémentez la propriété needsRefresh () et la méthode refresh (). Pour un exemple pratique, consultez https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/ AuthProvider .jsx #L93 -L101.