Layanan Azure Web PubSub internal

Artikel
06/01/2023

Layanan Azure Web PubSub menyediakan cara mudah untuk menerbitkan/berlangganan pesan menggunakan koneksi WebSocket yang sederhana.

Klien dapat ditulis dalam bahasa apa pun yang memiliki dukungan Websocket.
Pesan teks dan biner didukung dalam satu koneksi.
Ada protokol sederhana bagi klien untuk melakukan penerbitan pesan klien-ke-klien langsung.
Layanan ini mengelola koneksi WebSocket untuk Anda.

Syarat

Layanan: Layanan Azure Web PubSub.

Koneksi: Koneksi, juga disebut klien atau koneksi klien, mewakili setiap koneksi WebSocket yang terhubung ke layanan Web PubSub. Jika berhasil terhubung, ID koneksi unik ditetapkan ke koneksi ini oleh layanan Web PubSub.
Hub: Hub adalah konsep logis untuk set koneksi klien. Biasanya Anda menggunakan satu hub untuk satu skenario, misalnya, hub obrolan , atau hub pemberitahuan . Ketika koneksi klien tersambung, koneksi terhubung ke hub, dan selama masa pakainya itu milik hub tersebut. Setelah koneksi klien tersambung ke hub, hub ada. Aplikasi yang berbeda dapat berbagi satu layanan Azure Web PubSub dengan menggunakan nama hub yang berbeda. Meskipun tidak ada batasan ketat pada jumlah hub, hub menggunakan lebih banyak beban layanan yang dibandingkan dengan grup. Disarankan untuk memiliki sekumpulan hub yang telah ditentukan daripada menghasilkannya secara dinamis.
Grup: Grup adalah subset koneksi ke hub. Anda dapat menambahkan koneksi klien ke grup atau menghapus koneksi klien dari grup kapan saja Anda inginkan. Misalnya, saat klien bergabung dengan ruang obrolan atau saat klien keluar dari ruang obrolan, ruang obrolan semacam itu bisa menjadi grup. Klien dapat bergabung dengan beberapa grup, dan grup dapat berisi beberapa klien. Grup ini seperti "sesi" grup, sesi grup dibuat setelah seseorang bergabung dengan grup, dan sesi hilang ketika tidak ada orang dalam grup. Pesan yang dikirim ke grup dikirimkan ke semua klien yang tersambung ke grup.
Pengguna: Satu pengguna bisa memiliki beberapa koneksi ke Web PubSub. Pengguna mungkin memiliki beberapa koneksi, misalnya saat satu pengguna terhubung di beberapa perangkat atau beberapa tab browser.
Pesan: Saat terhubung, klien dapat mengirim pesan ke aplikasi upstram atau menerima pesan dari aplikasi upstram melalui koneksi WebSocket. Pesan dapat dalam format teks biasa, biner, atau JSON dan memiliki ukuran maksimum 1 MB.
Koneksi Klien dan ConnectionId: klien tersambung ke titik akhir /client, ketika tersambung, connectionId yang unik dihasilkan oleh layanan sebagai identitas yang unik dari koneksi klien. Pengguna kemudian dapat mengelola koneksi klien menggunakan connectionId ini. Detail dijelaskan di bagian Protokol klien .
Acara Klien: Acara dibuat selama siklus hidup koneksi klien. Misalnya, koneksi klien WebSocket sederhana membuat acara connect ketika mencoba untuk terhubung ke layanan, acara connected ketika berhasil terhubung ke layanan, acara message ketika mengirim pesan ke layanan dan acara disconnected ketika terputus dari layanan. Detail tentang peristiwa klien diilustrasikan di bagian Protokol klien.
Handler Acara: Handler acara berisi logika untuk menangani acara klien. Daftarkan dan konfigurasikan handler acara dalam layanan melalui portal atau Azure CLI sebelumnya. Detail dijelaskan di bagian Penanganan aktivitas.
Event Listener(pratinjau): Pendengar peristiwa hanya mendengarkan peristiwa klien tetapi tidak dapat mengganggu masa pakai klien Anda melalui respons mereka. Detail dijelaskan di bagian Pendengar peristiwa.
Server: Server dapat menangani peristiwa klien, mengelola koneksi klien, atau menerbitkan pesan ke grup. Penanganan aktivitas dan pendengar peristiwa dianggap sebagai sisi server. Detail tentang server dijelaskan di bagian Protokol server.

