Tutorial: Erstellen einer Chat-App mit dem Azure Web PubSub-Dienst

Im Tutorial Veröffentlichen und Abonnieren von Nachrichten lernen Sie die Grundlagen des Veröffentlichen und Abonnieren von Nachrichten mit Azure Web PubSub. In diesem Tutorial lernen Sie das Ereignissystem von Azure Web PubSub kennen und verwenden es, um eine vollständige Webanwendung mit Echtzeit-Kommunikationsfunktionen zu erstellen.

In diesem Tutorial lernen Sie Folgendes:

  • Erstellen einer Web PubSub-Dienstinstanz
  • Konfigurieren von Ereignishandlereinstellungen für Azure Web PubSub
  • Verarbeite Ereignisse im App-Server und erstelle eine Echtzeit-Chat-App

Wenn Sie nicht über ein Azure-Konto verfügen, erstellen Sie ein kostenloses Konto , bevor Sie beginnen.

Voraussetzungen

  • Für dieses Setup ist mindestens Version 2.22.0 der Azure CLI erforderlich. Bei Verwendung von Azure Cloud Shell ist die aktuelle Version bereits installiert.

Erstellen einer Azure Web PubSub-Instanz

Erstellen einer Ressourcengruppe

Eine Ressourcengruppe ist ein logischer Container, in dem Azure-Ressourcen bereitgestellt und verwaltet werden. Erstellen Sie mithilfe des Befehls az group create eine Ressourcengruppe namens myResourceGroup in der Region eastus.

az group create --name myResourceGroup --location EastUS

Erstellen einer Web PubSub-Instanz

Führen Sie az extension add aus, um die Erweiterung webpubsub zu installieren bzw. auf die aktuelle Version zu aktualisieren.

az extension add --upgrade --name webpubsub

Verwenden Sie den Azure CLI-Befehl az webpubsub create, um eine Web PubSub-Instanz in der erstellten Ressourcengruppe zu erstellen. Mit dem folgenden Befehl wird eine Kostenlose Web-PubSub-Ressource unter der Ressourcengruppe myResourceGroup in USA, Osten erstellt:

Wichtig

Jede Web PubSub-Ressource muss einen eindeutigen Namen haben. Ersetzen Sie <your-unique-resource-name> in den folgenden Beispielen durch den Namen Ihrer Web PubSub.

az webpubsub create --name "<your-unique-resource-name>" --resource-group "myResourceGroup" --location "EastUS" --sku Free_F1

In der Ausgabe dieses Befehls werden die Eigenschaften der neu erstellten Ressource angezeigt. Beachten Sie die beiden folgenden Eigenschaften:

  • Resource Name: Der Name, den Sie oben für den Parameter --name angegeben haben.
  • hostName: Im Beispiel lautet der Hostname <your-unique-resource-name>.webpubsub.azure.com/.

An diesem Punkt ist nur Ihr Azure-Konto zum Ausführen von Vorgängen für die neue Ressource autorisiert.

Rufen Sie die Verbindungszeichenfolge zur späteren Verwendung ab.

Wichtig

Unformatierte Verbindungszeichenfolgen werden in diesem Artikel nur zu Demonstrationszwecken angezeigt.

Eine Verbindungszeichenfolge enthält die Autorisierungsinformationen, die Ihre Anwendung benötigt, um auf den Azure Web PubSub-Dienst zuzugreifen. Der Zugangsschlüssel im Verbindungszeichenfolge fungiert wie ein Root-Passwort für deinen Dienst. Schützen Sie Ihre Zugriffsschlüssel in Produktionsumgebungen immer sorgfältig. Verwenden Sie Azure Key Vault zum sicheren Verwalten und Rotieren Ihrer Schlüssel und zum Schützen Ihrer Verbindung mit WebPubSubServiceClient.

Geben Sie Zugriffsschlüssel nicht an andere Benutzer weiter, vermeiden Sie das Hartcodieren, und speichern Sie die Schlüssel nicht als Klartext, auf den andere Benutzer Zugriff haben. Rotieren Sie die Schlüssel, wenn Sie glauben, dass sie möglicherweise gefährdet sind.

