Sviluppo e configurazione di Funzioni di Azure e con il Servizio Azure SignalR

Le applicazioni di Funzioni di Azure possono usare le associazioni del Servizio Azure SignalR per aggiungere funzionalità in tempo reale. Le applicazioni client usano gli SDK client disponibili in diverse lingue per connettersi al Servizio Azure SignalR e ricevere messaggi in tempo reale.

Questo articolo descrive i concetti per lo sviluppo e la configurazione di un'app per le funzioni di Azure integrata con il servizio SignalR.

Configurazione del servizio SignalR

Il Servizio Azure SignalR può essere configurato in modalità diverse. Se usato con Funzioni di Azure, il servizio deve essere configurato in modalità serverless.

Nel portale di Azure individuare la pagina Impostazioni della risorsa del servizio SignalR. Impostare Modalità servizio su Serverless.

Sviluppo di Funzioni di Azure

Un'applicazione serverless in tempo reale compilata con Funzioni di Azure e con il servizio Azure SignalR richiede almeno due istanze di Funzioni di Azure:

• Una funzione negotiate che il client chiama per ottenere un token di accesso valido del servizio SignalR e un URL dell'endpoint.
• Una o più funzioni che gestiscono i messaggi inviati dal servizio SignalR ai client.

Funzione di negoziazione

Un'applicazione client richiede un token di accesso valido per connettersi al Servizio Azure SignalR. Un token di accesso può essere anonimo o autenticato in un ID utente. Le applicazioni del servizio SignalR serverless richiedono un endpoint HTTP denominato negotiate per ottenere un token e altre informazioni di connessione, ad esempio l'URL dell'endpoint del servizio SignalR.

Usare una funzione di Azure attivata da HTTP e l'associazione di input SignalRConnectionInfo per generare l'oggetto con le informazioni di connessione. La funzione deve avere un percorso HTTP che termina in /negotiate.

Con il modello basato su classi in C# non è necessaria l'associazione di input SignalRConnectionInfo ed è possibile aggiungere attestazioni personalizzate molto più facilmente. Per altre informazioni, vedere Esperienza di negoziazione nel modello basato su classi.

Per altre informazioni sulla funzione negotiate, vedere Sviluppo di Funzioni di Azure.

Per informazioni su come creare un token autenticato, vedere Uso dell'autenticazione di Servizio app.

Gestire i messaggi inviati dal servizio SignalR

Usare l'associazione SignalRTrigger per gestire i messaggi inviati dal servizio SignalR. È possibile ricevere una notifica quando i client inviano messaggi o i client vengono connessi o disconnessi.

Per altre informazioni, vedere informazioni di riferimento sull'associazione di trigger del servizio SignalR.

È anche necessario configurare l'endpoint della funzione come endpoint upstream in modo che il servizio attivi la funzione quando viene visualizzato un messaggio da un client. Per altre informazioni su come configurare gli endpoint upstream, vedere Endpoint upstream.

Invio di messaggi e gestione dell'appartenenza ai gruppi

Usare l'associazione di output SignalR per inviare messaggi ai client connessi al Servizio Azure SignalR. È possibile trasmettere messaggi a tutti i client oppure inviarli a un subset di client. Ad esempio, inviare messaggi solo ai client autenticati con un ID utente specifico o solo a un gruppo specifico.

Gli utenti possono essere aggiunti a uno o più gruppi. È anche possibile usare l'associazione di output SignalR per aggiungere o rimuovere utenti da/verso i gruppi.

Per altre informazioni, vedere il SignalR riferimento all'associazione di output.

Hub SignalR

SignalR ha un concetto di hub. Ogni connessione client e ogni messaggio inviato da Funzioni di Azure ha come ambito un hub specifico. È possibile usare hub come modo per separare le connessioni e i messaggi in spazi dei nomi logici.

Modello basato su classi

Il modello basato su classi è dedicato per 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)
{
}

Sviluppo client

Le applicazioni client SignalR possono usare l'SDK client SignalR in uno dei diversi linguaggi per connettersi e ricevere facilmente messaggi dal Servizio Azure SignalR.

Configurazione di una connessione client

Per connettersi al servizio SignalR, un client deve completare una negoziazione di connessione riuscita costituita da questi passaggi:

1. Effettuare una richiesta all'endpoint HTTP negotiate descritto in precedenza per ottenere informazioni di connessione valide
2. Connettersi al servizio SignalR usando l'URL dell'endpoint di servizio e il token di accesso ottenuti dall'endpoint negotiate

Gli SDK del client SignalR contengono già la logica necessaria per eseguire l'handshake di negoziazione. Passare l'URL dell'endpoint di negoziazione, meno il segmento negotiate a HubConnectionBuilder dell'SDK. Ecco un esempio in JavaScript:

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

Per convenzione, l'SDK aggiunge automaticamente /negotiate all'URL e lo usa per avviare la negoziazione.

Per altre informazioni su come usare l'SDK client SignalR, vedere la documentazione relativa al linguaggio:

• .NET Standard
• JavaScript
• Java

Invio di messaggi da un client al servizio

Se è stato configurato upstream per la risorsa SignalR, è possibile inviare messaggi da un client a Funzioni di Azure usando qualsiasi client SignalR. Ecco un esempio in JavaScript:

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

Configurazione di Funzioni di Azure

Le app per le funzioni di Azure che si integrano con il Servizio Azure SignalR possono essere distribuite come qualsiasi tipica app per le funzioni di Azure usando tecniche come la distribuzione continua, la distribuzione zip e l'esecuzione dal pacchetto.

Esistono tuttavia alcune considerazioni speciali per le app che usano le associazioni del servizio SignalR. Se il client viene eseguito in un browser, è necessario abilitare CORS. Se l'app richiede l'autenticazione, è possibile integrare l'endpoint di negoziazione con l'autenticazione del servizio app.

Abilitazione della condivisione CORS

Il client JavaScript/TypeScript effettua una richiesta HTTP alla funzione di negoziazione per avviare la negoziazione della connessione. Quando l'applicazione client è ospitata in un dominio diverso rispetto all'app per le funzioni di Azure, è necessario abilitare la condivisione di risorse tra le origini (CORS) nell'app per le funzioni oppure il browser bloccherà le richieste.

Localhost

Quando si esegue l'app per le funzioni nel computer locale, è possibile aggiungere una sezione Host a local.settings.json per abilitare CORS. Nella sezione Host aggiungere due proprietà:

• CORS: immettere l'URL di base che rappresenta l'origine dell'applicazione client
• CORSCredentials: impostarlo su true per consentire le richieste "withCredentials"

Esempio:

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

Cloud - CORS di Funzioni di Azure

Per abilitare CORS in un'app per le funzioni di Azure, passare alla schermata di configurazione CORS nella scheda Funzionalità della piattaforma dell'app per le funzioni nel portale di Azure.

CORS con Access-Control-Allow-Credentials deve essere abilitato per consentire al client SignalR di chiamare la funzione di negoziazione. Per abilitarla, selezionare la casella di controllo.

Nella sezione Origini consentite aggiungere una voce con l'URL di base di origine dell'applicazione Web.

Cloud - Gestione API di Azure

Gestione API di Azure offre un gateway API che aggiunge funzionalità ai servizi back-end esistenti. È possibile usarlo per aggiungere CORS all'app per le funzioni. Offre un piano a consumo con prezzi con pagamento in base all'azione e una concessione gratuita mensile.

Per informazioni su come importare un'app per le funzioni di Azure, vedere la documentazione di Gestione API. Dopo l'importazione, è possibile aggiungere un criterio in ingresso per abilitare CORS con il supporto di 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>

Configurare i client SignalR per l'uso dell'URL di Gestione API.

Utilizzo di Autenticazione servizio app

Funzioni di Azure include l'autenticazione predefinita, supportando provider diffusi come Facebook, X, Account Microsoft, Google e Microsoft Entra ID. Questa funzionalità può essere integrata con l'associazione SignalRConnectionInfo per creare connessioni al Servizio Azure SignalR autenticato in un ID utente. L'applicazione può inviare messaggi usando l'associazione di output SignalR destinata a tale ID utente.

Nella scheda Funzionalità della piattaforma dell'app per le funzioni del portale di Azure aprire la finestra delle impostazioni di Autenticazione/autorizzazione. Seguire la documentazione relativa all'autenticazione del servizio app per configurare l'autenticazione usando un provider di identità di propria scelta.

Dopo la configurazione, le richieste HTTP autenticate includono le intestazioni x-ms-client-principal-name e x-ms-client-principal-id contenenti rispettivamente il nome utente e l'ID utente dell'identità autenticata.

È possibile usare queste intestazioni nella configurazione dell'associazione SignalRConnectionInfo per creare connessioni autenticate. Ecco un esempio di funzione di negoziazione C# che usa l'intestazione 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;
}

È quindi possibile inviare messaggi all'utente impostando la proprietà UserId di un messaggio 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 }
        });
}

Per informazioni su altri linguaggi, vedere Associazioni del Servizio Azure SignalR come riferimento per le Funzioni di Azure.

Passaggi successivi

Questo articolo illustra come sviluppare e configurare applicazioni del servizio SignalR serverless usando Funzioni di Azure. Provare a creare manualmente un'applicazione usando una delle guide introduttive o le esercitazioni nella pagina di panoramica del servizio SignalR.