Azure Functions 的 SignalR 服务输出绑定SignalR Service output binding for Azure Functions

使用 Azure SignalR 服务,通过 SignalR 输出绑定发送一条或多条消息。Use the SignalR output binding to send one or more messages using Azure SignalR Service. 可以将消息广播到:You can broadcast a message to:

  • 所有连接的客户端All connected clients
  • 对特定用户进行身份验证的已连接客户端Connected clients authenticated to a specific user

输出绑定还允许管理组。The output binding also allows you to manage groups.

若要了解设置和配置详细信息,请参阅概述For information on setup and configuration details, see the overview.

广播到所有客户端Broadcast to all clients

以下示例演示使用输出绑定将一条消息发送给所有连接的客户端的函数。The following example shows a function that sends a message using the output binding to all connected clients. target 是需要在每个客户端上调用的方法的名称 。The target is the name of the method to be invoked on each client. Arguments 属性是一个数组,其中包含要传递给客户端方法的零个或多个对象。The Arguments property is an array of zero or more objects to be passed to the client method.

[FunctionName("SendMessage")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]object message, 
    [SignalR(HubName = "chat")]IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage 
        {
            Target = "newMessage", 
            Arguments = new [] { message } 
        });
}

发送给用户Send to a user

可以设置 SignalR 消息的用户 ID,以便将消息只发送给已针对某个用户进行身份验证的连接 。You can send a message only to connections that have been authenticated to a user by setting the user ID in the SignalR message.

[FunctionName("SendMessage")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]object message, 
    [SignalR(HubName = "chat")]IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage 
        {
            // the message will only be sent to this user ID
            UserId = "userId1",
            Target = "newMessage",
            Arguments = new [] { message }
        });
}

发送给组Send to a group

可以设置 SignalR 消息的组名称,以便将消息只发送给已添加到某个组的连接 。You can send a message only to connections that have been added to a group by setting the group name in the SignalR message.

[FunctionName("SendMessage")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]object message,
    [SignalR(HubName = "chat")]IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage
        {
            // the message will be sent to the group with this name
            GroupName = "myGroup",
            Target = "newMessage",
            Arguments = new [] { message }
        });
}

组管理Group management

SignalR 服务允许将用户添加到组。SignalR Service allows users to be added to groups. 然后即可将消息发送到组。Messages can then be sent to a group. 可以使用 SignalR 输出绑定来管理用户的组成员身份。You can use the SignalR output binding to manage a user's group membership.

将用户添加到组Add user to a group

以下示例将用户添加到组。The following example adds a user to a group.

[FunctionName("addToGroup")]
public static Task AddToGroup(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]HttpRequest req,
    ClaimsPrincipal claimsPrincipal,
    [SignalR(HubName = "chat")]
        IAsyncCollector<SignalRGroupAction> signalRGroupActions)
{
    var userIdClaim = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier);
    return signalRGroupActions.AddAsync(
        new SignalRGroupAction
        {
            UserId = userIdClaim.Value,
            GroupName = "myGroup",
            Action = GroupAction.Add
        });
}

从组中删除用户Remove user from a group

以下示例从组中删除用户。The following example removes a user from a group.

[FunctionName("removeFromGroup")]
public static Task RemoveFromGroup(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]HttpRequest req,
    ClaimsPrincipal claimsPrincipal,
    [SignalR(HubName = "chat")]
        IAsyncCollector<SignalRGroupAction> signalRGroupActions)
{
    var userIdClaim = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier);
    return signalRGroupActions.AddAsync(
        new SignalRGroupAction
        {
            UserId = userIdClaim.Value,
            GroupName = "myGroup",
            Action = GroupAction.Remove
        });
}

备注

若要正确绑定 ClaimsPrincipal,必须已经在 Azure Functions 中配置身份验证设置。In order to get the ClaimsPrincipal correctly bound, you must have configured the authentication settings in Azure Functions.

配置Configuration

SignalRConnectionInfoSignalRConnectionInfo

下表解释了在 function.json 文件和 SignalRConnectionInfo 特性中设置的绑定配置属性。The following table explains the binding configuration properties that you set in the function.json file and the SignalRConnectionInfo attribute.

function.json 属性function.json property Attribute 属性Attribute property 说明Description
type type 不适用n/a 必须设置为 signalRConnectionInfoMust be set to signalRConnectionInfo.
direction direction 不适用n/a 必须设置为 inMust be set to in.
name name 不适用n/a 变量名称,在连接信息对象的函数代码中使用。Variable name used in function code for connection info object.
hubNamehubName HubNameHubName 此值必须设置为 SignalR 中心(将为其生成连接信息)的名称。This value must be set to the name of the SignalR hub for which the connection information is generated.
userIduserId UserIdUserId 可选:将要在访问密钥令牌中设置的用户标识符声明的值。Optional: The value of the user identifier claim to be set in the access key token.
connectionStringSettingconnectionStringSetting ConnectionStringSettingConnectionStringSetting 应用设置的名称,该设置包含 SignalR 服务连接字符串(默认为“AzureSignalRConnectionString”)The name of the app setting that contains the SignalR Service connection string (defaults to "AzureSignalRConnectionString")

SignalRSignalR

下表解释了在 function.json 文件和 SignalR 特性中设置的绑定配置属性。The following table explains the binding configuration properties that you set in the function.json file and the SignalR attribute.

function.json 属性function.json property Attribute 属性Attribute property 说明Description
type type 不适用n/a 必须设置为 signalRMust be set to signalR.
direction direction 不适用n/a 必须设置为 outMust be set to out.
name name 不适用n/a 变量名称,在连接信息对象的函数代码中使用。Variable name used in function code for connection info object.
hubNamehubName HubNameHubName 此值必须设置为 SignalR 中心(将为其生成连接信息)的名称。This value must be set to the name of the SignalR hub for which the connection information is generated.
connectionStringSettingconnectionStringSetting ConnectionStringSettingConnectionStringSetting 应用设置的名称,该设置包含 SignalR 服务连接字符串(默认为“AzureSignalRConnectionString”)The name of the app setting that contains the SignalR Service connection string (defaults to "AzureSignalRConnectionString")

在本地进行开发时,应用设置将取 local.settings.json 文件的值。When you're developing locally, app settings go into the local.settings.json file.

后续步骤Next steps