Azure Functions 的 SignalR 服務輸入系結
客戶端必須先擷取服務端點 URL 和有效的存取令牌，用戶端才能連線到 Azure SignalR 服務。 SignalRConnectionInfo 輸入系結會產生 SignalR 服務端點 URL 和用來連線至服務的有效令牌。 令牌有時間限制，可用來驗證連線的特定使用者。 因此，您不應該快取令牌或在客戶端之間共用令牌。 您通常會使用 SignalRConnectionInfo 搭配 HTTP 觸發程式，讓用戶端擷取連線資訊。
如需如何使用此系結來建立與 SignalR 用戶端 SDK 相容的「交涉」函式的詳細資訊，請參閱 使用 Azure SignalR Service 進行 Azure Functions 開發和設定。 如需安裝和組態詳細數據的詳細資訊，請參閱概 觀。
範例
您可以使用下列其中一種 C# 模式來建立 C# 函式：
- 隔離的背景工作模型：在與運行時間隔離的背景工作進程中執行的已編譯 C# 函式。 需要隔離的背景工作進程，才能支援在 LTS 和非 LTS 版本 .NET 和 .NET Framework 上執行的 C# 函式。
- 同進程模型：在與 Functions 運行時間相同的進程中執行的已編譯 C# 函式。
- C# 文稿：主要用於在 Azure 入口網站 中建立 C# 函式。
重要
內含式模型支援將於 2026 年 11 月 10 日結束。 強烈建議您將應用程式移轉至隔離式背景工作角色模型，以取得完整支援。
下列範例示範 使用輸入系結取得 SignalR 連線資訊的 C# 函式 ，並透過 HTTP 傳回它。
[Function(nameof(Negotiate))]
public static string Negotiate([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
[SignalRConnectionInfoInput(HubName = "serverless")] string connectionInfo)
{
// The serialization of the connection info object is done by the framework. It should be camel case. The SignalR client respects the camel case response only.
return connectionInfo;
}
下列範例顯示function.json檔案中的 SignalR 連線資訊輸入系結，以及使用系結傳回連接資訊的函式。
以下是 function.json 檔案中範例的系結數據：
{
"type": "signalRConnectionInfo",
"name": "connectionInfo",
"hubName": "hubName1",
"connectionStringSetting": "<name of setting containing SignalR Service connection string>",
"direction": "in"
}
以下是 JavaScript 程式碼：
const { app, input } = require('@azure/functions');
const inputSignalR = input.generic({
type: 'signalRConnectionInfo',
name: 'connectionInfo',
hubName: 'hubName1',
connectionStringSetting: 'AzureSignalRConnectionString',
});
app.post('negotiate', {
authLevel: 'function',
handler: (request, context) => {
return { body: JSON.stringify(context.extraInputs.get(inputSignalR)) }
},
route: 'negotiate',
extraInputs: [inputSignalR],
});
完整的 PowerShell 範例擱置中。
下列範例顯示function.json檔案中的 SignalR 連線資訊輸入系結，以及使用系結傳回連線資訊的 Python 函式。
以下是 Python 程式碼：
def main(req: func.HttpRequest, connectionInfoJson: str) -> func.HttpResponse:
return func.HttpResponse(
connectionInfoJson,
status_code=200,
headers={
'Content-type': 'application/json'
}
)
下列範例示範使用 輸入系結取得 SignalR 連線資訊的 Java 函式 ，並透過 HTTP 傳回它。
@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
@HttpTrigger(
name = "req",
methods = { HttpMethod.POST },
authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> req,
@SignalRConnectionInfoInput(
name = "connectionInfo",
HubName = "hubName1") SignalRConnectionInfo connectionInfo) {
return connectionInfo;
}
使用方式
已驗證權杖
當已驗證的用戶端觸發函式時，您可以將使用者標識碼宣告新增至產生的令牌。 您可以使用App Service 驗證，輕鬆地將驗證新增至函式應用程式。
App Service 驗證會分別設定名為 x-ms-client-principal-id 且 x-ms-client-principal-name 包含已驗證使用者的用戶端主體標識碼和名稱的 HTTP 標頭。
您可以使用繫結運算式：{headers.x-ms-client-principal-id} 或 {headers.x-ms-client-principal-name}，將繫結的 UserId 屬性設為任一標頭的值。
[Function("Negotiate")]
public static string Negotiate([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
[SignalRConnectionInfoInput(HubName = "hubName1", UserId = "{headers.x-ms-client-principal-id}")] string connectionInfo)
{
// The serialization of the connection info object is done by the framework. It should be camel case. The SignalR client respects the camel case response only.
return connectionInfo;
}
@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
@HttpTrigger(
name = "req",
methods = { HttpMethod.POST, HttpMethod.GET },
authLevel = AuthorizationLevel.ANONYMOUS)
HttpRequestMessage<Optional<String>> req,
@SignalRConnectionInfoInput(name = "connectionInfo", hubName = "hubName1", userId = "{headers.x-ms-signalr-userid}") SignalRConnectionInfo connectionInfo) {
return connectionInfo;
}
以下是 function.json 檔案中的繫結資料：
{
"type": "signalRConnectionInfo",
"name": "connectionInfo",
"hubName": "hubName1",
"userId": "{headers.x-ms-client-principal-id}",
"connectionStringSetting": "<name of setting containing SignalR Service connection string>",
"direction": "in"
}
以下是 JavaScript 程式碼：
const { app, input } = require('@azure/functions');
const inputSignalR = input.generic({
type: 'signalRConnectionInfo',
name: 'connectionInfo',
hubName: 'hubName1',
connectionStringSetting: 'AzureSignalRConnectionString',
userId: '{headers.x-ms-client-principal-id}',
});
app.post('negotiate', {
authLevel: 'function',
handler: (request, context) => {
return { body: JSON.stringify(context.extraInputs.get(inputSignalR)) }
},
route: 'negotiate',
extraInputs: [inputSignalR],
});
完整的 PowerShell 範例擱置中。
以下是 Python 程式碼：
def main(req: func.HttpRequest, connectionInfo: str) -> func.HttpResponse:
# connectionInfo contains an access key token with a name identifier
# claim set to the authenticated user
return func.HttpResponse(
connectionInfo,
status_code=200,
headers={
'Content-type': 'application/json'
}
)
@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
@HttpTrigger(
name = "req",
methods = { HttpMethod.POST },
authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> req,
@SignalRConnectionInfoInput(
name = "connectionInfo",
HubName = "hubName1",
userId = "{headers.x-ms-client-principal-id}") SignalRConnectionInfo connectionInfo) {
return connectionInfo;
}
屬性
進程內和隔離的背景工作進程 C# 連結庫都會使用 屬性來定義函式。 C# 文稿會改用function.json組態檔。
下表說明 屬性的屬性 SignalRConnectionInfoInput ：
| 屬性內容 | 描述 |
|---|---|
| HubName | 必要。 中樞名稱。 |
| ConnectionStringSetting | 包含 SignalR Service 連接字串 的應用程式設定名稱，預設為 AzureSignalRConnectionString。 |
| UserId | 選擇性。 SignalR 連線的用戶標識碼。 您可以使用系 結運算式 將值系結至 HTTP 要求標頭或查詢。 |
| IdToken | 選擇性。 將宣告新增至使用者宣告的 JWT 令牌。 它應該與 ClaimTypeList 一起使用。 您可以使用系 結運算式 將值系結至 HTTP 要求標頭或查詢。 |
| ClaimTypeList | 選擇性。 宣告類型清單，其會篩選IdToken中的宣告。 |
註釋
下表說明批注支持的設定 SignalRConnectionInfoInput 。
| 設定 | 描述 |
|---|---|
| name | 用於連接資訊物件的函式程式代碼中的變數名稱。 |
| hubName | 必要。 中樞名稱。 |
| connectionStringSetting | 包含 SignalR Service 連接字串 的應用程式設定名稱，預設為 AzureSignalRConnectionString。 |
| userId | 選擇性。 SignalR 連線的用戶標識碼。 您可以使用系 結運算式 將值系結至 HTTP 要求標頭或查詢。 |
| idToken | 選擇性。 將宣告新增至使用者宣告的 JWT 令牌。 它應該與 claimTypeList 一起使用。 您可以使用系 結運算式 將值系結至 HTTP 要求標頭或查詢。 |
| claimTypeList | 選擇性。 宣告類型清單，其會篩選 idToken 中的宣告。 |
註釋
下表說明批注支持的設定 SignalRConnectionInfoInput 。
| 設定 | 描述 |
|---|---|
| name | 用於連接資訊物件的函式程式代碼中的變數名稱。 |
| hubName | 必要。 中樞名稱。 |
| connectionStringSetting | 包含 SignalR Service 連接字串 的應用程式設定名稱，預設為 AzureSignalRConnectionString。 |
| userId | 選擇性。 SignalR 連線的用戶標識碼。 您可以使用系 結運算式 將值系結至 HTTP 要求標頭或查詢。 |
| idToken | 選擇性。 將宣告新增至使用者宣告的 JWT 令牌。 它應該與 claimTypeList 一起使用。 您可以使用系 結運算式 將值系結至 HTTP 要求標頭或查詢。 |
| claimTypeList | 選擇性。 宣告類型清單，其會篩選 idToken 中的宣告。 |
組態
下表說明您在 function.json 檔案中設定的繫結設定屬性。
| function.json 屬性 | 描述 |
|---|---|
| type | 必須設定為 signalRConnectionInfo。 |
| direction | 必須設定為 in。 |
| hubName | 必要。 中樞名稱。 |
| connectionStringSetting | 包含 SignalR Service 連接字串 的應用程式設定名稱，預設為 AzureSignalRConnectionString。 |
| userId | 選擇性。 SignalR 連線的用戶標識碼。 您可以使用系 結運算式 將值系結至 HTTP 要求標頭或查詢。 |
| idToken | 選擇性。 將宣告新增至使用者宣告的 JWT 令牌。 它應該與 claimTypeList 一起使用。 您可以使用系 結運算式 將值系結至 HTTP 要求標頭或查詢。 |
| claimTypeList | 選擇性。 宣告類型清單，其會篩選 idToken 中的宣告。 |
HTTP 觸發程式的系結表達式
這是一個常見的案例，SignalR 輸入系結的某些屬性值來自 HTTP 要求。 因此，我們會示範如何透過 系結表達式，將 HTTP 要求中的值系結至 SignalR 輸入系結屬性。
| HTTP 元數據類型 | 系結表達式格式 | 描述 | 範例 |
|---|---|---|---|
| HTTP 要求查詢 | {query.QUERY_PARAMETER_NAME} |
將對應查詢參數的值系結至屬性 | {query.userName} |
| HTTP 要求標頭 | {headers.HEADER_NAME} |
將標頭的值系結至屬性 | {headers.token} |