Layanan Azure Web PubSub internal

Artikel
08/21/2024

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.
Protokol sederhana memungkinkan klien untuk menerbitkan pijat langsung satu sama lain.
Layanan ini mengelola koneksi WebSocket untuk Anda.

Syarat

Layanan: Layanan Azure Web PubSub.

Koneksi: Koneksi, juga dikenal sebagai koneksi klien atau klien, ini adalah hubungan logis antara klien dan layanan Web PubSub. Melalui 'koneksi', klien dan layanan terlibat dalam serangkaian interaksi bernegara. Koneksi yang menggunakan protokol yang berbeda mungkin bersifat berbeda, misalnya, beberapa koneksi terbatas pada durasi koneksi jaringan, sementara yang lain dapat memperluas beberapa koneksi jaringan berturut-turut antara klien dan layanan.
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.
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 yang menampilkan alur kerja layanan Web PubSub.

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 berikut: Diagram memperlihatkan urutan untuk koneksi klien.

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. Kejadian ini berisi pesan yang dikirim dalam bingkai WebSocket. Kode Anda perlu mengirimkan pesan di dalam penanganan aktivitas ini. Jika penanganan aktivitas mengembalikan kode respons yang gagal, layanan akan menghilangkan koneksi klien. Layanan ini juga mendorong message peristiwa ke semua pendengar peristiwa yang bersangkutan, jika ada. Jika layanan tidak dapat menemukan server terdaftar untuk menerima pesan, layanan juga menghilangkan koneksi klien.
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 melihat 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. Sebaliknya, mereka mengirim 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 menampilkan alur kerja autentikasi klien.

Klien dapat menerbitkan ke klien lain hanya ketika diotorisasi. roleKlien menentukan izin awal yang dimiliki klien:

Peran	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 menampilkan mode dorong acara layanan Web PubSub.

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. Mode ini bertindak sebagai induk 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

Untuk menetapkan autentikasi dan otorisasi yang aman antara layanan dan webhook Anda, pertimbangkan opsi dan langkah-langkah berikut:

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.

Aktifkan Identitas untuk layanan Web PubSub.
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 menampilkan alur kerja manajer koneksi layanan Web PubSub.

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 di mana Anda mengonfigurasinya tidak memengaruhi fungsionalitasnya. Jika peristiwa cocok dengan beberapa pendengar, acara dikirim ke semua pendengar yang cocok. Lihat diagram berikut untuk contohnya. Misalnya, jika Anda mengonfigurasi empat pendengar peristiwa secara bersamaan, setiap pendengar yang menerima kecocokan memproses peristiwa. Peristiwa klien yang cocok dengan tiga pendengar tersebut dikirim ke tiga pendengar, dengan pendengar yang tersisa diabaikan.

Sampel diagram aliran data pendengar peristiwa

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

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

Ringkasan

Peran penanganan aktivitas menangani komunikasi dari layanan ke server sementara peran manajer menangani komunikasi dari server ke layanan. Setelah Anda menggabungkan dua peran, aliran data antara layanan dan server terlihat mirip dengan diagram berikut menggunakan protokol HTTP.

Diagram menampilkan alur kerja dua arah layanan Web PubSub.