Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Menggunakan WebSockets untuk menerima pesan di perpesanan Amazon Chime SDK Anda dapat menggunakan [Amazon Chime JS SDK](https://github.com/aws/amazon-chime-sdk-js) untuk menerima pesan menggunakan WebSockets, atau Anda dapat menggunakan pustaka WebSocket klien pilihan Anda. Ikuti topik ini dalam urutan yang tercantum untuk mulai menggunakan WebSockets: **Topics** + [Mendefinisikan kebijakan IAM](#define-iam-policy) + [Mengambil titik akhir](#retrieve-endpoint) + [Membangun koneksi](#connect-api) + [Menggunakan prefetch untuk menyampaikan detail saluran](#prefetch) + [Memproses acara](#process-events) ## Mendefinisikan kebijakan IAM Untuk memulai, tentukan kebijakan IAM yang memberi Anda izin untuk membuat WebSocket koneksi. Contoh kebijakan berikut memberikan `AppInstanceUser` izin untuk membuat WebSocket koneksi. ``` "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": [ "*" ] } ] } ``` ## Mengambil titik akhir Langkah-langkah berikut menjelaskan cara mengambil titik akhir yang digunakan dalam koneksi WebSocket. 1. Gunakan [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 untuk mengambil titik WebSocket akhir. 1. Gunakan URL yang dikembalikan oleh [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 untuk membuat WebSocket URL Tanda Tangan Versi 4 Tanda Tangan. Jika Anda memerlukan bantuan untuk melakukan itu, Anda dapat mengikuti petunjuk di[Membangun koneksi](#connect-api). **catatan** WebSocket URL memiliki bentuk berikut: `{{id}}.{{region}}.ws-messaging.chime.aws` ## Membangun koneksi Setelah Anda mengambil endpoint, Anda menggunakan connect API untuk membuat WebSocket sambungan ke server back-end Amazon Chime SDK dan menerima pesan untuk file. `AppInstanceUser` Anda harus menggunakan AWS Signature Version 4 untuk menandatangani permintaan. Untuk informasi selengkapnya tentang menandatangani permintaan, lihat [Menandatangani AWS Permintaan dengan Tanda Tangan Versi 4](https://docs.aws.amazon.com/general/latest/gr/Signature Version 4_signing.html). **catatan** Untuk mengambil titik akhir, Anda dapat menjalankan API. [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) Anda dapat menggunakan pustaka WebSocket klien pilihan Anda untuk terhubung ke titik akhir. **Permintaan Sintaks** ``` 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}} ``` **Parameter Permintaan URI** Semua Parameter Kueri Permintaan URI harus dikodekan URL. **X-Amz-Algorithm** Mengidentifikasi versi AWS Signature dan algoritma yang Anda gunakan untuk menghitung tanda tangan. Amazon Chime SDK hanya mendukung otentikasi AWS Signature Version 4, jadi nilainya adalah. `AWS4-HMAC-SHA256` **X-Amz-Credential** Selain ID kunci akses Anda, parameter ini juga menyediakan AWS Wilayah dan layanan—cakupan—yang tanda tangannya valid. Nilai ini harus sesuai dengan cakupan yang Anda gunakan dalam perhitungan tanda tangan. Bentuk umum untuk nilai parameter ini adalah: `<{{yourAccessKeyId}}>/<{{date}}>/<{{awsRegion}}>/<{{awsService}} >/aws4_request` Contoh: `AKIAIOSFODNN7EXAMPLE/20201214/us-east-1/chime/aws4_request` **X-Amz-Date** Format tanggal dan waktu harus mengikuti standar ISO 8601, dan Anda harus memformatnya sebagai. `yyyyMMddTHHmmssZ` Misalnya, Anda harus **08/01mengonversi/2020 15:32:41.982-700** ke Coordinated Universal Time (UTC) dan mengirimkannya sebagai. `20200801T083241Z` **X-Amz-Signed-Headers** Daftar header yang Anda gunakan untuk menghitung tanda tangan. Header berikut diperlukan dalam perhitungan tanda tangan: + Header host HTTP. + Setiap header x-amz-\* yang Anda rencanakan untuk ditambahkan ke permintaan. **catatan** Untuk keamanan tambahan, tandatangani semua header permintaan yang Anda rencanakan untuk disertakan dalam permintaan Anda. **X-Amz-Signatures** Memberikan tanda tangan untuk mengautentikasi permintaan Anda. Tanda tangan ini harus cocok dengan tanda tangan yang dihitung Amazon Chime SDK. Jika tidak, Amazon Chime SDK menolak permintaan tersebut. Misalnya, `733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7`. **X-Amz-Security-Token** Parameter kredensi opsional jika menggunakan kredensil yang bersumber dari Security Token Service. Untuk informasi lebih lanjut tentang layanan, lihat [https://docs.aws.amazon.com/STS/latest/APIReference/](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html). **SessionId** Menunjukkan Id unik untuk WebSocket koneksi yang sedang dibuat. **UserArn** Menunjukkan identitas orang yang `AppInstanceUser` mencoba membuat koneksi. Nilainya harus ARN dari. `AppInstanceUser` Sebagai contoh, `arn:aws:chime:{{us%2Deast%2D1}}:{{123456789012}}:app%2Dinstance/{{694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e}}/user/{{johndoe}}`. ## Menggunakan prefetch untuk menyampaikan detail saluran Saat Anda membuat WebSocket sambungan, Anda dapat menentukan `prefetch-on=connect` parameter kueri untuk mengirimkan `CHANNEL_DETAILS` peristiwa. Fitur prefetch dilengkapi dengan connect API, dan fitur ini memungkinkan pengguna untuk melihat tampilan obrolan yang diperkaya tanpa panggilan API tambahan. Pengguna dapat: + Lihat pratinjau pesan saluran terakhir, ditambah stempel waktunya. + Lihat anggota saluran. + Lihat penanda saluran yang belum dibaca. Setelah pengguna terhubung dengan parameter prefetch yang ditentukan, pengguna menerima acara yang dibuat sesi, yang menunjukkan koneksi telah dibuat. Pengguna kemudian menerima hingga 50 `CHANNEL_DETAILS` acara. Jika pengguna memiliki kurang dari 50 saluran, API connect akan mengambil semua saluran melalui `CHANNEL_DETAILS` acara. Jika pengguna memiliki lebih dari 50 saluran, API akan mengambil 50 saluran teratas yang berisi pesan yang belum dibaca dan nilai terbaru. `LastMessageTimestamp` `CHANNEL_DETAILS`Acara tiba dalam urutan acak, dan Anda menerima acara untuk semua 50 saluran. Juga, prefetch mengembalikan berikut untuk `ChannelMessages` dan: `ChannelMemberships` + **ChannelMessages**— Daftar [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)objek, diurutkan berdasarkan `CreatedTimestamp` urutan menurun. Hanya menyertakan 20 pesan terbaru yang terlihat oleh pengguna. Jika ada pesan yang ditargetkan di saluran yang tidak terlihat oleh pengguna saat ini, maka kurang dari 20 pesan mungkin dikembalikan. `ChannelMessagesHasMore`Boolean akan disetel ke true untuk menunjukkan ada lebih banyak pesan. Batas lunak, dapat disesuaikan di tingkat AWS akun. + **ChannelMemberships**— Daftar [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)objek. Termasuk maksimal 30 anggota saluran. Batas lunak, dapat disesuaikan di tingkat AWS akun. Contoh ini menunjukkan cara menggunakan`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}} ``` Contoh ini menunjukkan respons untuk satu saluran. Anda akan menerima tanggapan untuk semua 50 saluran. ``` { "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 }) } ``` ## Memproses acara `AppInstanceUser`Untuk menerima pesan setelah mereka membuat koneksi, Anda harus menambahkannya ke saluran. Untuk melakukan itu, gunakan [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. **catatan** A `AppInstanceUser` selalu menerima pesan untuk semua saluran milik mereka. Pesan berhenti saat `AppInstance` pengguna terputus. Sebuah `AppInstanceAdmin` dan a `ChannelModerator` tidak menerima pesan di saluran kecuali Anda menggunakan [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 untuk menambahkannya secara eksplisit. Topik berikut menjelaskan cara memproses peristiwa. **Topics** + [Memahami struktur pesan](#message-structures) + [Penanganan terputus](#handle-disconnects) ### Memahami struktur pesan Setiap WebSocket pesan yang Anda terima mematuhi format ini: ``` { "Headers": {"{{key}}": "{{value}}"}, "Payload": "{\"{{key}}\": \"{{value}}\"}" } ``` **Header** Pesan Amazon Chime SDK menggunakan tombol header berikut: + `x-amz-chime-event-type` + `x-amz-chime-message-type` + `x-amz-chime-event-reason` Bagian selanjutnya mencantumkan dan menjelaskan kemungkinan nilai dan muatan header. **Payload** Pesan Websocket mengembalikan string JSON. Struktur string JSON tergantung pada header. `x-amz-event-type` Tabel berikut mencantumkan `x-amz-chime-event-type` nilai dan muatan yang mungkin:
EventTypeFormat muatan
`SESSION_ESTABLISHED`N/A. Pesan ini dikirim sekali setelah pengguna terhubung ke file WebSocket. Ini menunjukkan bahwa setiap pesan atau peristiwa pada saluran yang tiba setelah pengguna menerima `SESSION_ESTABLISHED` pesan dijamin akan dikirim ke pengguna selama WebSocket tetap terbuka.
`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/id_id/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-pesan-tipe** Tabel berikut mencantumkan jenis `x-amz-chime-message-type` pesan. | Jenis pesan | Deskripsi | | --- | --- | | `STANDARD` | Dikirim ketika websocket menerima pesan saluran STANDARD. | | `CONTROL` | Dikirim saat WebSocket menerima pesan saluran KONTROL. | | `SYSTEM` | Semua pesan websocket lainnya yang dikirim oleh Amazon Chime SDK Messaging. | **x-amz-chime-acara-alasan-** Ini adalah header opsional yang didukung untuk kasus penggunaan tertentu. Header memberikan informasi tentang mengapa acara tertentu diterima. | Alasan acara | Deskripsi | | --- | --- | | Subchannel\_Deleted | `DELETE_CHANNEL_MEMBERSHIP`peristiwa yang diterima oleh moderator saluran elastis. Hanya dilihat oleh moderator setelah balancing keanggotaan menghapus sub-saluran milik mereka. | ### Penanganan terputus Websockets dapat terputus karena perubahan konektivitas jaringan, atau ketika kredensil kedaluwarsa. Setelah Anda membuka WebSocket, Amazon Chime SDK mengirimkan ping reguler ke klien perpesanan untuk memastikannya masih terhubung. Jika koneksi ditutup, klien menerima kode WebSocket tutup. Klien dapat mencoba menyambung kembali, atau tidak, tergantung pada kode tutup. Tabel berikut menunjukkan kode tutup yang dapat digunakan klien untuk menyambung kembali. Untuk 1000 hingga 4000 kode penutupan, sambungkan kembali hanya untuk pesan berikut: | Kode penutupan | Dapat menyambung kembali | Alasan | | --- | --- | --- | | 1001 | Ya | Penutupan normal | | 1006 | Ya | Penutupan abnormal | | 1011 | Ya | Kesalahan server internal | | 1012 | Ya | Mulai ulang layanan | | 1013 | Ya | Coba lagi nanti | | 1014 | Ya | Server bertindak sebagai gateway atau proxy dan menerima respons yang tidak valid dari server hulu. Ini mirip dengan Kode Status HTTP 502. | Untuk kode 4XXX, selalu sambungkan kembali *kecuali* untuk pesan berikut: | Kode penutupan | Dapat menyambung kembali | Alasan | | --- | --- | --- | | 4002 | Tidak | Klien diprakarsai | | 4003 | Tidak | Dilarang | | 4401 | Tidak | Tidak diotorisasi | Ketika aplikasi menggunakan kode dekat untuk menyambung kembali, aplikasi harus: 1. Panggil [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 lagi untuk mendapatkan URL dasar baru. 1. Segarkan kredensyal IAM jika sudah kedaluwarsa. 1. Connect melalui WebSocket. [Jika Anda menggunakan library amazon-chime-sdk-js, ini akan ditangani untuk Anda jika Anda menerapkan properti [needsRefresh () dan metode refresh ()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#needsRefresh-property).](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#refresh-property) Untuk contoh kerja, lihat [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).