Esercitazione: Autenticazione del servizio Azure SignalR con Funzioni di Azure

In questa esercitazione dettagliata si creerà una chat room con autenticazione e messaggistica privata usando queste tecnologie:

• Funzioni di Azure: API back-end per autenticare gli utenti e inviare messaggi di chat.
• Servizio Azure SignalR: servizio per la trasmissione di nuovi messaggi ai client di chat connessi.
• Archiviazione di Azure: servizio Archiviazione necessario Funzioni di Azure.
• app Azure Servizio: servizio che fornisce l'autenticazione utente.

Modello v4

Nota

È possibile ottenere il codice menzionato in questo articolo da GitHub.

Modello v3

Nota

È possibile ottenere il codice menzionato in questo articolo da GitHub.

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Se non hai un account, puoi crearlo gratuitamente.
• Node.js (versione 20.x).
• Funzioni di Azure Core Tools (versione 4).

Problemi? Segnalarli.

Creare risorse essenziali in Azure

Creare una risorsa Servizio Azure SignalR

L'applicazione accederà a un'istanza di Servizio Azure SignalR. Usare la procedura seguente per creare un'istanza di Servizio Azure SignalR usando il portale di Azure:

1. Nella portale di Azure selezionare il pulsante Crea una risorsa (+).

2. Cercare il servizio SignalR e selezionarlo.

3. Seleziona Crea.

4. Immetti le informazioni seguenti.

   Nome	Valore
   Gruppo di risorse	Creare un nuovo gruppo di risorse con un nome univoco.
   Nome risorsa	Immettere un nome univoco per l'istanza di Servizio Azure SignalR.
   Area	Selezionare un'area nelle vicinanze.
   Piano tariffario	Selezionare Gratuito.
   Modalità di servizio	Selezionare Serverless.

5. Selezionare Rivedi e crea.

6. Seleziona Crea.

Problemi? Segnalarli.

Creare un'app per le funzioni di Azure e un account di archiviazione di Azure

1. Nella home page del portale di Azure selezionare Crea una risorsa (+).

2. Cercare App per le funzioni e selezionarla.

3. Seleziona Crea.

4. Immetti le informazioni seguenti.

   Nome	Valore
   Gruppo di risorse	Usare lo stesso gruppo di risorse con l'istanza di Servizio Azure SignalR.
   Nome dell'app per le funzioni	Immettere un nome univoco per l'app per le funzioni.
   Stack di runtime	selezionare Node.js.
   Area	Selezionare un'area nelle vicinanze.

5. Per impostazione predefinita, viene creato un nuovo account di archiviazione di Azure nello stesso gruppo di risorse insieme all'app per le funzioni. Se si vuole usare un altro account di archiviazione nell'app per le funzioni, passare alla scheda Hosting per scegliere un account.

6. Selezionare Rivedi e crea e quindi Crea.

Creare un progetto Funzioni di Azure in locale

Inizializzare un'app per le funzioni

1. Da una riga di comando creare una cartella radice per il progetto e passare alla cartella .

2. Eseguire il comando seguente nel terminale per creare un nuovo progetto funzioni JavaScript:

Modello v4

func init --worker-runtime node --language javascript --name my-app --model V4

Modello v3

func init --worker-runtime node --language javascript --name my-app --model V3

Per impostazione predefinita, il progetto generato include un file host.json che contiene i bundle di estensioni che includono l'estensione SignalR. Per altre informazioni sui bundle di estensioni, vedere Registrare Funzioni di Azure estensioni di binding.

Configurare le impostazioni dell'applicazione

Quando si esegue ed esegue il debug del runtime di Funzioni di Azure in locale, l'app per le funzioni legge le impostazioni dell'applicazione da local.settings.json. Aggiornare questo file con le stringa di connessione dell'istanza di Servizio Azure SignalR e l'account di archiviazione creato in precedenza.

Sostituire il contenuto di local.settings.json con il codice seguente:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AzureWebJobsStorage": "<your-storage-account-connection-string>",
    "AzureSignalRConnectionString": "<your-Azure-SignalR-connection-string>"
  }
}

