benutzen WebSockets um Nachrichten zu empfangen - Amazon Chime SDK

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

benutzen WebSockets um Nachrichten zu empfangen

Sie können dasAmazon Chime SDKum Nachrichten zu empfangen mit WebSockets, oder Sie können die verwenden WebSocket Kundenbibliothek Ihrer Wahl.

Folgen Sie diesen Schritten zur Verwendung WebSockets:

Definieren Sie eine IAM-Richtlinie

Definieren Sie zunächst eine IAM-Richtlinie, die Ihnen die Berechtigung zum Einrichten einer WebSocket -Verbindung. Die folgende Beispielrichtlinie gibt eineAppInstanceUserErlaubnis zur Einrichtung einer WebSocket-Verbindung.

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

Abrufen des Endpunkts

In diesen Schritten wird erklärt, wie der in einem WebSocket -Verbindung.

  1. Verwenden der GetMessagingSessionEndpoint API zum Abrufen der WebSocket Endpunkt.

  2. Verwenden Sie die URL, die vom GetMessagingSessionEndpoint API zum Erstellen einer Signature Version 4 Signed WebSocket URL. Wenn Sie dabei Hilfe benötigen, folgen Sie den Anweisungen inStellen Sie die Verbindung heraus.

Stellen Sie die Verbindung her

Nachdem Sie einen Endpunkt abgerufen haben, verwenden Sie die Connect-API, um eine WebSocket Verbindung zum Amazon Chime Back-End-Server herstellen und Nachrichten für eineAppInstanceUseraus. Sie müssen verwendenAWSSignature Version 4 zum Signieren von -Anforderungen. Weitere Informationen zum Signieren einer -Anforderung finden Sie unterSignierenAWSAnforderungen mit Signature Version 4aus.

Anmerkung

Um den Endpunkt abzurufen, können Sie den GetMessagingSessionEndpointAPI. Sie können die Websocket-Clientbibliothek Ihrer Wahl verwenden, um eine Verbindung zum Endpunkt herzustellen.

Anforderungssyntax

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

URI-Anfrageparameter

Alle URI-Anforderungs-Abfrageparameter müssen URL-codiert sein.

X-Amz-Algorithmus

Identifiziert die -VersionAWSSignatur und der Algorithmus, den Sie verwendet haben, um die Signatur zu berechnen. Amazon Chime unterstützt nurAWSSignature Version 4-Authentifizierung, der Wert dieser ist alsoAWS4-HMAC-SHA256aus.

X-Amz-Anmeldeinformationen

Zusätzlich zu Ihrer Zugangsschlüssel-ID liefert dieser Parameter auch dieAWSRegion und Dienst — der Bereich, für den die Signatur gültig ist. Dieser Wert muss mit dem Bereich übereinstimmen, den Sie in Signaturberechnungen verwenden. Die allgemeine Form für diesen Parameterwert lautet:

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

Zum Beispiel:

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

X-Amz-Datum

Das Datums- und Uhrzeitformat muss dem ISO 8601-Standard entsprechen und Sie müssen es formatieren alsyyyyMMddTHHmmssZaus. Beispielsweise müssen Sie konvertieren08.01.2020 15:32:41 .982-700zur Coordinated Universal Time (UTC) und reichen Sie als20200801T083241Zaus.

X-Amaz-Signed-Header

Listet die Header auf, die Sie zur Berechnung der Signatur verwendet haben. Die folgenden Header sind für die Signaturberechnungen erforderlich:

  • Der HTTP-Host-Header.

  • Alle x-amz-*-Header, die Sie der Anfrage hinzufügen möchten.

Anmerkung

Signieren Sie für zusätzliche Sicherheit alle Anforderungsheader, die Sie in Ihre Anfrage aufnehmen möchten.

X-Amz-Signaturen

