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.
Wird WebSockets zum Empfangen von Nachrichten verwendet
Sie können Amazon Chime JS
Folgen Sie diesen Themen in der angegebenen Reihenfolge, um mit der Nutzung WebSockets zu beginnen:
Themen
Definition einer IAM Richtlinie
Definieren Sie zunächst eine IAM Richtlinie, die Ihnen die Erlaubnis gibt, eine WebSocket Verbindung herzustellen. Die folgende Beispielrichtlinie erteilt die AppInstanceUser Erlaubnis, eine WebSocket Verbindung herzustellen.
"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": [ "*" ] } ] }
Der Endpunkt wird abgerufen
In den folgenden Schritten wird erklärt, wie der in einer WebSocket Verbindung verwendete Endpunkt abgerufen wird.
Verwenden der GetMessagingSessionEndpointAPIum den WebSocket Endpunkt abzurufen.
Verwenden Sie den vom URL zurückgegebenen GetMessagingSessionEndpointAPIum eine Signature Version 4 Signed zu erstellen WebSocket URL. Wenn Sie dabei Hilfe benötigen, können Sie den Anweisungen in der folgenDie Verbindung wird hergestellt.
Anmerkung
WebSocket URLshabe das folgende Formular:
id.region.ws-messaging.chime.aws
Die Verbindung wird hergestellt
Nachdem Sie einen Endpunkt abgerufen haben, verwenden Sie die Verbindung, API um eine WebSocket Verbindung zum Amazon Chime SDK Chime-Backend-Server herzustellen und Nachrichten für einen zu empfangen. AppInstanceUser Sie müssen AWS Signature Version 4 verwenden, um Anfragen zu signieren. Weitere Informationen zum Signieren einer Anfrage finden Sie unter Signieren von AWS
Anfragen mit Signature Version 4.
Anmerkung
Um den Endpunkt abzurufen, können Sie den aufrufen GetMessagingSessionEndpointAPI. Sie können die WebSocket Client-Bibliothek 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
URIParameter anfordern
Alle URI Anforderungsabfrageparameter müssen URL codiert sein.
X-Amz-Algorithmus
Identifiziert die Version von AWS Signature und den Algorithmus, den Sie zur Berechnung der Signatur verwendet haben. Amazon Chime SDK unterstützt nur die Authentifizierung mit AWS Signature Version 4, der Wert dieser Option ist AWS4-HMAC-SHA256 also.
X-Amz-Anmeldedaten
Zusätzlich zu Ihrer Zugriffsschlüssel-ID gibt dieser Parameter auch die AWS Region und den Dienst — den Bereich — an, für den die Signatur gültig ist. Dieser Wert muss dem Bereich entsprechen, den Sie bei Signaturberechnungen verwenden. Die allgemeine Form für diesen Parameterwert lautet:
<yourAccessKeyId>/<date>/<awsRegion>/<awsService
>/aws4_request
Beispielsweise:
AKIAIOSFODNN7EXAMPLE/20201214/us-east-1/chime/aws4_request
X-Amz-Date
Das Datums- und Uhrzeitformat muss dem ISO 8601-Standard entsprechen, und Sie müssen es als formatieren. yyyyMMddTHHmmssZ Beispielsweise müssen Sie 08/01/2020 15:32:41.982-700 in die koordinierte Weltzeit () konvertieren und als angeben. UTC 20200801T083241Z
Von X-Amz signierte Header
Listet die Header auf, die Sie zur Berechnung der Signatur verwendet haben. Für die Signaturberechnungen sind folgende Header erforderlich:
Der Host-Header. HTTP
Alle x-amz-*-Header, die Sie der Anfrage hinzufügen möchten.
Anmerkung
Signieren Sie aus Sicherheitsgründen 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 Amazon Chime SDK berechnet. Ist dies nicht der Fall, lehnt Amazon Chime die SDK Anfrage ab. Beispiel, 733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7.
X-Amz-Sicherheitstoken
Optionaler Anmeldeinformationsparameter, wenn Anmeldeinformationen verwendet werden, die vom Security Token Service stammen. Weitere Informationen über den Dienst finden Sie in der https://docs.aws.amazon.com/STS/neuesten APIReference Version von/.
SessionId
Gibt eine eindeutige ID für die WebSocket Verbindung an, die gerade hergestellt wird.
UserArn
Gibt die Identität der Person anAppInstanceUser, die versucht, eine Verbindung herzustellen. Der Wert sollte der ARN von seinAppInstanceUser. Beispiel: arn:aws:chime: us%2Deast%2D1:123456789012:app%2Dinstance/694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e/user/johndoe
Verwenden von Prefetch zur Bereitstellung von Kanaldetails
Wenn Sie eine WebSocket Verbindung herstellen, können Sie prefetch-on=connect in Ihren Abfrageparametern angeben, ob Ereignisse übermittelt werden sollen. CHANNEL_DETAILS Die Prefetch-Funktion ist im Lieferumfang von Connect enthalten und ermöglicht es BenutzernAPI, eine erweiterte Chat-Ansicht ohne zusätzliche API Anrufe zu sehen. Benutzer können:
Eine Vorschau der letzten Kanalnachricht mit ihrem Zeitstempel anzeigen.
Sieh dir die Mitglieder eines Kanals an.
Sieh dir die ungelesenen Markierungen eines Kanals an.
Nachdem ein Benutzer mit dem angegebenen Prefetch-Parameter eine Verbindung hergestellt hat, erhält der Benutzer das Ereignis „Sitzung hergestellt“, das angibt, dass die Verbindung hergestellt wurde. Der Benutzer empfängt dann bis zu 50 CHANNEL_DETAILS Ereignisse. Wenn der Benutzer weniger als 50 Kanäle hat, API ruft Connect alle Kanäle über CHANNEL_DETAILS Ereignisse vorab ab. Wenn der Benutzer über mehr als 50 Kanäle verfügt, werden die 50 wichtigsten Kanäle, API die ungelesene Nachrichten enthalten, sowie die neuesten Werte vorab abgerufen. LastMessageTimestamp Die CHANNEL_DETAILS Ereignisse kommen in zufälliger Reihenfolge an, und Sie erhalten Ereignisse für alle 50 Kanäle.
Außerdem gibt Prefetch für ChannelMessages und Folgendes zurück: ChannelMemberships
ChannelMessages— Liste von ChannelMessageSummaryObjekte, sortiert nach
CreatedTimestampabsteigender Reihenfolge. Enthält nur die letzten 20 Nachrichten, die für den Benutzer sichtbar sind. Wenn der Kanal gezielte Nachrichten enthält, die für den aktuellen Benutzer nicht sichtbar sind, werden möglicherweise weniger als 20 Nachrichten zurückgegeben. DerChannelMessagesHasMoreboolesche Wert wird auf true gesetzt, um anzuzeigen, dass mehr Nachrichten vorhanden sind. Soft-Limit, einstellbar auf AWS Kontoebene.ChannelMemberships— Liste von ChannelMembershipSummaryObjekte. Beinhaltet maximal 30 Kanalmitglieder. Soft-Limit, auf AWS Kontoebene einstellbar.
Dieses Beispiel zeigt, wie man es benutztprefetch-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
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 ChannelMessagesHasMore: Boolean }) }
Bearbeitung der Ereignisse
Damit AppInstanceUser Sie Nachrichten empfangen können, nachdem sie eine Verbindung hergestellt haben, müssen Sie sie zu einem Kanal hinzufügen. Verwenden Sie dazu den CreateChannelMembership API.
Anmerkung
An empfängt AppInstanceUser immer Nachrichten für alle Kanäle, zu denen sie gehören. Die Nachrichtenübermittlung wird beendet, wenn der AppInstance Benutzer die Verbindung trennt.
An AppInstanceAdmin und a empfangen ChannelModerator keine Nachrichten auf einem Kanal, es sei denn, Sie verwenden CreateChannelMembershipAPIum sie explizit hinzuzufügen.
In den folgenden Themen wird erklärt, wie Ereignisse verarbeitet werden.
Grundlegendes zu Nachrichtenstrukturen
Jede WebSocket Nachricht, die Sie erhalten, entspricht diesem Format:
{ "Headers": {"key": "value"}, "Payload": "{\"key\": \"value\"}" }
Überschriften
Amazon Chime SDK Chime-Nachrichten verwenden die folgenden Header-Tasten:
x-amz-chime-event-typex-amz-chime-message-typex-amz-chime-event-reason
Im nächsten Abschnitt werden die möglichen Werte und Payloads des Headers aufgeführt und beschrieben.
Nutzlast
Websocket-Nachrichten geben Zeichenketten zurückJSON. Die Struktur der JSON Zeichenketten hängt von den x-amz-event-type Headern ab. In der folgenden Tabelle sind die möglichen x-amz-chime-event-type Werte und Payloads aufgeführt:
| EventType | Format der Nutzdaten |
|---|---|
|
N/A. Diese Nachricht wird einmal gesendet, nachdem der Benutzer eine Verbindung mit dem hergestellt hat. WebSocket Sie gibt an, dass jede Nachricht oder jedes Ereignis auf einem Kanal, das eingeht, nachdem der Benutzer die |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
x-amz-chime-message-Typ
In der folgenden Tabelle sind die x-amz-chime-message-type Nachrichtentypen aufgeführt.
| Nachrichtentyp | Beschreibung |
|---|---|
|
Wird gesendet, wenn der Websocket eine STANDARD Kanalnachricht empfängt. |
|
Wird gesendet, wenn der eine CONTROL Kanalnachricht WebSocket empfängt. |
|
Alle anderen Websocket-Nachrichten, die von Amazon Chime SDK Messaging gesendet werden. |
x-amz-chime-event-Grund
Dies ist ein optionaler Header, der für einen bestimmten Anwendungsfall unterstützt wird. Der Header enthält Informationen darüber, warum ein bestimmtes Ereignis empfangen wurde.
| Grund des Ereignisses | Beschreibung |
|---|---|
Unterkanal_ DELETED |
|
Umgang mit Verbindungsabbrüchen
Websockets können aufgrund von Änderungen in der Netzwerkkonnektivität oder wenn Anmeldeinformationen ablaufen, getrennt werden. Nachdem Sie einen geöffnet haben WebSocket, SDK sendet Amazon Chime regelmäßig Pings an den Messaging-Client, um sicherzustellen, dass er weiterhin verbunden ist. Wenn die Verbindung geschlossen wird, erhält der Client einen WebSocket Schließcode. Der Client kann je nach Schließcode versuchen, die Verbindung wiederherzustellen oder nicht. In den folgenden Tabellen sind die Schließcodes aufgeführt, mit denen der Client die Verbindung wiederherstellen kann.
Stellen Sie bei den Schließungscodes 1000 bis 4000 die Verbindung nur für die folgenden Meldungen wieder her:
Schließungscodes |
Kann die Verbindung wieder herstellen |
Grund |
|---|---|---|
1001 |
Ja |
Normaler Verschluss |
1006 |
Ja |
Abnormaler Verschluss |
1011 |
Ja |
Interner Serverfehler |
1012 |
Ja |
Dienst neu starten |
1013 |
Ja |
Versuchen Sie es später erneut |
1014 |
Ja |
Der Server fungierte als Gateway oder Proxy und erhielt eine ungültige Antwort vom Upstream-Server. Dies ähnelt dem HTTP 502-Statuscode. |
Stellen Sie bei 4 XXX Codes immer die Verbindung wieder her, mit Ausnahme der folgenden Meldungen:
Schließungscodes |
Kann die Verbindung wieder herstellen |
Grund |
|---|---|---|
4002 |
Nein |
Der Kunde wurde initiiert |
4003 |
Nein |
Forbidden |
4401 |
Nein |
Nicht autorisiert. |
Wenn die Anwendung einen Code zum Schließen verwendet, um die Verbindung wiederherzustellen, sollte die Anwendung:
-
Rufen Sie den GetMessagingSessionEndpointAPInochmal, um eine neue Basis zu bekommenURL.
Aktualisieren Sie die IAM Anmeldeinformationen, falls sie abgelaufen sind.
-
Connect über die WebSocket.
Wenn Sie die amazon-chime-sdk-js Bibliothek verwenden, wird dies für Sie erledigt, wenn Sie die Eigenschaft needsRefresh() und die Methode refresh () implementieren. Ein funktionierendes Beispiel finden Sie unter https://github.com/aws-samples/amazon-chime-sdkAuthProvider/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/