Nel codice precedente:

• Immettere il Servizio Azure SignalR stringa di connessione nell'impostazioneAzureSignalRConnectionString.

  Per ottenere la stringa, passare all'istanza di Servizio Azure SignalR nel portale di Azure. Nella sezione Impostazioni individuare l'impostazione Chiavi. Selezionare il pulsante Copia a destra del stringa di connessione per copiarlo negli Appunti. È possibile usare il stringa di connessione primario o secondario.

• Immettere il stringa di connessione dell'account di archiviazione nell'impostazioneAzureWebJobsStorage.

  Per ottenere la stringa, passare all'account di archiviazione nel portale di Azure. Nella sezione Sicurezza e rete individuare l'impostazione Chiavi di accesso. Selezionare il pulsante Copia a destra del stringa di connessione per copiarlo negli Appunti. È possibile usare il stringa di connessione primario o secondario.

Problemi? Segnalarli.

Creare una funzione per autenticare gli utenti per Servizio Azure SignalR

Quando l'app di chat viene aperta per la prima volta nel browser, richiede credenziali di connessione valide per connettersi al servizio Azure SignalR. Creare una funzione trigger HTTP denominata negotiate nell'app per le funzioni per restituire queste informazioni di connessione.

Nota

Questa funzione deve essere denominata negotiate perché il client SignalR richiede un endpoint che termina con /negotiate.

Modello v4

1. Dalla cartella del progetto radice creare la negotiate funzione da un modello predefinito usando il comando seguente:

   func new --template "HTTP trigger" --name negotiate
   

2. Aprire src/functions/negotiate.js, aggiornare il contenuto nel modo seguente:

   const { app, input } = require('@azure/functions');
   
   const inputSignalR = input.generic({
       type: 'signalRConnectionInfo',
       name: 'connectionInfo',
       hubName: 'default',
       connectionStringSetting: 'AzureSignalRConnectionString',
   });
   
   app.post('negotiate', {
       authLevel: 'anonymous',
       handler: (request, context) => {
           return { body: JSON.stringify(context.extraInputs.get(inputSignalR)) }
       },
       route: 'negotiate',
       extraInputs: [inputSignalR],
   });
   

   La funzione contiene un'associazione di trigger HTTP per ricevere richieste dai client SignalR. La funzione contiene anche un'associazione di input SignalR per generare credenziali valide per la connessione di un client a un hub Servizio Azure SignalR denominato default.

   Questa funzione accetta le informazioni di connessione SignalR dall'associazione di input e la restituisce al client nel corpo della risposta HTTP.

   Non esiste alcuna userId proprietà nell'associazione signalRConnectionInfo per lo sviluppo locale. Verrà aggiunto in un secondo momento per impostare il nome utente di una connessione SignalR quando si distribuisce l'app per le funzioni in Azure.

Modello v3

1. Dalla cartella del progetto radice creare la negotiate funzione da un modello predefinito usando il comando seguente:

   func new --template "SignalR negotiate HTTP trigger" --name negotiate
   

2. Aprire negotiate/function.json per visualizzare la configurazione dell'associazione di funzioni.

   La funzione contiene un'associazione di trigger HTTP per ricevere richieste dai client SignalR. La funzione contiene anche un'associazione di input SignalR per generare credenziali valide per la connessione di un client a un hub Servizio Azure SignalR denominato default.

   {
     "disabled": false,
     "bindings": [
       {
         "authLevel": "anonymous",
         "type": "httpTrigger",
         "direction": "in",
         "methods": ["post"],
         "name": "req",
         "route": "negotiate"
       },
       {
         "type": "http",
         "direction": "out",
         "name": "res"
       },
       {
         "type": "signalRConnectionInfo",
         "name": "connectionInfo",
         "hubName": "default",
         "connectionStringSetting": "AzureSignalRConnectionString",
         "direction": "in"
       }
     ]
   }
   

   Non esiste alcuna userId proprietà nell'associazione signalRConnectionInfo per lo sviluppo locale. Verrà aggiunto in un secondo momento per impostare il nome utente di una connessione SignalR quando si distribuisce l'app per le funzioni in Azure.