Verwenden Sie den Azure CLI-Befehl az webpubsub key, um die Verbindungszeichenfolge (ConnectionString) des Diensts abzurufen. Ersetzen Sie den Platzhalter <your-unique-resource-name> durch den Namen Ihrer Azure Web PubSub-Instanz.

az webpubsub key show --resource-group myResourceGroup --name <your-unique-resource-name> --query primaryConnectionString --output tsv

Kopieren Sie die Verbindungszeichenfolge zur späteren Verwendung.

Kopieren Sie den abgerufenen ConnectionString und legen Sie ihn in die Umgebungsvariable WebPubSubConnectionString fest, die das Tutorial später liest. Ersetzen Sie <connection-string> unten durch die ConnectionString, die Sie abgerufen haben.

export WebPubSubConnectionString="<connection-string>"

SET WebPubSubConnectionString=<connection-string>

Einrichten des Projekts

Voraussetzungen

Erstellen der Anwendung

In Azure Web PubSub gibt es zwei Rollen: Server und Client. Dieses Konzept ähnelt den Server- und Clientrollen in einer Webanwendung. Der Server ist dafür verantwortlich, die Clients zu verwalten, zuzuhören und auf Clientnachrichten zu reagieren. Der Client ist dafür verantwortlich, die Nachrichten des Benutzers vom Server zu senden und zu empfangen und für den Endbenutzer zu visualisieren.

In diesem Tutorial erstellen wir eine Echtzeit-Chat-Webanwendung. In einer echten Webanwendung umfasst die Verantwortung des Servers auch die Authentifizierung von Clients und die Bereitstellung statischer Webseiten für die Benutzeroberfläche der Anwendung.

Wir verwenden ASP.NET Core 8, um die Webseiten zu hosten und eingehende Anfragen zu bearbeiten.

Erstellen wir zunächst eine ASP.NET Core Web App in einem chatapp-Ordner.

  1. Erstellen Sie eine neue Web-App.

    mkdir chatapp
cd chatapp
dotnet new web

  2. Fügen Sie app.UseStaticFiles() Program.cs hinzu, um das Hosting statischer Webseiten zu unterstützen.

    var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseStaticFiles();

app.Run();

  3. Erstellen Sie eine HTML-Datei und speichern Sie diese unter wwwroot/index.html, wir verwenden sie später für die Benutzeroberfläche der Chat-App.

    <html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
  </body>
</html>

Sie können den Server testen, indem Sie dotnet run --urls http://localhost:8080 ausführen und http://localhost:8080/index.html im Browser aufrufen.

Hinzufügen eines Aushandlungsendpunkts

Im Tutorial Nachricht veröffentlichen und abonnieren verwendet der Abonnent die Verbindungszeichenfolge direkt. In einer realen Anwendung ist es nicht sicher, die Verbindungszeichenfolge für einen beliebigen Client freizugeben, da Verbindungszeichenfolgen über hohe Berechtigungen verfügen, um einen Vorgang für den Dienst auszuführen. Lassen Sie uns nun festlegen, dass Ihr Server die Verbindungszeichenfolge verwendet und einen negotiate-Endpunkt für den Client verfügbar macht, um die vollständige URL mit Zugriffstoken abzurufen. Auf diese Weise kann der Server vor dem negotiate-Endpunkt Authentifizierungs-Middleware hinzufügen, um nicht autorisierten Zugriff zu verhindern.

Installieren Sie zunächst die Abhängigkeiten.

dotnet add package Microsoft.Azure.WebPubSub.AspNetCore

Jetzt fügen wir einen /negotiate-Endpunkt hinzu, den der Client aufrufen kann, um das Token zu generieren.

using Azure.Core;
using Microsoft.Azure.WebPubSub.AspNetCore;
using Microsoft.Azure.WebPubSub.Common;
using Microsoft.Extensions.Primitives;