Stellt die Signatur zur Authentifizierung Ihrer Anfrage bereit. Diese Signatur muss mit der Signatur übereinstimmen, die das Amazon Chime SDK berechnet. Ist dies nicht der Fall, lehnt das Amazon Chime SDK die Anfrage ab. Zum Beispiel 733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7.

X-Amz-Security-Token

Optionaler Anmeldeinformationsparameter, wenn Anmeldeinformationen aus dem Security Token Service verwendet werden. Weitere Informationen über den -Service finden Sie in derhttps://docs.aws.amazon.com/STS/latest/APIReference/aus.

SessionId

Gibt eine eindeutige ID für die Websocket-Verbindung an, die gerade hergestellt wird.

UserArn

Zeigt die Identität desAppInstanceUserversucht, eine Verbindung herzustellen. Der Wert sollte der ARN desAppInstanceUseraus. Zum Beispiel, arn:aws:chime:us%2Deast%2D1:123456789012:app%2Dinstance/694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e/user/johndoe

Verwendung von Prefetch

Wenn Sie eine Websocket-Verbindung herstellen, können Sie Folgendes angeben:prefetch-on=connectin Ihren Abfrageparametern zu liefernCHANNEL_DETAILS-Ereignissen kommen. Die prefectch-Funktion wird mit der Connect-API geliefert, und die Funktion ermöglicht es Benutzern, eine erweiterte Chat-Ansicht ohne zusätzliche API-Aufrufe zu sehen. Benutzer können:

  • Sehen Sie sich eine Vorschau der letzten Kanalnachricht sowie deren Zeitstempel an.

  • Sieh dir die Mitglieder eines Channels an.

  • Sieh dir die ungelesenen Markierungen eines Kanals an.

Nachdem ein Benutzer eine Verbindung mit dem angegebenen Prefetch-Parameter hergestellt hat, erhält der Benutzer das Ereignis session established, das anzeigt, dass die Verbindung hergestellt wurde. Der Benutzer erhält dann bis zu 50CHANNEL_DETAILS-Ereignissen kommen. Wenn der Benutzer weniger als 50 Kanäle hat, ruft die connect API alle Kanäle vorab überCHANNEL_DETAILS-Ereignissen kommen. Wenn der Benutzer mehr als 50 Kanäle hat, ruft die API die 50 häufigsten Kanäle ab, die ungelesene Nachrichten enthalten, und die neuestenLastMessageTimestampwerte. DieCHANNEL_DETAILSEreignisse kommen in zufälliger Reihenfolge an und Sie erhalten Ereignisse für alle 50 Kanäle.

In diesem Beispiel wird Folgendes veranschaulicht:prefetch-on=connectaus.

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

Dieses Beispiel zeigt die Antwort für einen Kanal. Sie erhalten Antworten für alle 50 Kanäle.

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

Verarbeiten der Events

In der entsprechenden ReihenfolgeAppInstanceUserum Nachrichten zu empfangen, nachdem sie eine Verbindung hergestellt haben, müssen Sie sie zu einem Channel hinzufügen. Um das zu tun, benutzen Sie das CreateChannelMembership API.

Anmerkung

Importieren in &S3;AppInstanceUserempfängt immer Nachrichten für alle Kanäle, in denen sie Mitglied sind, solange sie erfolgreich eine Verbindung hergestellt haben.

AndAppInstanceAdminund einChannelModeratorempfangen Sie keine Nachrichten in einem Kanal, es sei denn, Sie verwenden CreateChannelMembership API, um sie explizit hinzuzufügen.

Nachrichtenstrukturen

Alle WebSocket Nachricht, die Sie erhalten, entspricht diesem Format:

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

Header

Amazon Chime SDK-Messaging verwendet einen einzigen Header-Schlüssel,x-amz-chime-event-Typaus. Im nächsten Abschnitt werden die möglichen Werte und Nutzlasten des Headers aufgeführt und beschrieben.

Nutzlast

