Azure Web PubSub サービスでイベントハンドラーを構成する

[アーティクル]
09/19/2024

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

Web PubSub サービスは、Azure Web PubSub イベントハンドラーの CloudEvents 拡張機能と共に CloudEvents HTTP プロトコルを使用して、構成されたアップストリーム Webhook にクライアントイベントを配信します。

Web PubSub サービスイベントトリガーのスクリーンショット。

イベントハンドラーの設定

クライアントは常にハブに接続し、ハブに対して複数のイベントハンドラー設定を構成できます。イベントハンドラー設定の順序が重要であり、先に設定された方が優先順位が高くなります。クライアントが接続し、イベントがトリガーされると、Web PubSub は構成されたイベントハンドラーを優先度順に確認し、最初に一致したイベントハンドラーが採用されます。イベントハンドラーを構成するときに、次のプロパティを設定します。

プロパティ名	説明
URL テンプレート	Web PubSub がアップストリーム Webhook URL の評価に使用するテンプレートを定義します。
ユーザーイベント	現在のイベントハンドラー設定で考慮されるユーザーイベントを定義します。
システムイベント	現在のイベントハンドラー設定で考慮されるシステムイベントを定義します。
認証	Web PubSub サービスとアップストリームサーバーの間の認証方法を定義します。

Events

イベントには、ユーザーイベントとシステムイベントが含まれます。システムイベントは、クライアントの有効期間中にトリガーされる定義済みのイベントです。ユーザーイベントは、クライアントがデータを送信するときにトリガーされます。ユーザーイベント名は、クライアントプロトコルを使用してカスタマイズできます。詳細についてはこちらを参照してください。

イベントの種類	サポート状況の値
システムイベント	`connect`、`connected`、`disconnected`
ユーザーイベント	`message`、またはクライアントプロトコルに続くカスタムイベント名

URL テンプレート

URL テンプレートでは、実行時に評価できるいくつかのパラメーターがサポートされています。この機能を使用すると、異なるハブまたはイベントを単一の設定で異なるアップストリームサーバーに簡単にルーティングできます。 KeyVault 参照構文もサポートされているため、データを Azure Key Vault に安全に格納できます。

注: URL ドメイン名にはパラメーター構文を含めないでください。たとえば、http://{hub}.com は有効な URL テンプレートではありません。

サポートされているパラメーター	構文	説明	サンプル
ハブパラメーター	`{hub}`	値は、クライアントが接続するハブです。	クライアントが `client/hubs/chat` に接続すると、このクライアントではハブが `chat` であるため、URL テンプレート `http://host.com/api/{hub}` は "`http://host.com/api/chat`" と評価されます。
イベントパラメーター	`{event}`	トリガーされたイベントの値。 `event` 値はこちらに記載されています。乱用保護要求のイベント値は、こちらで説明されているように `validate` です。	イベント `connect` 用に構成された URL テンプレート `http://host.com/api/{hub}/{event}` がある場合、クライアントが `client/hubs/chat` に接続すると、Web PubSub は、クライアントが接続しているときに評価された URL `http://host.com/api/chat/connect` への POST 要求を開始します。これは、このクライアントイベントのハブが `chat` であり、このイベントハンドラー設定をトリガーするイベントが `connect` であるためです。
KeyVault 参照パラメーター	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	SecretUri は、コンテナー内のシークレットのフルデータプレーン URI である必要があり、必要に応じてバージョンが含まれます (例: `https://myvault.vault.azure.net/secrets/mysecret/` や `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`)。 KeyVault リファレンスを使用する場合は、Web PubSub サービスと KeyVault サービスの間で認証を構成する必要もあります。詳細な手順については、こちらを確認してください。	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)`

サービスと Webhook 間の認証

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

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

アップストリームと検証

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 はサポートされていません。

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

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"