Mengonfigurasi penanganan aktivitas di layanan Azure Web PubSub

Artikel
10/16/2024

Handler acara menangani acara klien yang masuk. Penanganan aktivitas didaftarkan dan dikonfigurasi dalam layanan melalui portal Azure atau Azure CLI. Saat peristiwa klien dipicu, layanan dapat mengirim peristiwa ke penanganan aktivitas yang sesuai. Layanan Web PubSub sekarang mendukung penanganan aktivitas sebagai sisi server, yang mengekspos titik akhir yang dapat diakses publik agar layanan dipanggil saat peristiwa dipicu. Dengan kata lain, penanganan aktivitas bertindak sebagai webhook.

Layanan Web PubSub mengirimkan peristiwa klien ke webhook upstream yang dikonfigurasi menggunakan protokol HTTP CloudEvents, dengan ekstensi CloudEvents untuk penanganan aktivitas Azure Web PubSub.

Cuplikan layar pemicu peristiwa layanan Web PubSub.

Pengaturan penanganan aktivitas

Klien selalu terhubung ke hub, dan Anda dapat mengonfigurasi beberapa pengaturan penanganan aktivitas untuk hub. Urutan pengaturan penanganan aktivitas penting dan yang pertama memiliki prioritas yang lebih tinggi. Ketika klien terhubung dan peristiwa dipicu, Web PubSub melewati penanganan aktivitas yang dikonfigurasi dalam urutan prioritas dan yang pertama cocok menang. Atur properti berikut saat Anda mengonfigurasi penanganan aktivitas:

Nama properti	Deskripsi
Templat url	Menentukan templat yang digunakan Web PubSub untuk mengevaluasi URL webhook upstream Anda.
Peristiwa pengguna	Menentukan peristiwa pengguna yang menjadi perhatian pengaturan penanganan aktivitas saat ini.
Peristiwa sistem	Menentukan peristiwa sistem yang menjadi perhatian pengaturan penanganan aktivitas saat ini.
Autentikasi	Menentukan metode autentikasi antara layanan Web PubSub dan server hulu Anda.

Acara

Peristiwa tersebut mencakup peristiwa pengguna dan peristiwa sistem. Peristiwa sistem adalah peristiwa yang telah ditentukan sebelumnya yang dipicu selama masa pakai klien. Peristiwa pengguna dipicu ketika klien mengirim data, nama peristiwa pengguna dapat disesuaikan menggunakan protokol klien, di sini berisi penjelasan terperinci.

Jenis peristiwa	Nilai yang Didukung
Peristiwa sistem	`connect`, `connected`, dan `disconnected`
Peristiwa pengguna	`message`, atau nama peristiwa kustom yang mengikuti protokol klien

Templat URL

Templat URL mendukung beberapa parameter yang dapat dievaluasi selama runtime. Dengan fitur ini, mudah untuk merutekan hub atau peristiwa yang berbeda ke server hulu yang berbeda dengan satu pengaturan. Sintaks referensi KeyVault juga didukung sehingga data dapat disimpan di Azure Key Vault dengan aman.

Nama domain URL catatan tidak boleh berisi sintaks parameter, misalnya, http://{hub}.com bukan templat URL yang valid.

Parameter yang didukung	Sintaks	Deskripsi	Sampel
Parameter hub	`{hub}`	Nilainya adalah hub tempat klien terhubung.	Saat klien tersambung ke `client/hubs/chat`, templat `http://host.com/api/{hub}` URL dievaluasi `http://host.com/api/chat` karena untuk klien ini, hub adalah `chat`.
Parameter peristiwa	`{event}`	Nilai peristiwa yang dipicu. `event` nilai tercantum di sini. Nilai peristiwa untuk permintaan perlindungan penyalahgunaan seperti yang `validate` dijelaskan di sini.	Jika ada templat `http://host.com/api/{hub}/{event}` URL yang dikonfigurasi untuk peristiwa `connect`, Saat klien terhubung ke `client/hubs/chat`, Web PubSub memulai permintaan POST ke URL `http://host.com/api/chat/connect` yang dievaluasi saat klien terhubung, karena untuk peristiwa klien ini, hub adalah `chat` dan peristiwa yang memicu pengaturan penanganan aktivitas ini adalah `connect`.
Parameter referensi KeyVault	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	SecretUri harus menjadi URI bidang data lengkap dari rahasia di brankas, secara opsional termasuk versi, misalnya, `https://myvault.vault.azure.net/secrets/mysecret/` atau `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`. Saat menggunakan referensi KeyVault, Anda juga perlu mengonfigurasi autentikasi antara layanan Web PubSub dan layanan KeyVault Anda, periksa di sini untuk langkah-langkah terperinci.	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

