Protokol klien WebSocket untuk Azure Web PubSub

Artikel
03/05/2024

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, sendToGroupdan 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 itu false, klien perlu memeriksa error.
error hanya ada saat success adalah false dan klien harus memiliki logika berbeda untuk name yang berbeda. Anda harus berpikir mungkin ada lebih banyak jenis name 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 dengan ackId 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" });