共用方式為

Azure Functions 的 Azure Web PubSub 觸發程式系結

使用 Azure Web PubSub 觸發程式來處理來自 Azure Web PubSub 服務的用戶端事件。

觸發程式端點模式如下所示，這應該在 Web PubSub 服務端設定（入口網站：設定 -> 事件處理程式 -> URL 範本）。 在端點模式中，當您基於code=<API_KEY>考量使用 Azure Function 應用程式時，需要使用查詢組件 。 可以在 Azure 入口網站中找到該金鑰。 尋找函式應用程式資源，並在將函式應用程式部署至 Azure 之後，瀏覽至函式 ->應用程式金鑰 ->系統金鑰 ->webpubsub_extension。 不過，當您使用本機函式時，不需要此金鑰。

<Function_App_Url>/runtime/webhooks/webpubsub?code=<API_KEY>

取得函式系統金鑰的螢幕擷取畫面。

範例

下列範例示範如何處理來自用戶端的使用者事件。

[Function("Broadcast")]
public static void Run(
[WebPubSubTrigger("<hub>", WebPubSubEventType.User, "message")] UserEventRequest request, ILogger log)
{
    log.LogInformation($"Request from: {request.ConnectionContext.UserId}");
    log.LogInformation($"Request message data: {request.Data}");
    log.LogInformation($"Request message dataType: {request.DataType}");
}

當伺服器可以檢查和拒絕用戶端要求，或直接將訊息傳送給呼叫者端時，WebPubSubTrigger 繫結也支援同步處理情節中的傳回值 (例如，系統 Connect 和使用者事件)。 Connect 事件遵守 ConnectEventResponse 和 EventErrorResponse，而使用者事件遵守 UserEventResponse 和 EventErrorResponse，不符合目前情節的 rest 型別會予以忽略。

[Function("Broadcast")]
public static UserEventResponse Run(
[WebPubSubTrigger("<hub>", WebPubSubEventType.User, "message")] UserEventRequest request)
{
    return new UserEventResponse("[SYSTEM ACK] Received.");
}

const { app, trigger } = require('@azure/functions');

const wpsTrigger = trigger.generic({
    type: 'webPubSubTrigger',
    name: 'request',
    hub: '<hub>',
    eventName: 'message',
    eventType: 'user'
});

app.generic('message', {
    trigger: wpsTrigger,
    handler: async (request, context) => {
        context.log('Request from: ', request.connectionContext.userId);
        context.log('Request message data: ', request.data);
        context.log('Request message dataType: ', request.dataType);
    }
});

當伺服器可以檢查和拒絕用戶端要求，或直接將訊息傳送給要求用戶端時，WebPubSubTrigger 繫結也支援同步處理情節中的傳回值 (例如，系統 Connect 和使用者事件)。 在 JavaScript 弱型別語言中，它會針對物件索引鍵還原序列化。 而且 EventErrorResponse 具有與其餘對象比較的最高優先順序，如果 code 位於 傳回中，則會剖析為 EventErrorResponse。

app.generic('message', {
    trigger: wpsTrigger,
    handler: async (request, context) => {
          return {
              "data": "ack",
              "dataType" : "text"
          };
    }
});

注意

此語言的完整範例擱置中。

注意

目前尚不支援 Java 的 Web PubSub 擴充功能。

組態

下表說明您在 function.json 檔案中設定的繫結設定屬性。

function.json 屬性 屬性內容 描述
類型 n/a 必要項目 - 必須設定為 webPubSubTrigger。
方向 n/a 必要項目 - 必須設定為 in。
名字 n/a 必要項目 - 函式程式碼中用於接收事件資料之參數的變數名稱。
中樞 中樞 必要 - 針對要觸發的函式，此值必須設為其 Web PubSub 中樞的名稱。 我們支援將屬性中的該值設定為較高的優先順序，或者可以在應用程式設定中將其設定為全域值。
事件類型 網頁發布訂閱事件類型 必要 - 針對要觸發的函式，此值必須設為其訊息事件類型。 該值應為 user 或 system。
eventName 事件名稱 必要 - 針對要觸發的函式，此值必須設為其訊息事件。