3. Chiudere il file negotiate/function.json .

4. Aprire negotiate/index.js per visualizzare il corpo della funzione:

   module.exports = async function (context, req, connectionInfo) {
     context.res.body = connectionInfo;
   };
   

   Questa funzione accetta le informazioni di connessione a SignalR dall'associazione di input e le restituisce al client nel corpo della risposta HTTP. Il client SignalR usa queste informazioni per connettersi all'istanza di Servizio Azure SignalR.

Problemi? Segnalarli.

Creare una funzione per inviare messaggi di chat

L'app Web richiede anche un'API HTTP per inviare i messaggi di chat. Creare una funzione trigger HTTP che invia messaggi a tutti i client connessi che usano Servizio Azure SignalR:

Modello v4

1. Dalla cartella del progetto radice creare una funzione trigger HTTP denominata sendMessage dal modello usando il comando seguente:

   func new --name sendMessage --template "Http trigger"
   

2. Aprire il file src/functions/sendMessage.js , aggiornare il contenuto come indicato di seguito:

   const { app, output } = require('@azure/functions');
   
   const signalR = output.generic({
       type: 'signalR',
       name: 'signalR',
       hubName: 'default',
       connectionStringSetting: 'AzureSignalRConnectionString',
   });
   
   app.http('messages', {
       methods: ['POST'],
       authLevel: 'anonymous',
       extraOutputs: [signalR],
       handler: async (request, context) => {
           const message = await request.json();
           message.sender = request.headers && request.headers.get('x-ms-client-principal-name') || '';
   
           let recipientUserId = '';
           if (message.recipient) {
               recipientUserId = message.recipient;
               message.isPrivate = true;
           }
           context.extraOutputs.set(signalR,
               {
                   'userId': recipientUserId,
                   'target': 'newMessage',
                   'arguments': [message]
               });
       }
   });
   

   La funzione contiene un trigger HTTP e un'associazione di output SignalR. Accetta il corpo dalla richiesta HTTP e lo invia ai client connessi a Servizio Azure SignalR. Richiama una funzione denominata newMessage in ogni client.

   La funzione può leggere l'identità del mittente e può accettare un recipient valore nel corpo del messaggio per consentire di inviare un messaggio privatamente a un singolo utente. Queste funzionalità verranno usate più avanti nell'esercitazione.

3. Salvare il file.

Modello v3

1. Dalla cartella del progetto radice creare una funzione trigger HTTP denominata sendMessage dal modello usando il comando seguente:

   func new --name sendMessage --template "Http trigger"
   

2. Per configurare le associazioni per la funzione, sostituire il contenuto di sendMessage/function.json con il codice seguente:

   {
     "disabled": false,
     "bindings": [
       {
         "authLevel": "anonymous",
         "type": "httpTrigger",
         "direction": "in",
         "name": "req",
         "route": "messages",
         "methods": ["post"]
       },
       {
         "type": "http",
         "direction": "out",
         "name": "res"
       },
       {
         "type": "signalR",
         "name": "$return",
         "hubName": "default",
         "direction": "out"
       }
     ]
   }
   

   Il codice precedente apporta due modifiche al file originale:

   • Modifica la route in messages e limita il trigger HTTP al POST metodo HTTP.
   • Aggiunge un'associazione di output Servizio Azure SignalR che invia un messaggio restituito dalla funzione a tutti i client connessi a un hub Servizio Azure SignalR denominato default.

3. Sostituire il contenuto di sendMessage/index.js con il codice seguente:

   module.exports = async function (context, req) {
     const message = req.body;
     message.sender =
       (req.headers && req.headers["x-ms-client-principal-name"]) || "";
   
     let recipientUserId = "";
     if (message.recipient) {
       recipientUserId = message.recipient;
       message.isPrivate = true;
     }
   
     return {
       userId: recipientUserId,
       target: "newMessage",
       arguments: [message],
     };
   };
   

   Questa funzione accetta il corpo dalla richiesta HTTP e lo invia ai client connessi a Servizio Azure SignalR. Richiama una funzione denominata newMessage in ogni client.

   La funzione può leggere l'identità del mittente e può accettare un recipient valore nel corpo del messaggio per consentire di inviare un messaggio privatamente a un singolo utente. Queste funzionalità verranno usate più avanti nell'esercitazione.

