Konfigurowanie programu obsługi zdarzeń w usłudze Azure Web PubSub

Artykuł
09/19/2024

Procedura obsługi zdarzeń obsługuje przychodzące zdarzenia klienta. Programy obsługi zdarzeń są rejestrowane i konfigurowane w usłudze za pośrednictwem witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure. Po wyzwoleniu zdarzenia klienta usługa może wysłać zdarzenie do odpowiedniej procedury obsługi zdarzeń. Usługa Web PubSub obsługuje teraz program obsługi zdarzeń po stronie serwera, który uwidacznia publicznie dostępny punkt końcowy dla usługi do wywołania po wyzwoleniu zdarzenia. Innymi słowy, działa jako element webhook.

Usługa Web PubSub dostarcza zdarzenia klienta do skonfigurowanego nadrzędnego elementu webhook przy użyciu protokołu HTTP CloudEvents z rozszerzeniem CloudEvents dla programu obsługi zdarzeń usługi Azure Web PubSub.

Zrzut ekranu przedstawiający wyzwalacz zdarzeń usługi Web PubSub.

Ustawienia programu obsługi zdarzeń

Klient zawsze łączy się z koncentratorem i można skonfigurować wiele ustawień programu obsługi zdarzeń dla centrum. Kolejność ustawień programu obsługi zdarzeń ma znaczenie, a pierwszy ma wyższy priorytet. Gdy klient połączy się i zostanie wyzwolone zdarzenie, usługa Web PubSub przechodzi przez skonfigurowane programy obsługi zdarzeń w kolejności priorytetu i pierwsze zgodne z jednym zwycięstwem. Ustaw następujące właściwości podczas konfigurowania programu obsługi zdarzeń:

Nazwa właściwości	Opis
Szablon adresu URL	Definiuje szablon Web PubSub używa do oceny nadrzędnego adresu URL elementu webhook.
Zdarzenia użytkownika	Definiuje zdarzenia użytkownika, o które dba bieżące ustawienie programu obsługi zdarzeń.
Zdarzenia systemowe	Definiuje zdarzenia systemowe, o które dba bieżące ustawienie programu obsługi zdarzeń.
Uwierzytelnianie	Definiuje metodę uwierzytelniania między usługą Web PubSub i nadrzędnym serwerem.

Zdarzenia

Zdarzenia obejmują zdarzenia użytkownika i zdarzenia systemowe. Zdarzenia systemowe to wstępnie zdefiniowane zdarzenia, które są wyzwalane w okresie istnienia klienta. Zdarzenia użytkownika są wyzwalane, gdy klient wysyła dane, nazwę zdarzenia użytkownika można dostosować przy użyciu protokołów klienta, tutaj zawiera szczegółowe wyjaśnienie.

Typ zdarzenia	Obsługiwane wartości
Zdarzenia systemowe	`connect`, `connected` i `disconnected`
Zdarzenia użytkownika	`message`lub niestandardowa nazwa zdarzenia zgodnie z protokołami klienta

Szablon adresu URL

Szablon adresu URL obsługuje kilka parametrów, które można ocenić podczas wykonywania. Dzięki tej funkcji można łatwo kierować różne koncentratory lub zdarzenia do różnych serwerów nadrzędnych za pomocą jednego ustawienia. Składnia referencyjna usługi KeyVault jest również obsługa, dzięki czemu dane mogą być bezpiecznie przechowywane w usłudze Azure Key Vault.

Uwaga Nazwa domeny adresu URL nie powinna zawierać składni parametrów, na przykład http://{hub}.com nie jest prawidłowym szablonem adresu URL.

Obsługiwane parametry	Składnia	opis	Przykłady
Parametr koncentratora	`{hub}`	Wartość to centrum, z którymi nawiązuje połączenie klient.	Gdy klient nawiąż `client/hubs/chat`połączenie z usługą , zostanie obliczony `http://host.com/api/chat` szablon `http://host.com/api/{hub}` adresu URL, ponieważ w przypadku tego klienta centrum to `chat`.
Parametr zdarzenia	`{event}`	Wartość wyzwolonego zdarzenia. `event` wartości są wymienione tutaj. Wartość zdarzenia dla żądań ochrony przed nadużyciami jest `validate` wyjaśniona tutaj.	Jeśli istnieje szablon `http://host.com/api/{hub}/{event}` adresu URL skonfigurowany dla zdarzenia `connect`, gdy klient nawiązuje połączenie z `client/hubs/chat`usługą , usługa Web PubSub inicjuje żądanie POST do ocenianego adresu URL `http://host.com/api/chat/connect` , gdy klient nawiązuje połączenie, ponieważ w przypadku tego zdarzenia klienta centrum jest `chat` i zdarzenie wyzwalające to ustawienie procedury obsługi zdarzeń to `connect`.
Parametr referencyjny usługi KeyVault	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	Identyfikator SecretUri powinien być pełnym identyfikatorem URI płaszczyzny danych wpisu tajnego w magazynie, opcjonalnie zawierającym wersję, na przykład `https://myvault.vault.azure.net/secrets/mysecret/` lub `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`. W przypadku korzystania z odwołania do usługi KeyVault należy również skonfigurować uwierzytelnianie między usługą Web PubSub i usługą KeyVault, aby uzyskać szczegółowe instrukcje.	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

