在 Azure Web PubSub 服務中設定事件處理常式

發行項
09/25/2024

事件處理常式會處理傳入的用戶端事件。您可以透過 Azure 入口網站或 Azure CLI，在服務中註冊和設定事件處理常式。觸發用戶端事件時，服務可以將事件傳送至適當的事件處理常式。 Web PubSub 服務目前支援事件處理常式作為伺服器端，該事件處理常式會揭露可公開存取的端點，以便在觸發事件時叫用服務。換句話說，它會作為 Webhook。

Web PubSub 服務會使用 CloudEvents HTTP 通訊協定搭配 Azure Web PubSub 事件處理常式的 CloudEvents 延伸模組，將用戶端事件傳遞至已設定的上游 Webhook。

Web PubSub 服務事件觸發程序的螢幕擷取畫面。

事件處理常式設定

用戶端一律會連線到中樞，而您可設定中樞的多個事件處理常式設定。事件處理常式設定的順序很重要，而前面的項目具有較高的優先順序。當用戶端連線並觸發事件時，Web PubSub 會依照優先順序進行已設定的事件處理常式，而第一個相符項目優先。設定事件處理常式時，請設定下列屬性：

屬性名稱	描述
URL template	定義 Web PubSub 用來評估上游 Webhook URL 的範本。
使用者事件	定義目前事件處理常式設定所關切的使用者事件。
系統事件	定義目前事件處理常式設定所關切的系統事件。
驗證	定義 Web PubSub 服務與上游伺服器之間的驗證方法。

事件

這些事件包括使用者事件和系統事件。系統事件是用戶端存留期間觸發的預先定義事件。當用戶端傳送資料時，會觸發使用者事件，可以使用用戶端通訊協定自訂使用者事件名稱，這裡有詳細的說明。

事件類型	支援值
系統事件	`connect`、`connected` 和 `disconnected`
使用者事件	`message`，或接在用戶端通訊協定後面的自訂事件名稱

URL 範本

URL 範本支援數個可在執行階段期間評估的參數。透過這項功能，可使用單一設定，輕鬆地將不同的中樞或事件路由傳送到不同的上游伺服器。 KeyVault 參考語法也支援，以便安全地將資料儲存在 Azure Key Vault 中。

請注意 URL 網域名稱不得包含參數語法，例如 http://{hub}.com 不是有效的 URL 範本。

支援的參數	語法	描述	範例
中樞參數	`{hub}`	此值是用戶端所連線至的中樞。	當用戶端連線到 `client/hubs/chat` 時，URL 範本 `http://host.com/api/{hub}` 會評估為 `http://host.com/api/chat`，因為對於此用戶端而言，中樞是 `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 之間進行驗證。

匿名模式
簡單的 ?code=<code> 驗證是透過已設定的 Webhook URL 作為查詢參數提供。
Microsoft Entra 授權。如需詳細資訊，請參閱在用戶端事件中使用受控識別。

上游和驗證

透過 Azure 入口網站或 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 入口網站進行設定

您可以將事件處理常式新增至新的中樞，或編輯現有的中樞。

若要在新的中樞中設定事件處理常式：

在 Azure 入口網站中移至您的 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"