Protokol klien WebSocket untuk Azure Web PubSub
Klien tersambung ke Azure Web PubSub menggunakan protokol WebSocket standar.
Titik akhir layanan
Layanan Web PubSub ini menyediakan dua jenis titik akhir bagi klien untuk tersambung:
/client/hubs/{hub}
/client/?hub={hub}
{hub}
adalah parameter wajib yang bertindak sebagai isolasi untuk berbagai aplikasi. Anda dapat mengaturnya di jalur atau di kueri.
Otorisasi
Klien tersambung ke layanan dengan JSON Web Token. Token dapat berupa string kueri, sebagai /client/?hub={hub}&access_token={token}
, atau Authorization
header, sebagai Authorization: Bearer {token}
.
Berikut adalah alur kerja otorisasi umum:
- Klien bernegosiasi dengan server aplikasi Anda. Server aplikasi memiliki middleware otorisasi, yang menangani permintaan klien dan menandatangani JWT agar klien tersambung ke layanan.
- Server aplikasi mengembalikan JWT dan URL layanan kepada klien.
- Klien mencoba terhubung ke layanan Web PubSub dengan menggunakan URL dan token JWT yang dikembalikan dari server aplikasi.
Klaim yang didukung
Anda juga dapat mengonfigurasi properti untuk koneksi klien saat membuat token akses dengan menentukan klaim khusus di dalam token JWT:
Deskripsi | Jenis klaim | Nilai klaim | Catatan |
---|---|---|---|
userId untuk koneksi klien |
sub |
userId | Hanya satu sub klaim yang diizinkan. |
Masa pakai token | exp |
waktu kedaluwarsa | Klaim exp (waktu kedaluwarsa) mengidentifikasi waktu kedaluwarsa pada atau setelah itu token TIDAK BOLEH diterima untuk diproses. |
Izin yang awalnya dimiliki koneksi klien | role |
nilai peran yang ditentukan dalam izin | Tentukan beberapa role klaim jika klien memiliki beberapa izin. |
Grup awal yang bergabung dengan koneksi klien setelah tersambung ke Azure Web PubSub | group |
grup untuk bergabung | Tentukan beberapa group klaim jika klien bergabung dengan beberapa grup. |
Anda juga dapat menambahkan klaim kustom ke dalam token akses, dan nilai-nilai ini dipertahankan sebagai claims
properti dalam isi permintaan hulu.
SDK Server menyediakan API untuk menghasilkan token akses untuk klien.
Klien WebSocket sederhana
Klien WebSocket sederhana, seperti yang ditunjukkan oleh penamaannya, yaitu koneksi WebSocket sederhana. Koneksi ini juga memiliki subprotokol kustomnya sendiri.
Misalnya, di JavaScript, Anda dapat membuat klien WebSocket sederhana dengan menggunakan kode berikut:
// simple WebSocket client1
var client1 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');
// simple WebSocket client2 with some custom subprotocol
var client2 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'custom.subprotocol')
Klien WebSocket PubSub
Klien PubSub WebSocket adalah klien WebSocket menggunakan subprotokola yang ditentukan oleh layanan Azure Web PubSub:
json.webpubsub.azure.v1
protobuf.webpubsub.azure.v1
Dengan subprotokol yang didukung layanan, klien PubSub WebSocketdapat langsung memublikasikan pesan ke grup ketika mereka memiliki izin.
json.webpubsub.azure.v1
Subprotokol
Periksa di sini untuk subprotokol JSON secara rinci.
Buat klien PubSub WebSocket
var pubsubClient = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');
Gabung dengan grup dari klien secara langsung
let ackId = 0;
pubsubClient.send(
JSON.stringify({
type: 'joinGroup',
group: 'group1',
ackId: ++ackId
}));
Kirim pesan ke grup dari klien secara langsung
let ackId = 0;
pubsubClient.send(
JSON.stringify({
type: 'sendToGroup',
group: 'group1',
ackId: ++ackId,
dataType: "json",
data: {
"hello": "world"
}
}));
protobuf.webpubsub.azure.v1
Subprotokol
Buffer protokol (protobuf) adalah protokol berbasis biner netral bahasa dan netral platform yang menyederhanakan pengiriman data biner. Protobuf menyediakan alat untuk menghasilkan klien untuk banyak bahasa, seperti Java, Python, Objective-C, C #, dan C ++. Pelajari protobuf selengkapnya.
Misalnya, di JavaScript, Anda dapat membuat klien PubSub WebSocket dengan subprotokol protobuf menggunakan kode berikut:
// PubSub WebSocket client
var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'protobuf.webpubsub.azure.v1');
Periksa di sini untuk subprotokol protobuf secara rinci.
Tanggapan AckId dan Ack
Klien PubSub WebSocket mendukung ackId
properti untuk joinGroup
, leaveGroup
, sendToGroup
dan event
pesan. Saat menggunakan ackId
, Anda dapat menerima pesan respons ack saat permintaan Anda diproses. Anda dapat memilih untuk menghilangkan ackId
dalam skenario aktifkan dan lupakan. Dalam artikel tersebut, kami menjelaskan perbedaan perilaku antara menentukan ackId
atau tidak.
Perilaku ketika ackId
tidak ditentukan
Jika ackId
tidak ditentukan, itu adalah fire-and-forget. Bahkan ada kesalahan saat memperantarai pesan, Anda tidak memiliki cara untuk mendapatkan pemberitahuan.
Perilaku ketika ackId
ditentukan
Publikasi idempoten
ackId
adalah angka uint64 dan harus unik dalam klien dengan ID koneksi yang sama. Layanan Web PubSub merekam ackId
pesan dan dengan pesan yang sama ackId
diperlakukan sebagai pesan yang sama. Layanan menolak untuk menengahi pesan yang sama lebih dari sekali, yang berguna untuk mencoba kembali guna menghindari pesan duplikat. Misalnya, jika klien mengirim pesan dengan ackId=5
dan gagal menerima respons ack dengan ackId=5
, klien akan mencoba lagi dan mengirim pesan yang sama lagi. Dalam beberapa kasus, pesan sudah ditengahi dan respons ack hilang karena alasan tertentu. Layanan menolak coba lagi dan menanggapi respons ack dengan Duplicate
alasan.
Respons Ack
Layanan Web PubSub mengirimkan respons ack untuk setiap permintaan dengan ackId
.
Format:
{
"type": "ack",
"ackId": 1, // The ack id for the request to ack
"success": false, // true or false
"error": {
"name": "Forbidden|InternalServerError|Duplicate",
"message": "<error_detail>"
}
}
ackId
mengaitkan permintaan.success
adalah bool dan menunjukkan apakah permintaan berhasil diproses oleh layanan. Jika itufalse
, klien perlu memeriksaerror
.error
hanya ada saatsuccess
adalahfalse
dan klien harus memiliki logika berbeda untukname
yang berbeda. Anda harus berpikir mungkin ada lebih banyak jenisname
di masa depan.Forbidden
: Klien tidak memiliki izin untuk permintaan tersebut. Klien perlu ditambahkan peran yang relevan.InternalServerError
: Beberapa kesalahan internal terjadi dalam layanan. Percobaan ulang diperlukan.Duplicate
: Pesan denganackId
yang sama telah diproses oleh layanan.
Izin
Seperti yang mungkin telah Anda lihat dalam deskripsi klien PubSub WebSocket sebelumnya, klien dapat menerbitkan ke klien lain hanya jika klien tersebut diberi otorisasi untuk melakukannya. Izin klien dapat diberikan saat tersambung atau selama masa aktif koneksi.
Peran | Izin |
---|---|
Tidak ditentukan | Klien dapat mengirim permintaan peristiwa. |
webpubsub.joinLeaveGroup |
Klien dapat bergabung atau meninggalkan grup mana pun. |
webpubsub.sendToGroup |
Klien dapat menerbitkan pesan ke grup mana pun. |
webpubsub.joinLeaveGroup.<group> |
Klien dapat bergabung atau meninggalkan grup <group> . |
webpubsub.sendToGroup.<group> |
Klien dapat menerbitkan pesan ke grup <group> . |
Izin klien dapat diberikan dalam beberapa cara:
1. Tetapkan peran ke klien saat membuat token akses
Klien dapat terhubung ke layanan menggunakan token JWT. Payload token dapat membawa informasi seperti role
klien. Saat menandatangani token JWT ke klien, Anda dapat memberikan izin kepada klien dengan memberikan peran spesifik klien.
Misalnya, mari tanda tangani token JWT yang memiliki izin untuk mengirim pesan ke group1
dan group2
:
let token = await serviceClient.getClientAccessToken({
roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});
2. Tetapkan peran ke klien dengan penanganan aktivitas connect
Peran klien juga dapat diatur saat penanganan aktivitas connect
terdaftar dan penanganan aktivitas upstram dapat mengembalikan roles
klien ke layanan Web PubSub saat menangani aktivitas connect
.
Misalnya, di JavaScript, Anda dapat mengonfigurasi aktivitas handleConnect
untuk melakukannya:
let handler = new WebPubSubEventHandler("hub1", {
handleConnect: (req, res) => {
// auth the connection and set the userId of the connection
res.success({
roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});
},
});
3. Tetapkan peran kepada klien melalui REST API atau SDK server selama runtime
let service = new WebPubSubServiceClient("<your_connection_string>", "test-hub");
await service.grantPermission("<connection_id>", "joinLeaveGroup", { targetName: "group1" });
Langkah berikutnya
Gunakan sumber daya ini untuk mulai membangun aplikasi Anda sendiri: