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

Приложения Azure Functions могут использовать привязки службы Azure SignalR для добавления возможностей работы в режиме реального времени. Клиентские приложения используют клиентские пакеты SDK, доступные на нескольких языках, для подключения к Службе Azure SignalR и получения сообщений в режиме реального времени.

В этой статье описываются основные понятия разработки и настройки приложения-функции Azure с интеграцией со Службой SignalR.

Конфигурация Службы SignalR

Служба Azure SignalR можно настроить в разных режимах. При использовании с платформой Функции Azure служба должна быть настроена в Бессерверном режиме.

На портале Azure откройте страницу Параметры для ресурса Службы SignalR. Установите Режим службы — Бессерверный.

Разработка функций Azure

Для приложения в режиме реального времени, созданного с использованием функций Azure и службы Azure SignalR, требуется по крайней мере две функции Azure:

• Функцияnegotiate, вызываемая клиентом для получения действительного маркера доступа к службе SignalR и URL-адреса конечной точки.
• Одна или несколько функций, обрабатывающих сообщения, отправляемые из службы SignalR клиентам.

Функция согласования

Клиентскому приложению требуется допустимый токен доступа для подключения к Службе Azure SignalR. Маркер доступа может быть анонимным или прошедшим проверку подлинности в идентификаторе пользователя. Бессерверным приложениям службы SignalR требуется конечная точка HTTP с именем negotiate, чтобы получить токен и другую информацию о подключении, например URL-адрес конечной точки службы SignalR.

Используйте функцию Azure с триггером HTTP и SignalRConnectionInfo входную привязку для создания объекта сведений о подключении. Функция должна иметь маршрут HTTP, который заканчивается на /negotiate.

При использовании модели на основе классов в C#не требуется SignalRConnectionInfo входная привязка и можно гораздо проще добавлять пользовательские утверждения. Дополнительные сведения см. в разделе «Опыт согласования в модели, основанной на классах».

Для получения дополнительной информации о функции negotiate, обратитесь к разделу разработка Azure Functions.

Чтобы узнать, как создать аутентифицированный токен, см. статью "Использование аутентификации в Службе приложений".

Обработка сообщений от Службы SignalR

Используйте привязку SignalRTrigger для обработки сообщений, отправленных из службы SignalR. Вы можете получать уведомления, когда клиенты отправляют сообщения или когда клиенты подключаются и отключаются.

Для получения дополнительной информации см. справочник по привязке триггеров службы SignalR.

Кроме того, необходимо настроить конечную точку функции как вышестоящую конечную точку, чтобы служба активировала функцию при наличии сообщения от клиента. Дополнительные сведения о настройке конечных точек вышестоящего потока см. в разделе "Конечные точки вышестоящего потока".

Отправка сообщений и управление членством в группах

Используйте выходную привязку SignalR для отправки сообщений клиентам, подключенным к Служба Azure SignalR. Вы можете передавать сообщения всем клиентам или отправлять их в подмножество клиентов. Например, только отправлять сообщения клиентам, прошедшим проверку подлинности с определенным идентификатором пользователя или только в определенную группу.

Пользователи могут быть добавлены в одну или несколько групп. Вы также можете использовать выходную привязку SignalR для добавления или удаления пользователей в группы или из нее.

Для получения дополнительной информации см. справочник по выходному привязочному интерфейсу.

Хабы SignalR

SignalR имеет концепцию хабов. Каждое клиентское подключение и каждое сообщение, отправленное из Функций Azure, ограничены конкретным концентратором. Центры обработки можно использовать в качестве способа разделения подключений и сообщений на логические пространства имен.

Модель на основе классов

Модель на основе классов выделена для C#.

[SignalRConnection("AzureSignalRConnectionString")]
public class Functions : ServerlessHub
{
    private const string HubName = nameof(Functions); // Used by SignalR trigger only

    public Functions(IServiceProvider serviceProvider) : base(serviceProvider)
    {
    }

    [Function("negotiate")]
    public async Task<HttpResponseData> Negotiate([HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequestData req)
    {
        var negotiateResponse = await NegotiateAsync(new() { UserId = req.Headers.GetValues("userId").FirstOrDefault() });
        var response = req.CreateResponse();
        response.WriteBytes(negotiateResponse.ToArray());
        return response;
    }

    [Function("Broadcast")]
    public Task Broadcast(
    [SignalRTrigger(HubName, "messages", "broadcast", "message")] SignalRInvocationContext invocationContext, string message)
    {
        return Clients.All.SendAsync("newMessage", new NewMessage(invocationContext, message));
    }

    [Function("JoinGroup")]
    public Task JoinGroup([SignalRTrigger(HubName, "messages", "JoinGroup", "connectionId", "groupName")] SignalRInvocationContext invocationContext, string connectionId, string groupName)
    {
        return Groups.AddToGroupAsync(connectionId, groupName);
    }
}

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(b => b.Services
        .AddServerlessHub<Functions>())
    .Build();

Task<BinaryData> NegotiateAsync(NegotiationOptions? options = null)

public interface IChatClient
{
    Task newMessage(NewMessage message);
}

[SignalRConnection("AzureSignalRConnectionString")]
public class Functions : ServerlessHub<IChatClient>
{
    private const string HubName = nameof(Functions);  // Used by SignalR trigger only

