Azure Functions 的 SignalR 服务输入绑定SignalR Service input binding for Azure Functions

01/04/2021

客户端在连接到 Azure SignalR 服务之前，必须检索服务终结点 URL 和有效的访问令牌。Before a client can connect to Azure SignalR Service, it must retrieve the service endpoint URL and a valid access token. SignalRConnectionInfo 输入绑定生成 SignalR 服务终结点 URL 和有效的令牌，这两者可以用来连接到服务。The SignalRConnectionInfo input binding produces the SignalR Service endpoint URL and a valid token that are used to connect to the service. 由于此令牌有时间限制，并且可以用来对需要连接的特定用户进行身份验证，因此不应缓存此令牌，也不应在客户端之间共享它。Because the token is time-limited and can be used to authenticate a specific user to a connection, you should not cache the token or share it between clients. 使用此绑定的 HTTP 触发器可供客户端用来检索连接信息。An HTTP trigger using this binding can be used by clients to retrieve the connection information.

若要详细了解如何使用此绑定来创建一个可以由 SignalR 客户端 SDK 使用的“协商”函数，请参阅 SignalR 服务概念文档中的“Azure Functions 开发和配置”一文。For more information on how this binding is used to create a "negotiate" function that can be consumed by a SignalR client SDK, see the Azure Functions development and configuration article in the SignalR Service concepts documentation.

有关设置和配置详细信息，请参阅概述。For information on setup and configuration details, see the overview.

示例Example

以下示例演示了一个 C# 函数，该函数使用输入绑定获取 SignalR 连接信息，并通过 HTTP 将其返回。The following example shows a C# function that acquires SignalR connection information using the input binding and returns it over HTTP.

[FunctionName("negotiate")]
public static SignalRConnectionInfo Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req,
    [SignalRConnectionInfo(HubName = "chat")]SignalRConnectionInfo connectionInfo)
{
    return connectionInfo;
}

以下示例演示 function.json 文件中的一个 SignalR 连接信息输入绑定，以及使用该绑定来返回连接信息的 C# Script 函数。The following example shows a SignalR connection info input binding in a function.json file and a C# Script function that uses the binding to return the connection information.

下面是 function.json 文件中的绑定数据：Here's binding data in the function.json file:

示例 function.json：Example function.json:

{
    "type": "signalRConnectionInfo",
    "name": "connectionInfo",
    "hubName": "chat",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "direction": "in"
}

C# 脚本代码如下所示：Here's the C# Script code:

#r "Microsoft.Azure.WebJobs.Extensions.SignalRService"
using Microsoft.Azure.WebJobs.Extensions.SignalRService;

public static SignalRConnectionInfo Run(HttpRequest req, SignalRConnectionInfo connectionInfo)
{
    return connectionInfo;
}

以下示例演示 function.json 文件中的一个 SignalR 连接信息输入绑定，以及使用该绑定来返回连接信息的 JavaScript 函数。The following example shows a SignalR connection info input binding in a function.json file and a JavaScript function that uses the binding to return the connection information.

下面是 function.json 文件中的绑定数据：Here's binding data in the function.json file:

示例 function.json：Example function.json:

{
    "type": "signalRConnectionInfo",
    "name": "connectionInfo",
    "hubName": "chat",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "direction": "in"
}

JavaScript 代码如下所示：Here's the JavaScript code:

module.exports = async function (context, req, connectionInfo) {
    context.res.body = connectionInfo;
};

以下示例演示了一个 Java 函数，该函数使用输入绑定获取 SignalR 连接信息，并通过 HTTP 将其返回。The following example shows a Java function that acquires SignalR connection information using the input binding and returns it over HTTP.

@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> req,
        @SignalRConnectionInfoInput(
            name = "connectionInfo",
            hubName = "chat") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

已进行身份验证的令牌Authenticated tokens

如果此函数由经过身份验证的客户端触发，则可向生成的令牌添加用户 ID 声明。If the function is triggered by an authenticated client, you can add a user ID claim to the generated token. 可以轻松地使用应用服务身份验证向函数应用添加身份验证。You can easily add authentication to a function app using App Service Authentication.

应用服务身份验证会设置名为 x-ms-client-principal-id 和 x-ms-client-principal-name（分别包含经身份验证的用户的客户端主体 ID 和名称）的 HTTP 标头。App Service Authentication sets HTTP headers named x-ms-client-principal-id and x-ms-client-principal-name that contain the authenticated user's client principal ID and name, respectively.

可以使用绑定表达式{headers.x-ms-client-principal-id} 或 {headers.x-ms-client-principal-name} 将绑定的 UserId 属性设置为任一标头中的值。You can set the UserId property of the binding to the value from either header using a binding expression: {headers.x-ms-client-principal-id} or {headers.x-ms-client-principal-name}.

[FunctionName("negotiate")]
public static SignalRConnectionInfo Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req, 
    [SignalRConnectionInfo
        (HubName = "chat", UserId = "{headers.x-ms-client-principal-id}")]
        SignalRConnectionInfo connectionInfo)
{
    // connectionInfo contains an access key token with a name identifier claim set to the authenticated user
    return connectionInfo;
}

可以使用绑定表达式{headers.x-ms-client-principal-id} 或 {headers.x-ms-client-principal-name} 将绑定的 userId 属性设置为任一标头中的值。You can set the userId property of the binding to the value from either header using a binding expression: {headers.x-ms-client-principal-id} or {headers.x-ms-client-principal-name}.

示例 function.json：Example function.json:

{
    "type": "signalRConnectionInfo",
    "name": "connectionInfo",
    "hubName": "chat",
    "userId": "{headers.x-ms-client-principal-id}",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "direction": "in"
}

C# 脚本代码如下所示：Here's the C# Script code:

#r "Microsoft.Azure.WebJobs.Extensions.SignalRService"
using Microsoft.Azure.WebJobs.Extensions.SignalRService;

public static SignalRConnectionInfo Run(HttpRequest req, SignalRConnectionInfo connectionInfo)
{
    // connectionInfo contains an access key token with a name identifier
    // claim set to the authenticated user
    return connectionInfo;
}

示例 function.json：Example function.json:

{
    "type": "signalRConnectionInfo",
    "name": "connectionInfo",
    "hubName": "chat",
    "userId": "{headers.x-ms-client-principal-id}",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "direction": "in"
}

JavaScript 代码如下所示：Here's the JavaScript code:

module.exports = async function (context, req, connectionInfo) {
    // connectionInfo contains an access key token with a name identifier
    // claim set to the authenticated user
    context.res.body = connectionInfo;
};

@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> req,
        @SignalRConnectionInfoInput(
            name = "connectionInfo",
            hubName = "chat",
            userId = "{headers.x-ms-client-principal-id}") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

Azure Functions 的 SignalR 服务输入绑定SignalR Service input binding for Azure Functions

示例Example

已进行身份验证的令牌Authenticated tokens

后续步骤Next steps

此页面有帮助吗?

此页面有帮助吗?