Azure Web PubSub サービスのイベントハンドラー

[アーティクル]
11/15/2023

イベントハンドラーでは、受信クライアントイベントが処理されます。イベントハンドラーは、Azure portal または Azure CLI を使用してサービスに登録、設定できます。クライアントイベントがトリガーされると、サービスから適切なイベントハンドラーにイベントを送信できます。 Web PubSub サービスでは、サーバー側としてイベントハンドラーを使用できるようになりました。これにより、イベントがトリガーされたときに呼び出すサービスのパブリックアクセス可能なエンドポイントが公開されます。つまり Webhook として機能します。

Web PubSub サービスは、CloudEvents HTTP プロトコルを使用して、アップストリームの Webhook にクライアントイベントを配信します。

すべてのイベントに対して、このサービスは登録されたアップストリームエンドポイントへの HTTP POST 要求を形成し、HTTP 応答を期待します。

サービスからサーバーに送信されるデータは、常に CloudEvents binary 形式です。

Screenshot of Web PubSub service event trigger.

アップストリームと検証

Webhook エンドポイントを構成するときに、URL テンプレートを定義する {event} パラメーターを URL に含めることができます。サービスでは、クライアント要求を受信すると、Webhook URL の値が動的に計算されます。たとえば、ハブ /client/hubs/chat にイベントハンドラー URL パターン http://host.com/api/{event} が構成されている状態で、要求 chat を受信すると、クライアントは接続するときに、最初に URL http://host.com/api/connect に POST します。 {event} パラメーターは、PubSub WebSocket クライアントがカスタムイベントを送信するときに役立つ可能性があり、イベントハンドラーでは、さまざまなイベントをさまざまなアップストリームエンドポイントにディスパッチできます。 URL ドメイン名では {event} パラメーターを使用できません。

Azure portal または CLI を使用してイベントハンドラーの Webhook を設定すると、サービスでは、CloudEvents の不正使用防止に従ってアップストリームの Webhook が検証されます。このメカニズムによって、登録されているすべてのアップストリーム Webhook の URL が検証されます。 WebHook-Request-Origin 要求ヘッダーはサービスドメイン名 xxx.webpubsub.azure.com に設定されており、これは応答にこのドメイン名または * を含むヘッダー WebHook-Allowed-Origin があることが期待されます。

検証を実行すると、{event} パラメーターは validate に解決されます。たとえば、URL を http://host.com/api/{event} に設定しようとすると、サービスは http://host.com/api/validate に対して OPTIONS 要求を試みます。また、応答が有効な場合にのみ、構成を正常に設定できます。

現時点では、WebHook-Request-Rate と WebHook-Request-Callback はサポートされていません。

サービスと Webhook 間の認証

これらのメソッドのいずれかを使用して、サービスと webhook の間で認証を行うことができます。

匿名モード
クエリパラメーターとして構成された Webhook URL を通じて提供される ?code=<code> によるシンプルな認証。
Microsoft Entra 認証。詳細については、クライアントイベントでマネージド ID を使用することに関するページを参照してください。

イベントハンドラーの構成

Azure portal を使用して構成する

新しいハブにイベントハンドラーを追加することも、既存のハブを編集することもできます。

新しいハブでイベントハンドラーを構成するには、以下の手順を実行してください。

Azure portal で、Azure Web PubSub サービスページに移動します。
メニューから [設定] を選択します。
[追加] を選択してハブを作成し、サーバー側の Webhook URL を構成します。注: 既存のハブにイベントハンドラーを追加するには、ハブを選択して [編集] を選択します。
ハブ名を入力します。
[イベントハンドラーの構成] で [追加] を選択します。
イベントハンドラーページで、次のフィールドを構成します: 1。「URL テンプレート」フィールドにサーバー Webhook URL を入力します。 1. サブスクライブするシステムイベントを選択します。1. サブスクライブするユーザーイベントを選択します。1. アップストリーム要求の認証に使用する認証方法を選択します。 1. 確認を選択します。
[ハブ設定の構成] ページの上部にある [保存] を選択します。

Azure CLI を使用して構成する

Azure CLI の az webpubsub hub グループコマンドを使用して、イベントハンドラーの設定を構成します。

コマンド	説明
`create`	WebPubSub サービスのハブ設定を作成します。
`delete`	WebPubSub サービスのハブ設定を削除します。
`list`	WebPubSub サービスのすべてのハブ設定を一覧表示します。
`show`	WebPubSub サービスのハブ設定を表示します。
`update`	WebPubSub サービスのハブ設定を更新します。

以下に、MyWebPubSub リソースのハブ MyHub 用に 2 つの Webhook URL を作成する例を示します。

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"