Alur kerja

Diagram showing the Web PubSub service workflow.

Alur kerja seperti yang diperlihatkan dalam grafik di atas:

Klient tersambung ke layanan titik akhir /client menggunakan transpor WebSocket. Layanan meneruskan setiap bingkai WebSocket ke (server) induk yang dikonfigurasi. Koneksi WebSocket dapat terhubung dengan subprotokol kustom apa pun untuk ditangani server, atau dapat terhubung dengan json.webpubsub.azure.v1 subprotokol yang didukung layanan, yang memberdayakan klien untuk melakukan pub/sub secara langsung. Detailnya dijelaskan di bagian protokol klien.
Pada peristiwa klien yang berbeda, layanan memanggil server menggunakan protokol CloudEvents. CloudEvents adalah definisi standar dan protokol-agnostik dari deskripsi struktur dan metadata acara yang dihosting oleh Cloud Native Computing Foundation (CNCF). Implementasi terperinci protokol CloudEvents bergantung pada peran server, yang dijelaskan dalam protokol server.
Server Web PubSub dapat memanggil layanan menggunakan REST API untuk mengirim pesan ke klien atau untuk mengelola klien yang terhubung. Detailnya dijelaskan di bagian protokol server

Protokol klien

Koneksi klien tersambung ke titik akhir /client dari layanan menggunakan protokol WebSocket. Protokol WebSocket menyediakan saluran komunikasi dua arah secara bersamaan melalui koneksi TCP tunggal dan distandarisasi oleh IETF sebagai RFC 6455 pada tahun 2011. Sebagian besar bahasa memiliki dukungan asli untuk memulai koneksi WebSocket.

Layanan kami mendukung dua jenis klien:

Yang pertama disebut klien WebSocket sederhana
Yang kedua disebut klien WebSocket PubSub

Klien WebSocket sederhana

Klien WebSocket sederhana, seperti yang ditunjukkan oleh penamaannya, yaitu koneksi WebSocket sederhana. Koneksi ini juga memiliki subprotokol kustomnya sendiri.

Misalnya, di JS, klien WebSocket sederhana dapat dibuat 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 sederhana mengikuti arsitektur server klien<>, seperti yang ditunjukkan oleh diagram urutan di bawah ini: Diagram showing the sequence for a client connection.

Ketika klien memulai jabat tangan WebSocket, layanan mencoba memanggil connect penanganan aktivitas untuk jabat tangan WebSocket. Pengembang dapat menggunakan handler ini untuk menangani jabat tangan WebSocket, menentukan subprotokola untuk digunakan, mengautentikasi klien, dan bergabung dengan klien ke grup.
Ketika klien berhasil tersambung, layanan memanggil handler acara connected. Ini berfungsi sebagai pemberitahuan dan tidak memblokir klien untuk mengirim pesan. Pengembang dapat menggunakan handler ini untuk melakukan penyimpanan data dan dapat merespons dengan pesan ke klien. Layanan ini juga mendorong connected peristiwa ke semua pendengar peristiwa, jika ada.
Saat klien mengirim pesan, layanan memicu message peristiwa ke penanganan aktivitas untuk menangani pesan yang dikirim. Acara ini adalah acara umum yang berisi pesan yang dikirim dalam bingkai WebSocket. Kode Anda perlu mengirimkan pesan di dalam penanganan aktivitas ini. Jika penanganan aktivitas mengembalikan kode respons yang tidak berhasil, layanan akan menghilangkan koneksi klien. Layanan ini juga mendorong message peristiwa ke semua pendengar peristiwa, jika ada. Jika layanan tidak dapat menemukan server terdaftar untuk menerima pesan, layanan juga menghilangkan koneksi.
Ketika klien terputus, layanan mencoba memicu disconnected peristiwa ke penanganan aktivitas setelah mendeteksi pemutusan sambungan. Layanan ini juga mendorong disconnected peristiwa ke semua pendengar peristiwa, jika ada.

Skenario

Koneksi ini dapat digunakan dalam arsitektur server klien yang khas di mana klien mengirim pesan ke server dan server menangani pesan masuk menggunakan Penanganan Aktivitas. Koneksi tersebut juga dapat digunakan ketika pelanggan menerapkan subprotokol yang ada di logika aplikasi mereka.

Klien WebSocket PubSub

