Azure Web PubSub 服務中的事件處理常式

發行項
04/11/2024

事件處理常式會處理傳入的用戶端事件。您可以透過 Azure 入口網站或 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 要求傳入，且已為中樞 chat 設定了事件處理常式 URL 模式 http://host.com/api/{event} 時，這時如果用戶端連線，其會先 POST (張貼) 到此 URL：http://host.com/api/connect。當 PubSub WebSocket 用戶端傳送自訂事件時，事件處理常式會協助將不同的事件分派至不同的上游端點，這時 {event} 參數會很有用。 URL 網域名稱中不允許 {event} 參數。

透過 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。

服務與 Webhook 之間的驗證

您可使用其中任何一種方法，在服務和 Webhook 之間進行驗證。

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

設定事件處理常式

透過 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"