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 verwendet WebSockets , um Nachrichten im Amazon Chime SDK-Messaging zu empfangen Sie können das [Amazon Chime JS SDK](https://github.com/aws/amazon-chime-sdk-js) verwenden, um Nachrichten zu empfangen WebSockets, oder Sie können die WebSocket Client-Bibliothek Ihrer Wahl verwenden. Folgen Sie diesen Themen in der angegebenen Reihenfolge, um mit der Nutzung WebSockets zu beginnen: **Topics** + [Definition einer IAM-Richtlinie](#define-iam-policy) + [Der Endpunkt wird abgerufen](#retrieve-endpoint) + [Die Verbindung wird hergestellt](#connect-api) + [Verwenden von Prefetch zur Bereitstellung von Kanaldetails](#prefetch) + [Bearbeitung der Ereignisse](#process-events) ## 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. 1. Verwenden Sie die [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html)API, um den WebSocket Endpunkt abzurufen. 1. Verwenden Sie die von der [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html)API zurückgegebene URL, um eine signierte Signature Version WebSocket 4-URL zu erstellen. Wenn Sie dabei Hilfe benötigen, können Sie den Anweisungen in der folgen[Die Verbindung wird hergestellt](#connect-api). **Anmerkung** WebSocket URLs haben die folgende Form: `{{id}}.{{region}}.ws-messaging.chime.aws` ## Die Verbindung wird hergestellt Nachdem Sie einen Endpunkt abgerufen haben, verwenden Sie die Connect-API, um eine WebSocket Verbindung zum Amazon Chime SDK-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.](https://docs.aws.amazon.com/general/latest/gr/Signature Version 4_signing.html) **Anmerkung** Um den Endpunkt abzurufen, können Sie die [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html)API aufrufen. 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}}%2F{{region}}%2Fchime%2Faws4_request &X-Amz-Date={{20201214T171359Z}} &X-Amz-Expires={{10}} &X-Amz-SignedHeaders=host &sessionId={{{sessionId}}} &userArn={{{appInstanceUserArn}}} &X-Amz-Signature={{db75397d79583EXAMPLE}} ``` **URI-Anforderungsparameter** Alle URI-Anforderungsabfrageparameter müssen URL-codiert sein. **X-Amz-Algorithm** Identifiziert die Version von AWS Signature und den Algorithmus, den Sie zur Berechnung der Signatur verwendet haben. Das Amazon Chime SDK unterstützt nur die Authentifizierung mit AWS Signature Version 4, der Wert dieser Option ist `AWS4-HMAC-SHA256` also. **X-Amz-Credential** Neben Ihrer Zugriffsschlüssel-ID gibt dieser Parameter auch die AWS Region und den Service — 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` Beispiel: `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 `yyyyMMddTHHmmssZ` formatieren. Beispielsweise müssen Sie **08/01/2020 15:32:41.982-700** in die koordinierte Weltzeit (UTC) konvertieren und als angeben. `20200801T083241Z` **X-Amz-Signed-Headers** Listet die Header auf, die Sie zur Berechnung der Signatur verwendet haben. Für die Signaturberechnungen sind folgende Header erforderlich: + Der HTTP-Host-Header. + 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-Signatures** 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. Beispiel, `733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7`. **X-Amz-Security-Token** Optionaler Anmeldeinformationsparameter, wenn Anmeldeinformationen verwendet werden, die vom Security Token Service stammen. Weitere Informationen über den Dienst finden Sie unter [https://docs.aws.amazon.com/STS/latest/APIReference/](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html). **SessionId** Gibt eine eindeutige ID für die WebSocket Verbindung an, die gerade hergestellt wird. **UserArn** Gibt die Identität der Person an`AppInstanceUser`, die versucht, eine Verbindung herzustellen. Der Wert sollte der ARN von sein`AppInstanceUser`. 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 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: + 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, ruft die Connect-API alle Kanäle über `CHANNEL_DETAILS` Ereignisse vorab ab. Wenn der Benutzer mehr als 50 Kanäle hat, ruft die API die 50 wichtigsten Kanäle, die ungelesene Nachrichten enthalten, und die neuesten Werte vorab ab. `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 der [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html)Objekte, sortiert nach absteigender `CreatedTimestamp` 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. Der `ChannelMessagesHasMore` boolesche Wert wird auf true gesetzt, um anzuzeigen, dass mehr Nachrichten vorhanden sind. Soft-Limit, einstellbar auf AWS Kontoebene. + **ChannelMemberships**— Liste der [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html)Objekte. Beinhaltet maximal 30 Kanalmitglieder. Soft-Limit, auf AWS Kontoebene einstellbar. Dieses Beispiel zeigt, wie man es benutzt`prefetch-on=connect`. ``` GET /connect ?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential={{AKIARALLEXAMPLE}}%2F{{20201214}}%2F{{region}}%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: [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html) ChannelMessages: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html) ChannelMemberships: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html ](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html ) 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 die [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)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 die [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)API, um sie explizit hinzuzufügen. In den folgenden Themen wird erklärt, wie Ereignisse verarbeitet werden. **Topics** + [Grundlegendes zu Nachrichtenstrukturen](#message-structures) + [Umgang mit Verbindungsabbrüchen](#handle-disconnects) ### Grundlegendes zu Nachrichtenstrukturen Jede WebSocket Nachricht, die Sie erhalten, entspricht diesem Format: ``` { "Headers": {"{{key}}": "{{value}}"}, "Payload": "{\"{{key}}\": \"{{value}}\"}" } ``` **Kopfzeilen** Amazon Chime SDK-Nachrichten verwenden die folgenden Header-Schlüssel: + `x-amz-chime-event-type` + `x-amz-chime-message-type` + `x-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 JSON-Strings zurück. Die Struktur der JSON-Strings 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:
EventTypeNutzdatenformat
`SESSION_ESTABLISHED`N/A. Diese Nachricht wird einmal gesendet, nachdem der Benutzer eine Verbindung mit dem hergestellt hat WebSocket. Es gibt an, dass jede Nachricht oder jedes Ereignis auf einem Kanal, das eingeht, nachdem der Benutzer die `SESSION_ESTABLISHED` Nachricht erhalten hat, dem Benutzer garantiert zugestellt wird, solange sie geöffnet WebSocket bleibt.
`CREATE_CHANNEL_MESSAGE` [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessage.html)
`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`[See the AWS documentation website for more details](http://docs.aws.amazon.com/de_de/chime-sdk/latest/dg/websockets.html)
`UPDATE_CHANNEL` [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Channel.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Channel.html)
`DELETE_CHANNEL`
`BATCH_CREATE_CHANNEL_MEMBERSHIP` [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_BatchChannelMemberships.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_BatchChannelMemberships.html)
`CREATE_CHANNEL_MEMBERSHIP`[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembership.html)
`DELETE_CHANNEL_MEMBERSHIP`
`UPDATE_CHANNEL_MEMBERSHIP`
**X-AMZ-Chime-Nachrichtentyp** In der folgenden Tabelle sind die Nachrichtentypen aufgeführt. `x-amz-chime-message-type` | Nachrichtentyp | Description | | --- | --- | | `STANDARD` | Wird gesendet, wenn der Websocket eine STANDARD-Kanalnachricht empfängt. | | `CONTROL` | Wird gesendet, wenn der eine WebSocket CONTROL-Kanalnachricht empfängt. | | `SYSTEM` | Alle anderen Websocket-Nachrichten, die von Amazon Chime SDK Messaging gesendet werden. | **x-amz-chime-Grund für das Ereignis** 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 | Description | | --- | --- | | SubChannel\_Deleted | `DELETE_CHANNEL_MEMBERSHIP`Ereignisse, die von Elastic Channel-Moderatoren empfangen wurden. Moderatoren werden nur angezeigt, nachdem der Mitgliederausgleich einen Unterkanal gelöscht hat, dem sie angehört haben. | ### Umgang mit Verbindungsabbrüchen Websockets können aufgrund von Änderungen in der Netzwerkkonnektivität oder wenn Anmeldeinformationen ablaufen, getrennt werden. Nachdem Sie eine geöffnet haben WebSocket, sendet 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 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 502-HTTP-Statuscode. | Stellen Sie bei 4XXX-Codes immer wieder eine Verbindung 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: 1. Rufen Sie die [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html)API erneut auf, um eine neue Basis-URL zu erhalten. 1. Aktualisieren Sie die IAM-Anmeldeinformationen, falls sie abgelaufen sind. 1. 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 ()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#needsRefresh-property) implementieren.](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#refresh-property) [Ein funktionierendes Beispiel finden Sie unter \#. https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx L93-L101](https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx#L93-L101)