// Read connection string from environment
var connectionString = Environment.GetEnvironmentVariable("WebPubSubConnectionString");
if (connectionString == null)
{
    throw new ArgumentNullException(nameof(connectionString));
}

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddWebPubSub(o => o.ServiceEndpoint = new WebPubSubServiceEndpoint(connectionString))
    .AddWebPubSubServiceClient<Sample_ChatApp>();
var app = builder.Build();

app.UseStaticFiles();

// return the Client Access URL with negotiate endpoint
app.MapGet("/negotiate", (WebPubSubServiceClient<Sample_ChatApp> service, HttpContext context) =>
{
    var id = context.Request.Query["id"];
    if (StringValues.IsNullOrEmpty(id))
    {
        context.Response.StatusCode = 400;
        return null;
    }
    return new
    {
        url = service.GetClientAccessUri(userId: id).AbsoluteUri
    };
});
app.Run();

sealed class Sample_ChatApp : WebPubSubHub
{
}

AddWebPubSubServiceClient<THub>() wird verwendet, um den Dienstclient WebPubSubServiceClient<THub> einzufügen, mit dem im Aushandlungsschritt eine Clientverbindung generiert und in Hubmethoden verwendet werden kann, um Dienst-REST-APIs aufzurufen, wenn Hubereignisse ausgelöst werden. Dieser Code zum Generieren des Tokens ähnelt dem Code, den wir im Tutorial zum Veröffentlichen und Abonnieren von Nachrichten verwendet haben – abgesehen davon, dass wir beim Generieren des Tokens ein weiteres Argument (userId) übergeben. Mithilfe der Benutzer-ID kann der Client identifiziert werden, damit Sie beim Empfang einer Nachricht wissen, woher die Nachricht stammt.

Der Code liest die Verbindungszeichenfolge aus der Umgebungsvariable WebPubSubConnectionString, die wir im vorherigen Schritt festgelegt haben.

Starten Sie den Server mit dotnet run --urls http://localhost:8080 erneut.

Sie können diese API testen, indem Sie auf http://localhost:8080/negotiate?id=user1 zugreifen. Sie erhalten dann die vollständige URL des Azure Web PubSub mit einem Zugriffstoken.

Ereignisse behandeln

In Azure Web PubSub sendet der Dienst Benachrichtigungen an den Server, wenn auf der Clientseite bestimmte Aktivitäten stattfinden (z. B. wenn ein Client eine Verbindung herstellt, verbunden wird, die Verbindung trennt oder Nachrichten sendet), damit dieser auf diese Ereignisse reagieren kann.

Ereignisse werden in Form eines Webhooks an den Server übermittelt. Der Webhook wird vom Anwendungsserver verarbeitet und verfügbar gemacht und auf der Dienstseite von Azure Web PubSub registriert. Der Dienst ruft die Webhooks immer dann auf, wenn ein Ereignis eintritt.

Azure Web PubSub beschreibt die Ereignisdaten gemäß CloudEvents.

Nachfolgend behandeln wir connected-Systemereignisse, wenn ein Client verbunden ist und Benutzerereignisse verarbeitet message, wenn ein Client Nachrichten sendet, um die Chat-App zu erstellen.

Das Web PubSub SDK für AspNetCore Microsoft.Azure.WebPubSub.AspNetCore, das wir im vorherigen Schritt installiert haben, kann auch dazu beitragen, die CloudEvents-Anforderungen zu analysieren und zu verarbeiten.

Fügen Sie zunächst Ereignishandler vor app.Run() ein. Geben Sie den Endpunktpfad für die Ereignisse an, beispielsweise /eventhandler.

app.MapWebPubSubHub<Sample_ChatApp>("/eventhandler/{*path}");
app.Run();

Fügen Sie nun innerhalb der Klasse Sample_ChatApp, die wir im vorherigen Schritt erstellt haben, einen Konstruktor hinzu, um mit WebPubSubServiceClient<Sample_ChatApp> zu arbeiten, das wir verwenden, um den Web PubSub-Dienst aufzurufen. Und OnConnectedAsync(), um zu reagieren, wenn das connected-Ereignis ausgelöst wird, OnMessageReceivedAsync() um Nachrichten vom Client zu behandeln.

sealed class Sample_ChatApp : WebPubSubHub
{
    private readonly WebPubSubServiceClient<Sample_ChatApp> _serviceClient;

    public Sample_ChatApp(WebPubSubServiceClient<Sample_ChatApp> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override async Task OnConnectedAsync(ConnectedEventRequest request)
    {
        Console.WriteLine($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
    }

    public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
    {
        await _serviceClient.SendToAllAsync(RequestContent.Create(
        new
        {
            from = request.ConnectionContext.UserId,
            message = request.Data.ToString()
        }),
        ContentType.ApplicationJson);

        return new UserEventResponse();
    }
}

In dem obigen Code verwenden wir den Service-Client, um eine Benachrichtigung im JSON-Format an alle zu senden, die sich mit SendToAllAsync verknüpfen.

Aktualisieren Sie die Webseite

Nun aktualisieren wir index.html, um die Logik zum Verbinden, Senden von Nachrichten und Anzeigen empfangener Nachrichten auf der Seite hinzuzufügen.

<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
    <input id="message" placeholder="Type to chat...">
    <div id="messages"></div>
    <script>
      (async function () {
        let id = prompt('Please input your user name');
        let res = await fetch(`/negotiate?id=${id}`);
        let data = await res.json();
        let ws = new WebSocket(data.url);
        ws.onopen = () => console.log('connected');

        let messages = document.querySelector('#messages');
        
        ws.onmessage = event => {
          let m = document.createElement('p');
          let data = JSON.parse(event.data);
          m.innerText = `[${data.type || ''}${data.from || ''}] ${data.message}`;
          messages.appendChild(m);
        };

        let message = document.querySelector('#message');
        message.addEventListener('keypress', e => {
          if (e.charCode !== 13) return;
          ws.send(message.value);
          message.value = '';
        });
      })();
    </script>
  </body>

</html>

Im obigen Code können Sie sehen, dass wir die native WebSocket-API des Browsers verwenden und WebSocket.send() zum Senden von Nachrichten sowie WebSocket.onmessage, um empfangene Nachrichten zu verarbeiten.

Sie können auch Client-SDKs verwenden, um eine Verbindung mit dem Dienst herzustellen, was Ihnen die automatische Wiederherstellung, Fehlerbehandlung und vieles mehr ermöglicht.

Jetzt ist nur noch ein Schritt nötig, damit der Chat funktioniert. Lassen Sie uns konfigurieren, welche Ereignisse für uns relevant sind und wohin wir die Ereignisse im Web PubSub-Dienst senden.

Einrichten des Ereignishandlers

Wir legen den Ereignishandler im Web PubSub-Dienst fest, um dem Dienst mitzuteilen, an welchen Ort die Ereignisse gesendet werden sollen.

Wenn der Webserver lokal ausgeführt wird, wie der Web PubSub-Dienst den Localhost aufruft, wenn er keinen Endpunkt mit Internetzugriff hat? In der Regel gibt es zwei Möglichkeiten. Eine besteht darin, localhost über ein allgemeines Tunneltool für die Öffentlichkeit verfügbar zu machen, und die andere besteht darin , AWP-Tunnel zum Tunneln des Datenverkehrs vom Web PubSub-Dienst über das Tool zu Ihrem lokalen Server zu verwenden.

In diesem Abschnitt verwenden wir Azure CLI, um die Ereignishandler festzulegen und AWP-Tunnel zum Weiterleiten von Datenverkehr an Localhost zu verwenden.

Konfigurieren von Hubeinstellungen

Wir legen die URL-Vorlage so fest, dass das Schema tunnel verwendet wird, sodass Web PubSub die Nachrichten über die Tunnelverbindung von awps-tunnel leitet. Ereignishandler können entweder über das Portal oder über die CLI festgelegt werden, wie in diesem Artikel beschrieben. Hier wird die CLI verwendet. Da wir Ereignisse im Pfad /eventhandler überwachen, wie im vorherigen Schritt festgelegt, setzen wir die URL-Vorlage auf tunnel:///eventhandler.

Verwenden Sie den Azure CLI-Befehl az webpubsub hub create, um die Ereignishandlereinstellungen für den Sample_ChatApp-Hub zu erstellen.

Wichtig

Ersetzen Sie <your-unique-resource-name> durch den Namen Ihrer Web PubSub-Instanz, die in den vorherigen Schritten erstellt wurde.

az webpubsub hub create -n "<your-unique-resource-name>" -g "myResourceGroup" --hub-name "Sample_ChatApp" --event-handler url-template="tunnel:///eventhandler" user-event-pattern="*" system-event="connected"

awps-tunnel lokal ausführen

Herunterladen und Installieren des AWP-Tunnels

Das Tool wird auf Node.js Version 16 oder höher ausgeführt.

npm install -g @azure/web-pubsub-tunnel-tool

Verwenden Sie die Dienstverbindungszeichenfolge und führen Sie Folgendes aus

export WebPubSubConnectionString="<your connection string>"
awps-tunnel run --hub Sample_ChatApp --upstream http://localhost:8080

Ausführen des Webservers

Jetzt ist alles festgelegt. Lassen Sie uns den Webserver ausführen und mit der Chat-App in Aktion spielen.

Starten Sie nun den Server mit dotnet run --urls http://localhost:8080.

Das vollständige Codebeispiel für dieses Tutorial finden Sie hier.

Öffnen Sie http://localhost:8080/index.html. Sie können Ihren Benutzernamen eingeben und mit dem Chatten beginnen.

Lazy Auth mit dem connect-Ereignishandler

In vorherigen Abschnitten wurde veranschaulicht, wie der Aushandlungsendpunkt zum Zurückgeben der Web PubSub-Dienst-URL und des JWT-Zugriffstokens für die Clients zum Herstellen einer Verbindung mit dem Web PubSub-Dienst verwendet wird. In einigen Fällen, z. B. bei Edgegeräten mit eingeschränkten Ressourcen, bevorzugen Clients möglicherweise eine direkte Verbindung mit Web PubSub-Ressourcen. In solchen Fällen können Sie den connect-Ereignishandler konfigurieren, um eine verzögerte Authentifizierung für die Clients auszuführen, den Clients eine Benutzer-ID zuzuweisen, die Gruppen anzugeben, denen Clients nach der Verbindungsherstellung beitreten, die Berechtigungen der Clients zu konfigurieren und das WebSocket-Unterprotokoll als WebSocket-Antwort für den Client zu konfigurieren usw. Details finden Sie in der Spezifikation zum connect-Ereignishandler.

Verwenden Sie nun den connect-Ereignishandler, um ein ähnliches Ergebnis wie mit dem Abschnitt negotiate zu erzielen.

Aktualisieren der Hubeinstellungen

Zunächst aktualisieren Sie Hubeinstellungen, um auch den connect-Ereignishandler einzuschließen. Darüber hinaus müssen Sie anonyme Verbindungen zulassen, damit Clients ohne JWT-Zugriffstoken eine Verbindung mit dem Dienst herstellen können.

Verwenden Sie den Azure CLI-Befehl az webpubsub hub update, um die Ereignishandlereinstellungen für den Sample_ChatApp-Hub zu erstellen.

Wichtig

Ersetzen Sie <your-unique-resource-name> durch den Namen Ihrer Web PubSub-Instanz, die in den vorherigen Schritten erstellt wurde.

az webpubsub hub update -n "<your-unique-resource-name>" -g "myResourceGroup" --hub-name "Sample_ChatApp" --allow-anonymous true --event-handler url-template="tunnel:///eventhandler" user-event-pattern="*" system-event="connected" system-event="connect"

Upstreamlogik aktualisieren, um das Verbindungsereignis zu verarbeiten

Aktualisieren wir nun die Upstream-Logik, um das Connect-Ereignis zu verarbeiten. Wir könnten jetzt auch den Negotiate-Endpunkt entfernen.

Ähnlich wie wir es beim Negotiation-Endpunkt zu Demonstrationszwecken tun, lesen wir auch die id aus den Abfrageparametern. Beim connect-Ereignis wird die ursprüngliche Clientabfrage im Anforderungstext des connect-Ereignisses beibehalten.

Überschreiben Sie in der Klasse Sample_ChatApp das OnConnectAsync()-Element, um das connect-Ereignis zu behandeln:

sealed class Sample_ChatApp : WebPubSubHub
{
    private readonly WebPubSubServiceClient<Sample_ChatApp> _serviceClient;

    public Sample_ChatApp(WebPubSubServiceClient<Sample_ChatApp> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override ValueTask<ConnectEventResponse> OnConnectAsync(ConnectEventRequest request, CancellationToken cancellationToken)
    {
        if (request.Query.TryGetValue("id", out var id))
        {
            return new ValueTask<ConnectEventResponse>(request.CreateResponse(userId: id.FirstOrDefault(), null, null, null));
        }

        // The SDK catches this exception and returns 401 to the caller
        throw new UnauthorizedAccessException("Request missing id");
    }

    public override async Task OnConnectedAsync(ConnectedEventRequest request)
    {
        Console.WriteLine($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
    }

    public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
    {
        await _serviceClient.SendToAllAsync(RequestContent.Create(
        new
        {
            from = request.ConnectionContext.UserId,
            message = request.Data.ToString()
        }),
        ContentType.ApplicationJson);

        return new UserEventResponse();
    }
}

Aktualisieren Sie index.html für eine direkte Verbindung.

Aktualisieren Sie nun die Webseite so, dass eine direkte Verbindung mit dem Web PubSub-Dienst hergestellt wird. Zu erwähnen ist, dass der Web PubSub-Dienstendpunkt zu Demozwecken jetzt im Clientcode hartcodiert ist. Aktualisieren Sie den Diensthostnamen <the host name of your service> im folgenden HTML-Code mit dem Wert aus Ihrem eigenen Dienst. Möglicherweise ist es dennoch hilfreich, den Wert des Web PubSub-Dienstendpunkts von Ihrem Server abzurufen. Dadurch erhalten Sie mehr Flexibilität und Kontrolle darüber, wo der Client eine Verbindung herstellt.

<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
    <input id="message" placeholder="Type to chat...">
    <div id="messages"></div>
    <script>
      (async function () {
        // sample host: mock.webpubsub.azure.com
        let hostname = "<the host name of your service>";
        let id = prompt('Please input your user name');
        let ws = new WebSocket(`wss://${hostname}/client/hubs/Sample_ChatApp?id=${id}`);
        ws.onopen = () => console.log('connected');

        let messages = document.querySelector('#messages');
        
        ws.onmessage = event => {
          let m = document.createElement('p');
          let data = JSON.parse(event.data);
          m.innerText = `[${data.type || ''}${data.from || ''}] ${data.message}`;
          messages.appendChild(m);
        };

        let message = document.querySelector('#message');
        message.addEventListener('keypress', e => {
          if (e.charCode !== 13) return;
          ws.send(message.value);
          message.value = '';
        });
      })();
    </script>
  </body>

</html>

Server erneut starten

Führen Sie jetzt den Server erneut aus, und rufen Sie die Webseite gemäß den vorherigen Anweisungen auf. Wenn Sie awps-tunnel beendet haben, führen Sie auch das Tunneltool erneut aus.

Nächste Schritte

Dieses Tutorial vermittelt Ihnen eine grundlegende Vorstellung davon, wie das Ereignissystem im Azure Web PubSub Service funktioniert.

Sehen Sie sich weitere Tutorials an, um tiefer in die Nutzung des Diensts einzutauchen.

Weitere Beispiele für Azure Web PubSub

  • Last updated on