Layanan ini juga mendukung subprotokol tertentu yang disebut json.webpubsub.azure.v1, yang memberdayakan klien untuk melakukan penerbitan/berlangganan secara langsung daripada melakukan komunikasi dua arah ke server induk. Kami menyebut koneksi WebSocket dengan subprotokol json.webpubsub.azure.v1 klien WebSocket PubSub. Untuk informasi selengkapnya, lihat spesifikasi klien Web PubSub di GitHub.

Misalnya, di JS, klien WebSocket PubSub dapat dibuat menggunakan kode berikut.

// PubSub WebSocket client
var pubsub = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);

Klien WebSocket PubSub dapat:

Bergabung dengan grup, misalnya:

{
  "type": "joinGroup",
  "group": "<group_name>"
}

Keluar dari grup, misalnya:

{
  "type": "leaveGroup",
  "group": "<group_name>"
}

Menerbitkan pesan ke grup, misalnya:

{
  "type": "sendToGroup",
  "group": "<group_name>",
  "data": { "hello": "world" }
}

Mengirim acara kustom ke server induk, misalnya:

{
  "type": "event",
  "event": "<event_name>",
  "data": { "hello": "world" }
}

Subprotokol WebSocket PubSub berisi detail tentang subprotokol json.webpubsub.azure.v1.

Anda mungkin telah memperhatikan bahwa untuk klien WebSocket sederhana, server harus memiliki peran untuk menerima message peristiwa dari klien. Koneksi WebSocket sederhana selalu memicu peristiwa message saat mengirim pesan, dan selalu mengandalkan sisi server untuk memproses pesan dan melakukan operasi lain. Dengan bantuan subprotokol json.webpubsub.azure.v1, klien yang berwenang dapat bergabung dengan grup dan menerbitkan pesan ke grup secara langsung. Ini juga dapat merutekan pesan ke penanganan aktivitas / pendengar peristiwa yang berbeda dengan menyesuaikan peristiwa tempat pesan berada.

Skenario

Klien seperti itu dapat digunakan ketika klien ingin berkomunikasi dengan satu sama lain. Pesan dikirim dari client2 ke layanan dan layanan menyampaikan pesan secara langsung ke client1 jika klien berwenang untuk melakukannya.

Klien1:

