Azure Functions 的 SignalR Service 觸發程式系結

使用 SignalR 觸發程式系結來回應從 Azure SignalR 服務傳送的訊息。 觸發函式時,傳遞至函式的訊息會剖析為 json 物件。

在 SignalR 服務無伺服器模式中 ,SignalR Service 會使用上游 功能,將訊息從用戶端傳送至函式應用程式。 函式應用程式會使用SignalR Service 觸發程式系結來處理這些訊息。 一般架構如下所示:

SignalR 觸發程序架構

如需安裝和組態詳細數據的詳細資訊,請參閱概

範例

您可以使用下列其中一種 C# 模式來建立 C# 函式:

  • 隔離的背景工作模型:在與運行時間隔離的背景工作進程中執行的已編譯 C# 函式。 需要隔離的背景工作進程,才能支援在 LTS 和非 LTS 版本 .NET 和 .NET Framework 上執行的 C# 函式。
  • 同進程模型:在與 Functions 運行時間相同的進程中執行的已編譯 C# 函式。
  • C# 文稿:主要用於在 Azure 入口網站 中建立 C# 函式。

下列範例顯示從用戶端接收訊息事件的 C# 函式,並記錄訊息內容。

[Function(nameof(OnClientMessage))]
public static void OnClientMessage(
    [SignalRTrigger("Hub", "messages", "sendMessage", "content", ConnectionStringSetting = "SignalRConnection")]
        SignalRInvocationContext invocationContext, string content, FunctionContext functionContext)
{
    var logger = functionContext.GetLogger(nameof(OnClientMessage));
    logger.LogInformation("Connection {connectionId} sent a message. Message content: {content}", invocationContext.ConnectionId, content);
}

Java 目前不支援 SignalR 觸發程式。

以下是 function.json 檔案中的繫結資料:

{
    "type": "signalRTrigger",
    "name": "invocation",
    "hubName": "hubName1",
    "category": "messages",
    "event": "SendMessage",
    "parameterNames": [
        "message"
    ],
    "direction": "in"
}
app.generic("function1",
    {
        trigger: { "type": "signalRTrigger", "name": "invocation", "direction": "in", "hubName": "hubName1", "event": "SendMessage", "category": "messages" },
        handler: (triggerInput, context) => {
            context.log(`Receive ${context.Arguments[0]} from ${triggerInput.ConnectionId}.`)
        }
    })

完整的 PowerShell 範例擱置中。

以下是 Python 程式代碼:

import logging
import json
import azure.functions as func

def main(invocation) -> None:
    invocation_json = json.loads(invocation)
    logging.info("Receive {0} from {1}".format(invocation_json['Arguments'][0], invocation_json['ConnectionId']))

屬性

進程內和隔離的背景工作進程 C# 連結庫都會使用 SignalRTrigger 屬性來定義函式。 C# 文稿會改用 function.json組態檔

下表說明 屬性的屬性 SignalRTrigger

Attribute 屬性 描述
HubName 此值必須設定為SignalR 中樞的名稱,才能觸發函式。
類別 此值必須設定為要觸發之函式的訊息類別。 類別可以是下列其中一個值:
  • 線上:包括已連線中斷連線的事件
  • 訊息:包含連線類別中以外的所有其他事件
事件 此值必須設定為要觸發之函式的訊息事件。 針對訊息類別,事件是用戶端傳送的目標調用訊息。 針對 連線 類別,只會 使用已連線已中斷連線
ParameterNames (選擇性)係結至參數的名稱清單。
ConnectionStringSetting 包含 SignalR Service 連接字串 的應用程式設定名稱,預設為 AzureSignalRConnectionString

註釋

SignalR 觸發程式目前不支援 Java 註釋。

組態

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