Uwierzytelnianie między usługą a elementem webhook

Użyć dowolnej z tych metod do uwierzytelniania między usługą i elementem webhook.

Tryb anonimowy
Proste uwierzytelnianie za ?code=<code> pomocą polecenia jest udostępniane za pośrednictwem skonfigurowanego adresu URL elementu webhook jako parametru zapytania.
Autoryzacja firmy Microsoft Entra. Aby uzyskać więcej informacji, zobacz Używanie tożsamości zarządzanej w zdarzeniach klienta.

Nadrzędna i walidacja

Podczas konfigurowania elementu webhook programu obsługi zdarzeń za pośrednictwem witryny Azure Portal lub interfejsu wiersza polecenia usługa jest zgodna z usługą CloudEvents Abuse Protection w celu zweryfikowania nadrzędnego elementu webhook. Ten mechanizm weryfikuje każdy zarejestrowany nadrzędny adres URL elementu webhook. Nagłówek WebHook-Request-Origin żądania jest ustawiony na nazwę xxx.webpubsub.azure.comdomeny usługi i oczekuje, że odpowiedź będzie zawierać WebHook-Allowed-Origin tę nazwę domeny lub *.

Podczas sprawdzania {event} poprawności parametr jest rozpoznawany jako validate. Na przykład podczas próby ustawienia adresu URL na http://host.com/api/{event}wartość usługa próbuje OPCJE żądania na http://host.com/api/validate. I tylko wtedy, gdy odpowiedź jest prawidłowa, konfigurację można ustawić pomyślnie.

Na razie nie obsługujemy funkcji WebHook-Request-Rate i WebHook-Request-Callback.

Konfigurowanie programu obsługi zdarzeń

Konfigurowanie za pośrednictwem witryny Azure Portal

Możesz dodać procedurę obsługi zdarzeń do nowego centrum lub edytować istniejące centrum.

Aby skonfigurować program obsługi zdarzeń w nowym centrum:

Przejdź do strony usługi Azure Web PubSub w witrynie Azure Portal.
W menu wybierz pozycję Ustawienia.
Wybierz pozycję Dodaj , aby utworzyć centrum i skonfigurować adres URL elementu webhook po stronie serwera. Uwaga: Aby dodać program obsługi zdarzeń do istniejącego centrum, wybierz centrum i wybierz pozycję Edytuj.
Wprowadź nazwę centrum.
Wybierz pozycję Dodaj w obszarze Konfiguruj nawet programy obsługi.
Na stronie obsługi zdarzeń skonfiguruj następujące pola: 1. Wprowadź adres URL elementu webhook serwera w polu Szablon adresu URL. 1. Wybierz zdarzenia systemowe, do których chcesz zasubskrybować. 1. Wybierz zdarzenia użytkownika, do których chcesz zasubskrybować. 1. Wybierz metodę uwierzytelniania , aby uwierzytelnić żądania nadrzędne. 1. Wybierz pozycję Potwierdź.
Wybierz pozycję Zapisz w górnej części strony Konfigurowanie ustawień centrum.

Konfigurowanie za pomocą interfejsu wiersza polecenia platformy Azure

Użyj poleceń az webpubsub hub group interfejsu wiersza polecenia platformy Azure, aby skonfigurować ustawienia programu obsługi zdarzeń.

Polecenia	opis
`create`	Utwórz ustawienia centrum dla usługi WebPubSub.
`delete`	Usuń ustawienia centrum dla usługi WebPubSub.
`list`	Wyświetl listę wszystkich ustawień centrum dla usługi WebPubSub.
`show`	Pokaż ustawienia centrum dla usługi WebPubSub.
`update`	Zaktualizuj ustawienia centrum dla usługi WebPubSub.

Oto przykład tworzenia dwóch adresów URL elementu webhook dla centrum MyHub MyWebPubSub zasobu:

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"