var client1 = new WebSocket(
  "wss://xxx.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);
client1.onmessage = (e) => {
  if (e.data) {
    var message = JSON.parse(e.data);
    if (message.type === "message" && message.group === "Group1") {
      // Only print messages from Group1
      console.log(message.data);
    }
  }
};

client1.onopen = (e) => {
  client1.send(
    JSON.stringify({
      type: "joinGroup",
      group: "Group1",
    })
  );
};

Klien2:

var client2 = new WebSocket("wss://xxx.webpubsub.azure.com/client/hubs/hub1", "json.webpubsub.azure.v1");
client2.onopen = e => {
    client2.send(JSON.stringify({
        type: "sendToGroup",
        group: "Group1",
        data: "Hello Client1"
    });
};

Seperti yang ditampilkan contoh di atas, client2 mengirim data secara langsung ke client1 dengan menerbitkan pesan ke Group1 yang client1 berada.

Ringkasan peristiwa klien

Peristiwa klien termasuk dalam dua kategori:

Peristiwa sinkron (pemblokiran) Peristiwa sinkron memblokir alur kerja klien.
- connect: Kejadian ini hanya untuk penanganan aktivitas. Ketika klien memulai jabat tangan WebSocket, peristiwa dipicu dan pengembang dapat menggunakan connect penanganan aktivitas untuk menangani jabat tangan WebSocket, menentukan subprotokola untuk digunakan, mengautentikasi klien, dan bergabung dengan klien ke grup.
- message: Kejadian ini dipicu saat klien mengirim pesan.
Peristiwa asinkron (non-pemblokiran) Peristiwa asinkron tidak memblokir alur kerja klien, ini bertindak sebagai beberapa pemberitahuan ke server. Ketika pemicu acara seperti itu gagal, layanan mencatat detail kesalahan.
- connected: Kejadian ini dipicu ketika klien berhasil terhubung ke layanan.
- disconnected: Peristiwa ini dipicu ketika klien terputus dengan layanan.

Batas pesan klien

Ukuran pesan maksimum yang diizinkan untuk satu bingkai WebSocket adalah 1MB.

Autentikasi Klien

Alur kerja autentikasi

Klien menggunakan token JWT yang ditandatangani untuk terhubung ke layanan. Upstream juga dapat menolak klien saat connect menjadi penanganan aktivitas klien yang masuk. Penanganan aktivitas mengautentikasi klien dengan menentukan userId dan roleyang dimiliki klien dalam respons webhook, atau menolak klien dengan 401. Bagian handler acara menjelaskannya secara detail.

Grafik berikut menjelaskan alur kerja.

Diagram showing the client authentication workflow.

Seperti yang mungkin telah Anda perhatikan ketika kami menjelaskan klien PubSub WebSocket, bahwa klien dapat menerbitkan ke klien lain hanya ketika diotorisasi . role klien menentukan izin awal yang dimiliki klien:

Role	Izin
Tidak ditentukan	Klien dapat mengirimkan acara.
`webpubsub.joinLeaveGroup`	Klien dapat bergabung/meninggalkan grup mana pun.
`webpubsub.sendToGroup`	Klien dapat menerbitkan pesan ke grup mana pun.
`webpubsub.joinLeaveGroup.<group>`	Klien dapat bergabung/keluar dari grup `<group>`.
`webpubsub.sendToGroup.<group>`	Klien dapat menerbitkan pesan ke grup `<group>`.

Sisi server juga dapat memberikan atau mencabut izin klien secara dinamis melalui protokol server seperti yang digambarkan pada bagian nanti.

Protokol server

Protokol server menyediakan fungsionalitas bagi server untuk menangani peristiwa klien dan mengelola koneksi klien dan grup.

Secara umum, protokol server berisi tiga peran:

Handler acara
Manajer sambungan
Pendengar peristiwa

Handler acara

Handler acara menangani acara klien yang masuk. Penanganan aktivitas didaftarkan dan dikonfigurasi dalam layanan melalui portal atau Azure CLI. Ketika peristiwa klien dipicu, layanan dapat mengidentifikasi apakah peristiwa tersebut akan ditangani atau tidak. Sekarang kita menggunakan PUSH mode untuk memanggil penanganan aktivitas. Penanganan aktivitas di sisi server mengekspos titik akhir yang dapat diakses publik agar layanan dipanggil saat peristiwa dipicu. Mode tersebut bertindak sebagai webhook.

Layanan Web PubSub mengirimkan peristiwa klien ke webhook upstream menggunakan protokol HTTP CloudEvents.

Untuk setiap peristiwa, layanan merumuskan permintaan HTTP POST ke upstream terdaftar dan mengharapkan respons HTTP.

Data yang dikirim dari layanan ke server selalu dalam format CloudEvents binary .

Diagram showing the Web PubSub service event push mode.

Induk dan Validasi

Penanganan aktivitas perlu didaftarkan dan dikonfigurasi dalam layanan melalui portal atau Azure CLI sebelum digunakan terlebih dahulu. Ketika peristiwa klien dipicu, layanan dapat mengidentifikasi apakah peristiwa harus ditangani atau tidak. Untuk pratinjau publik, kami menggunakan PUSH mode untuk memanggil penanganan aktivitas. Penanganan aktivitas di sisi server mengekspos titik akhir yang dapat diakses publik agar layanan dapat dipanggil saat peristiwa dipicu. Ini bertindak sebagai upstream webhook.

URL dapat menggunakan {event} parameter untuk menentukan templat URL untuk handler webhook. Layanan ini menghitung nilai URL webhook secara dinamis ketika permintaan klien masuk. Misalnya, ketika permintaan /client/hubs/chat masuk dengan pola URL handler acara yang dikonfigurasikan http://host.com/api/{event} untuk hub chat, ketika klien tersambung permintan tersebut pertama-tama akan MEMPOSTING ke URL ini: http://host.com/api/connect. Perilaku ini dapat berguna ketika klien WebSocket PubSub mengirim peristiwa kustom, bahwa penanganan aktivitas membantu mengirimkan peristiwa yang berbeda ke upstream yang berbeda. Parameter {event} tidak diizinkan dalam nama domain URL.

Saat menyiapkan handler acara di induk melalui portal Azure atau CLI, layanan ini mengikuti perlindungan penyalahgunaan CloudEvents untuk memvalidasi webhook induk. Judul permintaan WebHook-Request-Origin diatur menjadi nama domain layanan xxx.webpubsub.azure.com, dan layanan tersebut mengharapkan respons yang memiliki judul WebHook-Allowed-Origin untuk mengandung nama domain berikut.

Ketika melakukan validasi, parameter {event} ditangani menjadi validate. Misalnya, saat mencoba mengatur URL ke http://host.com/api/{event}, layanan mencoba OPSI permintaan ke http://host.com/api/validate dan hanya ketika respons valid, konfigurasi dapat berhasil diatur.

Untuk saat ini, kami tidak mendukung WebHook-Request-Rate dan WebHook-Request-Callback.

Autentikasi/Otorisasi antara layanan dan webhook

Mode anonim
Autentikasi sederhana yang code disediakan melalui URL Webhook yang dikonfigurasi.
Gunakan otorisasi Microsoft Entra. Untuk informasi selengkapnya, lihat cara menggunakan identitas terkelola untuk detailnya.
- Langkah1: Aktifkan Identitas untuk layanan Web PubSub
- Langkah 2: Pilih dari aplikasi Microsoft Entra yang sudah ada yang merupakan singkatan dari aplikasi web webhook Anda

Manajer sambungan

Server pada dasarnya adalah pengguna yang berwenang. Dengan bantuan peran handler acara, server mengetahui metadata klien, misalnya connectionId dan userId, sehingga dapat:

Tutup sambungan klien
Mengirim pesan ke klien
Mengirim pesan ke klien yang dimiliki oleh pengguna yang sama
Menambahkan klien ke grup
Menambahkan klien yang diautentikasi sebagai pengguna yang sama ke grup
Menghapus klien dari grup
Menghapus klien yang diautentikasi sebagai pengguna yang sama dari grup
Menerbitkan pesan ke grup

Hal ini juga dapat memberikan atau mencabut izin penerbitan/bergabung untuk klien PubSub:

Memberikan izin terbitkan/gabung ke beberapa grup tertentu atau ke semua grup
Mencabut izin terbitkan/gabung untuk beberapa grup tertentu atau untuk semua grup
Periksa apakah klien memiliki izin untuk bergabung atau menerbitkan ke beberapa grup tertentu atau ke semua grup

Layanan ini menyediakan REST API bagi server untuk melakukan manajemen koneksi.

Diagram showing the Web PubSub service connection manager workflow.

Protokol REST API yang detail ditentukan di sini.

Pendengar peristiwa

Catatan

Fitur pendengar peristiwa dalam pratinjau.

Pendengar peristiwa mendengarkan peristiwa klien yang masuk. Setiap pendengar peristiwa berisi filter untuk menentukan jenis peristiwa mana yang menjadi perhatiannya, titik akhir tentang tempat mengirim peristiwa.

Saat ini kami mendukung Azure Event Hubs sebagai titik akhir pendengar peristiwa.

Anda perlu mendaftarkan pendengar peristiwa sebelumnya, sehingga ketika peristiwa klien dipicu, layanan dapat mendorong peristiwa ke pendengar peristiwa yang sesuai. Lihat dokumen ini tentang cara mengonfigurasi pendengar peristiwa dengan titik akhir pusat aktivitas.

Anda dapat mengonfigurasi beberapa pendengar peristiwa. Urutan pendengar peristiwa tidak masalah. Jika acara cocok dengan beberapa pendengar peristiwa, acara akan dikirim ke semua pendengar yang cocok dengannya. Lihat diagram berikut untuk contohnya. Katakanlah Anda mengonfigurasi empat pendengar peristiwa secara bersamaan. Kemudian acara klien yang cocok dengan tiga pendengar tersebut akan dikirim ke tiga pendengar, meninggalkan sisanya yang tidak tersentuh.

Event listener data flow diagram sample

Anda dapat menggabungkan penanganan aktivitas dan pendengar peristiwa untuk peristiwa yang sama. Dalam hal ini, penanganan aktivitas dan pendengar peristiwa akan menerima acara.

Layanan Web PubSub mengirimkan peristiwa klien kepada pendengar peristiwa menggunakan ekstensi CloudEvents AMQP untuk Azure Web PubSub.

Ringkasan

Anda mungkin sudah memperhatikan bahwa peran handler acara menangani komunikasi dari layanan ke server sementara layanan manajer menangani komunikasi dari server ke layanan. Setelah menggabungkan dua peran, aliran data antara layanan dan server terlihat mirip dengan diagram berikut menggunakan protokol HTTP.

Diagram showing the Web PubSub service bi-directional workflow.