4. Salvare il file.

Problemi? Segnalarli.

Ospitare l'interfaccia utente Web del client di chat

L'interfaccia utente dell'applicazione chat è una semplice applicazione a pagina singola creata con il framework JavaScript vue usando il client JavaScript ASP.NET Core SignalR. Per semplicità, l'app per le funzioni ospita la pagina Web. In un ambiente di produzione è possibile usare App Web statiche per ospitare la pagina Web.

Modello v4

1. Creare un file denominato index.html nella directory radice del progetto di funzione.

2. Copiare e incollare il contenuto di index.html nel file. Salvare il file.

3. Dalla cartella del progetto radice creare una funzione trigger HTTP denominata index dal modello usando questo comando:

   func new --name index --template "Http trigger"
   

4. Modificare il contenuto di src/functions/index.js nel codice seguente:

   const { app } = require('@azure/functions');
   const { readFile } = require('fs/promises');
   
   app.http('index', {
       methods: ['GET'],
       authLevel: 'anonymous',
       handler: async (context) => {
           const content = await readFile('index.html', 'utf8', (err, data) => {
               if (err) {
                   context.err(err)
                   return
               }
           });
   
           return {
               status: 200,
               headers: {
                   'Content-Type': 'text/html'
               },
               body: content,
           };
       }
   });
   

   La funzione legge la pagina Web statica e la restituisce all'utente.

5. Testare l'app in locale. Avviare l'app per le funzioni usando questo comando:

   func start
   

6. Aprire http://localhost:7071/api/index nel Web browser. Verrà visualizzata una pagina Web di chat.

   

7. Immettere un messaggio nella casella di chat.

   Dopo aver selezionato il tasto INVIO, il messaggio viene visualizzato nella pagina Web. Poiché il nome utente del client SignalR non è impostato, si inviano tutti i messaggi in modo anonimo.

Modello v3

1. Creare una cartella denominata content nella directory radice del progetto di funzione.

2. Nella cartella del contenuto creare un file denominato index.html.

3. Copiare e incollare il contenuto di index.html nel file. Salvare il file.

4. Dalla cartella del progetto radice creare una funzione trigger HTTP denominata index dal modello usando questo comando:

   func new --name index --template "Http trigger"
   

5. Modificare il contenuto di index/index.js nel codice seguente:

   const fs = require("fs");
   
   module.exports = async function (context, req) {
     const fileContent = fs.readFileSync("content/index.html", "utf8");
   
     context.res = {
       // status: 200, /* Defaults to 200 */
       body: fileContent,
       headers: {
         "Content-Type": "text/html",
       },
     };
   };
   

   La funzione legge la pagina Web statica e la restituisce all'utente.

6. Aprire index/function.json e modificare il authLevel valore delle associazioni in anonymous. L'intero file sarà ora simile all'esempio seguente:

   {
     "bindings": [
       {
         "authLevel": "anonymous",
         "type": "httpTrigger",
         "direction": "in",
         "name": "req",
         "methods": ["get", "post"]
       },
       {
         "type": "http",
         "direction": "out",
         "name": "res"
       }
     ]
   }
   

7. Testare l'app in locale. Avviare l'app per le funzioni usando questo comando:

   func start
   

8. Aprire http://localhost:7071/api/index nel Web browser. Verrà visualizzata una pagina Web di chat.

   

9. Immettere un messaggio nella casella di chat.

   Dopo aver selezionato il tasto INVIO, il messaggio viene visualizzato nella pagina Web. Poiché il nome utente del client SignalR non è impostato, si inviano tutti i messaggi in modo anonimo.

Problemi? Segnalarli.

Distribuire in Azure e abilitare l'autenticazione

L'app per le funzioni e l'app per le chat sono state eseguite in locale. Ora, distribuirli in Azure e abilitare l'autenticazione e la messaggistica privata.