針對system事件類型，事件名稱應位於 connect、 connecteddisconnected中。

針對使用者定義的子專案，事件名稱為 message。

針對系統支援的子程式json.webpubsub.azure.v1.，事件名稱是使用者定義的事件名稱。
clientProtocols ClientProtocols 選擇性 - 指定哪些用戶端通訊協定可以觸發 Web PubSub 觸發程式函式。

下列不區分大小寫的值有效：：
all接受所有客戶端通訊協定。 預設值。
webPubSub：只接受 Web PubSub 通訊協定。
mqtt：只接受 MQTT 通訊協定。
連接 連線 選擇性 - 指定上游 Azure Web PubSub 服務的應用程式設定名稱或設定集合名稱。 此值用於簽章驗證。 而且值預設會使用應用程式設定 WebPubSubConnectionString 自動解析。 這 null 表示不需要驗證，且一律會成功。

重要

為了獲得最佳安全性，函式應用程式應該在連線到 Web PubSub 服務時使用受控識別，而不是使用包含共用秘密密鑰的連接字串。 如需詳細資訊，請參閱 使用 Microsoft Entra ID 授權受控識別要求。

使用方式

在 C# 中，WebPubSubEventRequest 為已辨識型別繫結參數，剩餘參數則會由參數名稱繫結。 請查看下表，以取得可用的參數和類型。

在類似 JavaScript 的弱型別語言中， name in function.json 是用來繫結下列對應數據表的相關觸發程序物件。 當 dataType 設定為 function.json (作為觸發程序輸入的繫結物件) 時，會遵守 name 中的 data，以據此轉換訊息。 所有參數都可以從 context.bindingData.<BindingName> 進行讀取，而且會進行 JObject 轉換。

繫結名稱 繫結類型 描述 屬性
要求 WebPubSubEventRequest 描述上游要求 屬性會因不同的事件類型而有所不同，包括衍生類別ConnectEventRequest、、MqttConnectEventRequest、ConnectedEventRequestMqttConnectedEventRequest、、UserEventRequest、 DisconnectedEventRequest和 MqttDisconnectedEventRequest。
連線上下文 WebPubSubConnectionContext 一般要求資訊 EventType、EventName、Hub、ConnectionId、UserId、Headers、Origin、Signature、States
資料 BinaryData、string、Stream、byte[] 在使用者 message 事件中向用戶端要求訊息資料 -
數據類型 WebPubSubDataType 要求訊息 dataType，支援 binary、text、json -
主張 IDictionary<string, string[]> 系統 connect 要求中的使用者宣告 -
查詢 IDictionary<string, string[]> 系統 connect 要求中的使用者查詢 -
子通訊協定 IList<string> 系統 connect 要求中可用的子通訊協定 -
用戶端憑證 IList<ClientCertificate> 系統 connect 要求中用戶端的憑證指紋清單 -
原因 string 系統 disconnected 要求中的原因 -

重要

在 C# 中，支援多個型別的參數必須放在第一個，也就是預設 request 型別以外的 data 或 BinaryData 參數，讓函式正確繫結。

傳回回應

WebPubSubTrigger 會遵守客戶針對 connect 的同步事件和使用者事件所傳回的回應。 只有相符的回應會傳回至服務，否則會將其忽略。 此外，WebPubSubTrigger 傳回物件支援使用者 SetState() 及 ClearStates()，以管理連線的中繼資料。 延伸模組會將傳回值的結果與來自要求 WebPubSubConnectionContext.States 的原始結果合併。 現有索引鍵中的值會覆寫，並新增新索引鍵中的值。

傳回類型 描述 屬性
ConnectEventResponse connect 事件的回應 Groups、Roles、UserId、Subprotocol
UserEventResponse 使用者事件的回應 DataType、Data
EventErrorResponse 同步事件的錯誤回應 Code、ErrorMessage
*WebPubSubEventResponse 支援的基本回應類型 (適用於不確定傳回案例) -
  • Last updated on