Привязки службы SignalR для службы "Функции Azure"SignalR Service bindings for Azure Functions

В этой статье объясняется, как пройти проверку подлинности и отправлять сообщения в режиме реального времени для клиентов, подключенных к службе Azure SignalR с использованием привязок службы SignalR в службе "Функции Azure".This article explains how to authenticate and send real-time messages to clients connected to Azure SignalR Service by using SignalR Service bindings in Azure Functions. Служба "Функции Azure" поддерживает входные и выходные привязки для службы SignalR.Azure Functions supports input and output bindings for SignalR Service.

Это справочные сведения для разработчиков функций Azure.This is reference information for Azure Functions developers. Если вы новичок в функциях Azure, начните со следующих ресурсов:If you're new to Azure Functions, start with the following resources:

Packages — функции 2. x и более поздних версийPackages - Functions 2.x and higher

Привязки службы SignalR предоставляются в пакете NuGet Microsoft. Azure. веб-задания. Extensions. сигналрсервице , версия 1. *.The SignalR Service bindings are provided in the Microsoft.Azure.WebJobs.Extensions.SignalRService NuGet package, version 1.*. Исходный код для пакета находится в репозитории GitHub azure-functions-signalrservice-extension.Source code for the package is in the azure-functions-signalrservice-extension GitHub repository.

В следующей таблице указано как добавить поддержку для этой привязки в каждой среде разработки.The following table tells how to add support for this binding in each development environment.

Среда разработкиDevelopment environment Добавление поддержкиTo add support
Локальная разработка – библиотека классов C#Local development - C# class library Установка пакетаInstall the package
Локальная разработка – Скрипт C#, JavaScript, F#Local development - C# script, JavaScript, F# Регистрация расширенияRegister the extension
Разработка на порталеPortal development Регистрация расширенияRegister the extension

Дополнительные сведения об обновлении существующих расширений привязки на портале, не переиздавая проект приложения-функции, см. раздел Обновление расширений.To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

Дополнительные сведения о настройке и использовании службы SignalR и функций Azure см. в статье Разработка и Настройка функций Azure с помощью службы Azure SignalR.For details on how to configure and use SignalR Service and Azure Functions together, refer to Azure Functions development and configuration with Azure SignalR Service.

Библиотека заметок (только для Java)Annotations library (Java only)

Чтобы использовать заметки службы SignalR в функциях Java, необходимо добавить зависимость к артефакту Azure-functions-Java-Library-SignalR (версии 1,0 или более поздней) в файл POM. XML.To use the SignalR Service annotations in Java functions, you need to add a dependency to the azure-functions-java-library-signalr artifact (version 1.0 or higher) to your pom.xml.

<dependency>
    <groupId>com.microsoft.azure.functions</groupId>
    <artifactId>azure-functions-java-library-signalr</artifactId>
    <version>1.0.0</version>
</dependency>

Входные данныеInput

Прежде чем клиент сможет подключиться к службе 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 создает URL-адрес конечной точки службы SignalR и допустимый маркер, которые используются для подключения к службе.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.

Дополнительные сведения о том, как эта привязка используется для создания функции "Negotiate", которая может использоваться клиентским пакетом SDK для SignalR, см. в статье о разработке и настройке функций Azure в документации по основным понятиям службы SignalR.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.

В следующем примере показана функция 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;
}

Прошедшие проверку подлинности маркерыAuthenticated tokens

Если функцию активирует прошедший проверку подлинности клиент, вы можете добавить утверждение идентификатора пользователя для созданного маркера.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.

Проверка подлинности службы приложений задает заголовки HTTP x-ms-client-principal-id и x-ms-client-principal-name, содержащие имя и идентификатор субъекта клиента прошедшего проверку подлинности пользователя соответственно.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.

В качестве значения свойства UserId привязки можно задать один из заголовков с помощью выражения привязки: {headers.x-ms-client-principal-id} или {headers.x-ms-client-principal-name}.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;
}

Выходные данныеOutput

Выходная привязка SignalR используется для отправки одного или нескольких сообщений с помощью службы Azure 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, or you can broadcast it only to connected clients that have been authenticated to a given user.

Его также можно использовать для управления группами, к которым принадлежит пользователь.You can also use it to manage the groups that a user belongs to.

Широковещательная передача для всех клиентовBroadcast to all clients

В следующем примере показана функция, которая отправляет сообщение, используя выходную привязку для всех подключенных клиентов.The following example shows a function that sends a message using the output binding to all connected clients. Целевым объектом является имя метода, вызываемого на каждом клиенте.The target is the name of the method to be invoked on each client. Аргументы — это массив из нуля или более объектов, которые должны быть переданы в клиентский метод.Arguments 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.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.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.jsonfunction.json property Свойство атрибутаAttribute property DescriptionDescription
typetype Н/Дn/a Нужно задать значение signalRConnectionInfo.Must be set to signalRConnectionInfo.
directiondirection Н/Дn/a Нужно задать значение in.Must be set to in.
namename Н/Д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.jsonfunction.json property Свойство атрибутаAttribute property DescriptionDescription
typetype Н/Дn/a Нужно задать значение signalR.Must be set to signalR.
directiondirection Н/Дn/a Нужно задать значение out.Must be set to out.
namename Н/Д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

Azure Functions development and configuration with Azure SignalR Service (Разработка и настройка функций Azure с помощью Службы Azure SignalR)Azure Functions development and configuration with Azure SignalR Service