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

01/04/2021

使用 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 } 
        });
}

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

示例 function.json：Example function.json:

{
  "type": "signalR",
  "name": "signalRMessages",
  "hubName": "<hub_name>",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

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

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

public static Task Run(
    object message,
    IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage 
        {
            Target = "newMessage", 
            Arguments = new [] { message } 
        });
}

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

示例 function.json：Example function.json:

{
  "type": "signalR",
  "name": "signalRMessages",
  "hubName": "<hub_name>",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

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

module.exports = async function (context, req) {
    context.bindings.signalRMessages = [{
        "target": "newMessage",
        "arguments": [ req.body ]
    }];
};

@FunctionName("sendMessage")
@SignalROutput(name = "$return", hubName = "chat")
public SignalRMessage sendMessage(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Object> req) {

    SignalRMessage message = new SignalRMessage();
    message.target = "newMessage";
    message.arguments.add(req.getBody());
    return 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 }
        });
}

示例 function.json：Example function.json:

{
  "type": "signalR",
  "name": "signalRMessages",
  "hubName": "<hub_name>",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

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

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

public static Task Run(
    object message,
    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 } 
        });
}

示例 function.json：Example function.json:

{
  "type": "signalR",
  "name": "signalRMessages",
  "hubName": "<hub_name>",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

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

module.exports = async function (context, req) {
    context.bindings.signalRMessages = [{
        // message will only be sent to this user ID
        "userId": "userId1",
        "target": "newMessage",
        "arguments": [ req.body ]
    }];
};

@FunctionName("sendMessage")
@SignalROutput(name = "$return", hubName = "chat")
public SignalRMessage sendMessage(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Object> req) {

    SignalRMessage message = new SignalRMessage();
    message.userId = "userId1";
    message.target = "newMessage";
    message.arguments.add(req.getBody());
    return 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 }
        });
}

示例 function.json：Example function.json:

{
  "type": "signalR",
  "name": "signalRMessages",
  "hubName": "<hub_name>",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

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

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

public static Task Run(
    object message,
    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 } 
        });
}

示例 function.json：Example function.json:

{
  "type": "signalR",
  "name": "signalRMessages",
  "hubName": "<hub_name>",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

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

module.exports = async function (context, req) {
    context.bindings.signalRMessages = [{
        // message will only be sent to this group
        "groupName": "myGroup",
        "target": "newMessage",
        "arguments": [ req.body ]
    }];
};

@FunctionName("sendMessage")
@SignalROutput(name = "$return", hubName = "chat")
public SignalRMessage sendMessage(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Object> req) {

    SignalRMessage message = new SignalRMessage();
    message.groupName = "myGroup";
    message.target = "newMessage";
    message.arguments.add(req.getBody());
    return 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.

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

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

示例 function.json Example function.json

{
    "type": "signalR",
    "name": "signalRGroupActions",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "hubName": "chat",
    "direction": "out"
}

Run.csx Run.csx

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

public static Task Run(
    HttpRequest req,
    ClaimsPrincipal claimsPrincipal,
    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.

示例 function.json Example function.json

{
    "type": "signalR",
    "name": "signalRGroupActions",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "hubName": "chat",
    "direction": "out"
}

Run.csx Run.csx

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

public static Task Run(
    HttpRequest req,
    ClaimsPrincipal claimsPrincipal,
    IAsyncCollector<SignalRGroupAction> signalRGroupActions)
{
    var userIdClaim = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier);
    return signalRGroupActions.AddAsync(
        new SignalRGroupAction
        {
            UserId = userIdClaim.Value,
            GroupName = "myGroup",
            Action = GroupAction.Remove
        });
}

备注

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

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

示例 function.json Example function.json

{
    "type": "signalR",
    "name": "signalRGroupActions",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "hubName": "chat",
    "direction": "out"
}

index.jsindex.js

module.exports = async function (context, req) {
  context.bindings.signalRGroupActions = [{
    "userId": req.query.userId,
    "groupName": "myGroup",
    "action": "add"
  }];
};

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

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

示例 function.json Example function.json

{
    "type": "signalR",
    "name": "signalRGroupActions",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "hubName": "chat",
    "direction": "out"
}

index.jsindex.js

module.exports = async function (context, req) {
  context.bindings.signalRGroupActions = [{
    "userId": req.query.userId,
    "groupName": "myGroup",
    "action": "remove"
  }];
};

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

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

@FunctionName("addToGroup")
@SignalROutput(name = "$return", hubName = "chat")
public SignalRGroupAction addToGroup(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Object> req,
        @BindingName("userId") String userId) {

    SignalRGroupAction groupAction = new SignalRGroupAction();
    groupAction.action = "add";
    groupAction.userId = userId;
    groupAction.groupName = "myGroup";
    return action;
}

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

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

@FunctionName("removeFromGroup")
@SignalROutput(name = "$return", hubName = "chat")
public SignalRGroupAction removeFromGroup(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Object> req,
        @BindingName("userId") String userId) {

    SignalRGroupAction groupAction = new SignalRGroupAction();
    groupAction.action = "remove";
    groupAction.userId = userId;
    groupAction.groupName = "myGroup";
    return action;
}

配置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	必须设置为 `signalRConnectionInfo`。Must be set to `signalRConnectionInfo`.
direction direction	不适用n/a	必须设置为 `in`。Must 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	必须设置为 `signalR`。Must be set to `signalR`.
direction direction	不适用n/a	必须设置为 `out`。Must 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.

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

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

发送给用户Send to a user

发送给组Send to a group

组管理Group management

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

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

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

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

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

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

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

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

配置Configuration

SignalRConnectionInfoSignalRConnectionInfo

SignalRSignalR

后续步骤Next steps

此页面有帮助吗?

此页面有帮助吗?