Autentikasi antara layanan dan webhook

Anda dapat menggunakan salah satu metode ini untuk mengautentikasi antara layanan dan webhook.

Mode anonim
Autentikasi sederhana dengan ?code=<code> disediakan melalui URL Webhook yang dikonfigurasi sebagai parameter kueri.
Otorisasi Microsoft Entra. Untuk informasi selengkapnya, lihat Menggunakan identitas terkelola dalam peristiwa klien.

Induk dan Validasi

Saat menyiapkan webhook penanganan aktivitas melalui portal Azure atau CLI, layanan mengikuti CloudEvents Abuse Protection untuk memvalidasi webhook upstream. Mekanisme ini memvalidasi setiap URL webhook upstream yang terdaftar. Header WebHook-Request-Origin permintaan diatur ke nama xxx.webpubsub.azure.comdomain layanan , dan mengharapkan respons untuk memiliki header WebHook-Allowed-Origin untuk berisi nama domain ini atau *.

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.

Konfigurasikan penanganan aktivitas

Konfigurasikan melalui portal Microsoft Azure

Anda dapat menambahkan penanganan aktivitas ke hub baru atau mengedit hub yang sudah ada.

Untuk mengonfigurasi penanganan aktivitas di hub baru:

Buka halaman layanan Azure Web PubSub Anda di portal Azure.
Pilih Pengaturan dari menu.
Pilih Tambahkan untuk membuat hub dan mengonfigurasi URL webhook sisi server Anda. Catatan: Untuk menambahkan penanganan aktivitas ke hub yang sudah ada, pilih hub dan pilih Edit.
Masukkan nama hub Anda.
Pilih Tambahkan di bawah Konfigurasikan Penanganan Genap.
Di halaman penanganan aktivitas, konfigurasikan bidang berikut: 1. Masukkan URL webhook server di bidang Templat URL. 1. Pilih Peristiwa sistem yang ingin Anda berlangganan. 1. Pilih Peristiwa pengguna yang ingin Anda berlangganan. 1. Pilih Metode autentikasi untuk mengautentikasi permintaan upstram. 1. Pilih Konfirmasi.
Pilih Simpan di bagian atas halaman Konfigurasi Pengaturan Hub.

Konfigurasikan melalui Azure CLI

Gunakan perintah grup Azure CLI az webpubsub hub untuk mengonfigurasi pengaturan penanganan aktivitas.

Perintah	Deskripsi
`create`	Buat pengaturan hub untuk Layanan WebPubSub.
`delete`	Hapus pengaturan hub untuk Layanan WebPubSub.
`list`	Cantumkan semua pengaturan hub untuk Layanan WebPubSub.
`show`	Tampilkan pengaturan hub untuk Layanan WebPubSub.
`update`	Perbarui pengaturan hub untuk Layanan WebPubSub.

Berikut adalah contoh pembuatan dua URL webhook untuk hub MyHub MyWebPubSub sumber daya:

az webpubsub hub create -n "MyWebPubSub" -g "MyResourceGroup" --hub-name "MyHub" --event-handler url-template="http://host.com" user-event-pattern="*" --event-handler url-template="http://host2.com" system-event="connected" system-event="disconnected" auth-type="ManagedIdentity" auth-resource="uri://myUri"