Configurare l'app per le funzioni per l'autenticazione

Finora, l'app di chat ha funzionato in modo anonimo. In Azure si userà servizio app'autenticazione per autenticare l'utente. L'ID utente o il nome utente dell'utente autenticato viene passato all'associazione SignalRConnectionInfo per generare informazioni di connessione autenticate come utente.

Modello v4

1. Aprire il file src/functions/negotiate.js .

2. Inserire una userId proprietà nell'associazione inputSignalR con il valore {headers.x-ms-client-principal-name}. Questo valore è un'espressione di associazione che imposta il nome utente del client SignalR sul nome dell'utente autenticato. L'associazione dovrebbe ora essere simile all'esempio seguente:

   const inputSignalR = input.generic({
       type: 'signalRConnectionInfo',
       name: 'connectionInfo',
       hubName: 'default',
       connectionStringSetting: 'AzureSignalRConnectionString',
       userId: '{headers.x-ms-client-principal-name}'
   });
   

3. Salvare il file.

Modello v3

1. Aprire negotiate/function.json.

2. Inserire una userId proprietà nell'associazione SignalRConnectionInfo con il valore {headers.x-ms-client-principal-name}. Questo valore è un'espressione di associazione che imposta il nome utente del client SignalR sul nome dell'utente autenticato. L'associazione dovrebbe ora essere simile all'esempio seguente:

   {
     "type": "signalRConnectionInfo",
     "name": "connectionInfo",
     "userId": "{headers.x-ms-client-principal-name}",
     "hubName": "default",
     "direction": "in"
   }
   

3. Salvare il file.

Distribuire l'app per le funzioni in Azure

Distribuire l'app per le funzioni in Azure usando il comando seguente:

func azure functionapp publish <your-function-app-name> --publish-local-settings

L'opzione --publish-local-settings pubblica le impostazioni locali dal file local.settings.json in Azure, quindi non è necessario configurarle di nuovo in Azure.

Abilitare l'autenticazione del servizio app

Funzioni di Azure supporta l'autenticazione con Microsoft Entra ID, Facebook, Twitter, account Microsoft e Google. Per questa esercitazione si userà Microsoft come provider di identità.

1. Nella portale di Azure passare alla pagina delle risorse dell'app per le funzioni.

2. Selezionare Impostazioni> Autenticazione.

3. Selezionare Aggiungi provider di identità.

   

4. Nell'elenco Provider di identità selezionare Microsoft. Selezionare Aggiungi.

   

Le impostazioni completate creano una registrazione dell'app che associa il provider di identità all'app per le funzioni.

Per altre informazioni sui provider di identità supportati, vedere gli articoli seguenti:

• Microsoft Entra ID
• Facebook
• Twitter
• Account Microsoft
• Google

Provare l'applicazione

1. https://<YOUR-FUNCTION-APP-NAME>.azurewebsites.net/api/index aperti.
2. Selezionare Accesso per eseguire l'autenticazione con il provider di autenticazione scelto.
3. Inviare messaggi pubblici immettendoli nella chat principale.
4. Inviare messaggi privati selezionando un nome utente nella cronologia delle chat. Solo il destinatario selezionato riceve questi messaggi.

Complimenti. È stata distribuita un'app di chat serverless in tempo reale.

Problemi? Segnalarli.

Pulire le risorse

Per pulire le risorse create in questa esercitazione, eliminare il gruppo di risorse usando il portale di Azure.

Attenzione

L'eliminazione del gruppo di risorse elimina tutte le risorse contenute. Se il gruppo di risorse contiene risorse esterne all'ambito di questa esercitazione, vengono eliminate anche.

Problemi? Segnalarli.

Passaggi successivi

In questa esercitazione si è appreso come usare Funzioni di Azure con il servizio Azure SignalR. Altre informazioni sulla creazione di applicazioni serverless in tempo reale con associazioni Servizio Azure SignalR per Funzioni di Azure:

App in tempo reale con Servizio Azure SignalR e Funzioni di Azure

Problemi? Segnalarli.