function.json 屬性 描述
type 必須設定為 SignalRTrigger
direction 必須設定為 in
name 函式程式代碼中用於觸發程式調用內容物件的變數名稱。
hubName 此值必須設定為SignalR 中樞的名稱,才能觸發函式。
category 此值必須設定為要觸發之函式的訊息類別。 類別可以是下列其中一個值:
  • 線上:包括已連線中斷連線的事件
  • 訊息:包含連線類別中以外的所有其他事件
event 此值必須設定為要觸發之函式的訊息事件。 針對訊息類別,事件是用戶端傳送的目標調用訊息。 針對 連線 類別,只會 使用已連線已中斷連線
parameterNames (選擇性)係結至參數的名稱清單。
connectionStringSetting 包含 SignalR Service 連接字串 的應用程式設定名稱,預設為 AzureSignalRConnectionString

如需完整範例, 請參閱範例一節

使用方式

負載

觸發程式輸入類型會宣告為 InvocationContext 或自定義類型。 如果您選擇 InvocationContext 取得要求內容的完整存取權。 針對自定義類型,運行時間會嘗試剖析 JSON 要求本文來設定物件屬性。

InvocationContext

InvocationContext 包含從 SignalR 服務傳送之訊息中的所有內容,其中包含下列屬性:

屬性 說明
引數 適用於 訊息 類別目錄。 包含調用訊息中的自變數
錯誤 可用於 中斷連線 的事件。 如果連接關閉且沒有發生錯誤,或包含錯誤訊息,它可以是空的。
中樞 訊息所屬的中樞名稱。
類別 訊息的分類。
活動 訊息的事件。
ConnectionId 傳送訊息之客戶端的連接識別碼。
UserId 傳送訊息之用戶端的使用者身分識別。
標頭 要求的標頭。
查詢 用戶端連線至服務時的要求查詢。
宣告 用戶端的宣告。

使用 ParameterNames

中的 SignalRTrigger 屬性ParameterNames可讓您將調用訊息的自變數系結至函式的參數。 您可以使用您在其他系結中定義為系結運算式部分的名稱,或做為程式代碼中的參數。 這可讓您更方便存取的 InvocationContext自變數。

假設您有 JavaScript SignalR 用戶端嘗試在 Azure 函式中使用兩個自變數 message1message2用 方法broadcast, 。

await connection.invoke("broadcast", message1, message2);

設定 parameterNames之後,您定義的名稱會對應至用戶端上傳送的自變數。

[SignalRTrigger(parameterNames: new string[] {"arg1, arg2"})]

然後, arg1 將包含的內容 message1,並將 arg2 包含 的內容 message2

ParameterNames 考慮

對於參數係結,順序很重要。 如果您使用 ParameterNames,則中的順序 ParameterNames 會符合您在用戶端中叫用之自變數的順序。 如果您使用 C# 中的 屬性 [SignalRParameter] ,Azure Function 方法中的自變數順序會符合用戶端中的自變數順序。

ParameterNames 和 屬性 [SignalRParameter]無法 同時使用,否則您將會收到例外狀況。

SignalR Service 整合

當您使用 SignalR Service 觸發程式系結時,SignalR Service 需要 URL 才能存取函式應用程式。 URL 應該在 SignalR 服務端的上游 設定 中設定。

上游入口網站

使用 SignalR Service 觸發程式時,URL 可以簡單且格式化,如下所示:

<Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>

Function_App_URL您可以在函式應用程式的 [概觀] 頁面上找到 ,API_KEY而 是由 Azure 函式產生。 您可以在函式應用程式的 [應用程式金鑰] 刀鋒視窗中取得 API_KEYsignalr_extension API 金鑰

如果您想要搭配一個SignalR Service 使用多個函式應用程式,上游也可以支持複雜的路由規則。 在上游設定中 尋找更多詳細數據

逐步範例

您可以遵循 GitHub 中的範例,在函式應用程式上使用 SignalR Service 觸發程式系結和上游功能來部署聊天室: 雙向聊天室範例

下一步