Utilisation WebSockets pour recevoir des messages dans la messagerie du SDK Amazon Chime

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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.

É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.

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 ne prend en charge que 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 :

Signatures X-Amz

Fournit la signature pour authentifier votre demande. Cette signature doit correspondre à la signature calculée par le SDK Amazon Chime. Dans le cas contraire, 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 service de jeton de sécurité. Pour plus d'informations sur le service, consultez le https://docs.aws.amazon.com/STS/dernier//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 :

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

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 ce faire, utilisez le CreateChannelMembershipAPI.

An AppInstanceAdmin et a ChannelModerator ne reçoivent pas de messages sur une chaîne, sauf si vous utilisez le CreateChannelMembershipAPI pour les ajouter explicitement.

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

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 :

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 :

x-amz-chime-message-type

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

x-amz-chime-event-raison

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.

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 :

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

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

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.