    public Functions(IServiceProvider serviceProvider) : base(serviceProvider)
    {
    }

    [Function("Broadcast")]
    public Task Broadcast(
    [SignalRTrigger(HubName, "messages", "broadcast", "message")] SignalRInvocationContext invocationContext, string message)
    {
        return Clients.All.newMessage(new NewMessage(invocationContext, message));
    }
}

public class HubName1 : ServerlessHub
{
    [FunctionName("negotiate")]
    public SignalRConnectionInfo Negotiate([HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req)
    {
        return Negotiate(req.Headers["x-ms-signalr-user-id"], GetClaims(req.Headers["Authorization"]));
    }

    [FunctionName(nameof(OnConnected))]
    public async Task OnConnected([SignalRTrigger]InvocationContext invocationContext, ILogger logger)
    {
        await Clients.All.SendAsync(NewConnectionTarget, new NewConnection(invocationContext.ConnectionId));
        logger.LogInformation($"{invocationContext.ConnectionId} has connected");
    }

    [FunctionName(nameof(Broadcast))]
    public async Task Broadcast([SignalRTrigger]InvocationContext invocationContext, string message, ILogger logger)
    {
        await Clients.All.SendAsync(NewMessageTarget, new NewMessage(invocationContext, message));
        logger.LogInformation($"{invocationContext.ConnectionId} broadcast {message}");
    }

    [FunctionName(nameof(OnDisconnected))]
    public void OnDisconnected([SignalRTrigger]InvocationContext invocationContext)
    {
    }
}

SignalRConnectionInfo Negotiate(string userId = null, IList<Claim> claims = null, TimeSpan? lifeTime = null)

[AttributeUsage(AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
internal class FunctionAuthorizeAttribute: SignalRFilterAttribute
{
    private const string AdminKey = "admin";

    public override Task FilterAsync(InvocationContext invocationContext, CancellationToken cancellationToken)
    {
        if (invocationContext.Claims.TryGetValue(AdminKey, out var value) &&
            bool.TryParse(value, out var isAdmin) &&
            isAdmin)
        {
            return Task.CompletedTask;
        }

        throw new Exception($"{invocationContext.ConnectionId} doesn't have admin role");
    }
}

[FunctionAuthorize]
[FunctionName(nameof(Broadcast))]
public async Task Broadcast([SignalRTrigger]InvocationContext invocationContext, string message, ILogger logger)
{
}

Разработка клиентских приложений

Клиентские приложения SignalR могут использовать клиентский пакет SDK SignalR на одном из нескольких языков, чтобы легко подключаться к Служба Azure SignalR и получать сообщения.

Конфигурация подключения клиента

Чтобы подключиться к службе SignalR, клиент должен завершить успешное согласование подключения, которое состоит из следующих действий.

1. Выполните запрос к конечной точке negotiate HTTP, описанной выше, чтобы получить допустимые сведения о подключении
2. Подключение к службе SignalR с помощью URL-адреса конечной точки службы и маркера доступа, полученного из negotiate конечной точки.

Клиентские пакеты SDK SignalR уже включают логику, необходимую для выполнения рукопожатия с согласованием. Передайте URL-адрес конечной точки переговоров без сегмента negotiate в компонент SDK HubConnectionBuilder. Ниже приведен пример в JavaScript:

const connection = new signalR.HubConnectionBuilder()
  .withUrl("https://my-signalr-function-app.azurewebsites.net/api")
  .build();

Обычно пакет SDK автоматически присоединяет /negotiate к URL-адресу и использует его для начала согласования.

Дополнительные сведения об использовании клиентского пакета SDK SignalR см. в документации по языку:

• .NET Standard
• JavaScript
• Java

Отправка сообщений от клиента к службе

Если вы настроили вышестоящий поток для ресурса SignalR, вы можете отправлять сообщения от клиента в Функции Azure с помощью любого клиента SignalR. Ниже приведен пример в JavaScript:

connection.send("method1", "arg1", "arg2");

Конфигурация Azure Functions

Приложения-функции Azure, интегрированные со Службой Azure SignalR, можно развернуть как любое типичное приложение-функцию Azure с помощью таких методик, как: непрерывное развертывание, развертывание из ZIP-файла и запуск из пакета.

Однако существует несколько особых соображений для приложений, использующих привязки Службы SignalR. Если клиент выполняется в браузере, необходимо включить CORS. Если приложению требуется проверка подлинности, можно интегрировать точку окончания переговоров со службой проверки подлинности App Service.

Включение CORS

Клиент JavaScript/TypeScript отправляет HTTP-запрос в функцию согласования, чтобы инициировать согласование соединения. Если клиентское приложение размещено в другом домене, отличном от приложения-функции Azure, необходимо включить совместное использование ресурсов между источниками (CORS) в приложении-функции или браузер заблокирует запросы.

Localhost

При запуске приложения-функции на локальном компьютере можно добавить раздел Host в local.settings.json, чтобы включить CORS. В разделе Host добавьте два свойства:

• CORS — введите базовый URL-адрес, который является источником клиентского приложения.
• CORSCredentials — установите значение true, чтобы разрешить запросы "withCredentials".

Пример:

{
  "IsEncrypted": false,
  "Values": {
    // values
  },
  "Host": {
    "CORS": "http://localhost:8080",
    "CORSCredentials": true
  }
}

Облако - CORS для функций Azure

Чтобы включить CORS в приложении функции Azure, перейдите на страницу конфигурации CORS на вкладке Возможности платформы на портале Azure.

CORS с помощью access-Control-Allow-Credentials необходимо включить, чтобы клиент SignalR вызывал функцию согласования. Чтобы включить его, установите флажок.

В разделе Разрешенные источники добавьте запись с базовым URL-адресом источника вашего приложения.

Управление API Azure из облака

Управление API Azure предоставляет шлюз API, который добавляет возможности к существующим серверным службам. С ее помощью можно добавить CORS к вашему приложению-функции. Служба поставляется на уровне потребления с оплатой за действия и бесплатным ежемесячным лимитом.

Сведения о том, как импортировать приложение-функцию Azure, см. в документации по Управлению API. После импорта можно добавить политику входящего трафика, чтобы включить CORS с поддержкой Access-Control-Allow-Credentials.

<cors allow-credentials="true">
  <allowed-origins>
    <origin>https://azure-samples.github.io</origin>
  </allowed-origins>
  <allowed-methods>
    <method>GET</method>
    <method>POST</method>
  </allowed-methods>
  <allowed-headers>
    <header>*</header>
  </allowed-headers>
  <expose-headers>
    <header>*</header>
  </expose-headers>
</cors>

Настройте клиенты SignalR для использования URL-адреса службы Управления API.

Использование проверки подлинности в службе приложений

Azure Functions имеет встроенную аутентификацию, поддерживая популярных поставщиков, таких как Facebook, X, Аккаунт Microsoft, Google и Microsoft Entra ID. Эту функцию можно интегрировать с SignalRConnectionInfo связыванием для создания подключений к службе Azure SignalR, прошедших проверку подлинности по идентификатору пользователя. Приложение может отправлять сообщения, используя выходную привязку SignalR, которая нацелена на этот идентификатор пользователя.

На портале Azure на вкладке Возможности приложения-функции откройте окно параметров Проверка подлинности и авторизация. Чтобы настроить аутентификацию с помощью выбранного поставщика удостоверений, следуйте документации по аутентификации Службы приложений.

После настройки прошедшие проверку подлинности HTTP-запросы включают x-ms-client-principal-name и x-ms-client-principal-id заголовки, содержащие имя пользователя и идентификатор пользователя, прошедшие проверку подлинности, соответственно.

Эти заголовки можно использовать в SignalRConnectionInfo конфигурации привязки для создания прошедших проверку подлинности подключений. Ниже приведен пример функции согласования C#, которая использует x-ms-client-principal-id заголовок.

[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;
}

Затем можно отправлять сообщения этому пользователю, задав свойство UserId сообщения SignalR.

[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 these user IDs
            UserId = "userId1",
            Target = "newMessage",
            Arguments = new [] { message }
        });
}

Для получения информации о других языках обратитесь к справочнику по привязкам службы Azure SignalR для Azure Functions.

Следующие шаги

В этой статье вы узнаете, как разрабатывать и настраивать бессерверные приложения Служба SignalR с помощью Функции Azure. Попробуйте создать приложение самостоятельно с помощью одного из быстрых запусков или руководств на странице обзора Службы SignalR.