Websocket-Nachrichten geben JSON-Strings zurück Die Struktur der JSON-Zeichenfolge hängt von derx-amz-event-typeHeader.Die folgende Tabelle listet die möglichenx-amz-chime-event-typeWerte und Nutzlasten:

EventType

Nutzlastformat

SESSION_ESTABLISHED

Nicht zutreffend. Diese Nachricht wird einmal gesendet, nachdem der Benutzer eine Verbindung zum WebSocketaus. Es zeigt an, dass jede Nachricht oder jedes Ereignis in einem Kanal, das eintrifft, nachdem der Benutzer dieSESSION_ESTABLISHEDNachricht wird garantiert an den Benutzer zugestellt, solange die WebSocket bleibt geöffnet.

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

Channel

Das ChannelSummary-Objekt.

ChannelMessages

-Liste vonChannelMessageSummaryObjekte, geordnet nachCreatedTimestampin absteigender Reihenfolge. Enthält die letzten 20 Meldungen, aber Sie können dieses Limit auf AWS-Kontoebene anpassen.

ChannelMemberships

Liste von ChannelMembershipSummary-Objekten. Gibt maximal 30 Channel-Mitglieder zurück, aber Sie können dieses Limit auf AWS-Kontoebene anpassen.

ReadMarkerTimestamp

Die Uhrzeit, zu der derAppInstanceUserhat den Kanal zuletzt als gelesen markiert.

UPDATE_CHANNEL

Channel

DELETE_CHANNEL

BATCH_CREATE_CHANNEL_MEMBERSHIP

BatchChannelMembership

CREATE_CHANNEL_MEMBERSHIP

ChannelMembership

DELETE_CHANNEL_MEMBERSHIP

Umgang mit Verbindungsunterbrechungen

Websockets können aufgrund von Änderungen der Netzwerkkonnektivität oder wenn Anmeldeinformationen ablaufen, getrennt werden. Nachdem Sie eine geöffnet haben WebSocketsendet das Amazon Chime SDK regelmäßig Pings an den Messaging-Client, um sicherzustellen, dass er weiterhin verbunden ist. Wenn die Verbindung geschlossen wird, erhält der Client eine WebSocket Schließen Sie den Code. Je nach Schließcode kann der Client versuchen, die Verbindung wiederherzustellen oder nicht. Die folgenden Tabellen zeigen die Schließcodes, die der Client für die Wiederverbindung verwenden kann.

Bei 1000 bis 4000 Schließcodes nur für die folgenden Meldungen erneut verbinden:

Schließungscodes

Kann die erneute Verbindung

Grund

1001

Ja

Normal Schließen

1006

Ja

Abnormer Verschluss

1011

Ja

Interner Serverfehler

1012

Ja

Dienst neu starten

1013

Ja

Bitte versuchen Sie später erneut

1014

Ja

Der Server agierte als Gateway oder Proxy und erhielt eine ungültige Antwort vom Upstream-Server. Dies ähnelt dem 502-HTTP-Statuscode.

Verbinden Sie sich bei 4XXX-Codes immer erneutaußerfür die folgenden -Meldungen:

Schließungscodes

Kann die erneute Verbindung

Grund

4002

Nein

Klient initied

4003

Nein

Forbidden

4401

Nein

Nicht autorisiert (veraltet)

Wenn die Anwendung einen Close-Code zum Wiederverbinden verwendet, sollte die Anwendung:

  1. Rufen Sie die GetMessagingSessionEndpointerneut, um eine neue Basis-URL zu erhalten.

  2. Aktualisieren Sie die IAM-Anmeldeinformationen, falls sie abgelaufen sind.

  3. Connect (Verbinden) über WebSocketaus.

Wenn Sie das amazon-chime-sdk-js Bibliothek verwenden, wird dies für Sie erledigt, wenn Sie dieBenötigt Refresh ()Eigentum undrefresh () ()-Methode.