Share via


Tutorial: Veröffentlichen und Abonnieren von Nachrichten mithilfe der WebSocket-API und des Azure Web PubSub-Dienst-SDK

Der Azure Web PubSub-Dienst hilft Ihnen dabei, ganz einfach Echtzeit-Webmessaginganwendungen zu erstellen. In diesem Tutorial erfahren Sie, wie Sie den Dienst über die WebSocket-API abonnieren und Nachrichten mithilfe des SDK für Web PubSub-Dienst veröffentlichen.

In diesem Tutorial lernen Sie, wie die folgenden Aufgaben ausgeführt werden:

  • Erstellen einer Web PubSub-Dienstinstanz
  • Generieren der vollständigen URL zum Herstellen der WebSocket-Verbindung
  • Erstellen eines Web PubSub-Abonnentenclients zum Empfangen von Nachrichten über das WebSocket-Standardprotokoll
  • Erstellen eines Web PubSub-Herausgeberclients zum Veröffentlichen von Nachrichten mithilfe des SDK für den Web PubSub-Dienst

Voraussetzungen

  • Ein Azure-Abonnement. Sie können ein kostenloses Konto erstellen.
  • Eine Bash-Befehlsshell. Verwenden Sie entweder eine lokale Shell oder die Bash-Umgebung in Azure Cloud Shell.
  • Wenn Sie das Projekt auf einem lokalen Computer ausführen, installieren Sie die Azure CLI.

Sie können die Windows-Befehlsshell „cmd.exe“ anstelle einer Bash-Shell verwenden, um die Befehle in diesem Tutorial auszuführen.

Wenn Sie das Projekt auf einem lokalen Computer erstellen, müssen Sie die Abhängigkeiten für die von Ihnen verwendete Sprache installieren:

Vorbereiten der Umgebung

Azure CLI-Einrichtung für die lokale Entwicklung

Führen Sie die folgenden Schritte aus, um die Azure-Befehlszeilenschnittstelle (Azure CLI) und Ihre Projektumgebung einzurichten.

  1. Öffnen Sie eine Befehlsshell.

  2. Führen Sie ein Upgrade auf die neueste Version der Azure CLI durch.

    az upgrade
    
  3. Installieren Sie die Azure CLI-Erweiterung für Web PubSub.

    az extension add --name webpubsub
    
  4. Melden Sie sich bei Azure CLI an. Folgen Sie den Eingabeaufforderungen, und geben Sie Ihre Azure-Anmeldeinformationen ein.

    az login
    

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

1. Erstellen einer Azure Web PubSub-Instanz

Erstellen einer Web PubSub-Instanz

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 EastUS erstellt:

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

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

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

  • name: Der Web PubSub-Name, den Sie im --name-Parameter 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.

Abrufen der Verbindungszeichenfolge

Wichtig

Eine Verbindungszeichenfolge enthält die Autorisierungsinformationen, die Ihre Anwendung für den Zugriff auf den Azure Web PubSub-Dienst benötigt. Der Zugriffsschlüssel in der Verbindungszeichenfolge ähnelt einem Stammkennwort für Ihren Dienst. Achten Sie in Produktionsumgebungen immer gut darauf, Ihre Zugriffsschlüssel zu schützen. Verwenden Sie Azure Key Vault zum sicheren Verwalten und Rotieren Ihrer Schlüssel. 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.

Erstellen eines Abonnentenclients

Clients verbinden sich mit dem Azure Web PubSub-Dienst über das WebSocket-Standardprotokoll unter Verwendung der JSON-Webtoken-Authentifizierung. Das Dienst-SDK stellt Hilfsmethoden zum Generieren des Tokens bereit. In diesem Tutorial generiert der Abonnent das Token direkt aus ConnectionString. In echten Anwendungen wird der Workflow für die Authentifizierung/Autorisierung üblicherweise von einer serverseitigen Anwendung verarbeitet. Informationen zu diesem Workflow finden Sie im Tutorial Erstellen einer Chat-App.

  1. Erstellen Sie zuerst ein Projektverzeichnis namens subscriber für dieses Projekt, und installieren Sie die erforderlichen Abhängigkeiten:

    • Das Paket Websocket.Client ist ein Drittanbieterpaket, das WebSocket-Verbindungen unterstützt. Sie können jede beliebige API/Bibliothek verwenden, die WebSocket unterstützt.
    • Das SDK-Paket Azure.Messaging.WebPubSub hilft beim Generieren des JWT-Tokens.
    mkdir subscriber
    cd subscriber
    dotnet new console
    dotnet add package Websocket.Client --version 4.3.30
    dotnet add package Azure.Messaging.WebPubSub --version 1.0.0
    
  2. Ersetzen Sie den Code in Program.cs durch den folgenden Code, der eine Verbindung mit dem Dienst herstellt:

    using System;
    using System.Threading.Tasks;
    
    using Azure.Messaging.WebPubSub;
    
    using Websocket.Client;
    
    namespace subscriber
    {
        class Program
        {
            static async Task Main(string[] args)
            {
                if (args.Length != 2)
                {
                    Console.WriteLine("Usage: subscriber <connectionString> <hub>");
                    return;
                }
                var connectionString = args[0];
                var hub = args[1];
    
                // Either generate the URL or fetch it from server or fetch a temp one from the portal
                var serviceClient = new WebPubSubServiceClient(connectionString, hub);
                var url = serviceClient.GetClientAccessUri();
    
                using (var client = new WebsocketClient(url))
                {
                    // Disable the auto disconnect and reconnect because the sample would like the client to stay online even no data comes in
                    client.ReconnectTimeout = null;
                    client.MessageReceived.Subscribe(msg => Console.WriteLine($"Message received: {msg}"));
                    await client.Start();
                    Console.WriteLine("Connected.");
                    Console.Read();
                }
            }
        }
    }
    
    

    Der Code erstellt eine WebSocket-Verbindung mit einem Hub in Web PubSub. Ein Hub ist eine logische Einheit in Web PubSub, in der Sie Nachrichten für eine Gruppe von Clients veröffentlichen können. Unter Wichtige Konzepte finden Sie ausführliche Erläuterungen der in Web PubSub verwendeten Begriffe.

    Der Web PubSub-Dienst verwendet die Authentifizierung über ein JSON Web Token (JWT). Der Beispielcode verwendet WebPubSubServiceClient.GetClientAccessUri() im Web PubSub SDK, um eine URL zum Dienst zu generieren, die die vollständige URL mit einem gültigen Zugriffstoken umfasst.

    Nachdem die Verbindung hergestellt wurde, erhält Ihr Client Nachrichten über die WebSocket-Verbindung. Der Client verwendet client.MessageReceived.Subscribe(msg => ...));, um auf eingehende Nachrichten zu lauschen.

  3. Führen Sie zum Starten des Abonnenten den folgenden Befehl aus, und ersetzen Sie <Web-PubSub-connection-string> dabei durch die Verbindungszeichenfolge, die Sie zuvor kopiert haben:

    dotnet run <Web-PubSub-connection-string> "myHub1"
    

2. Veröffentlichen von Nachrichten mithilfe des Dienst-SDK

Erstellen Sie einen Herausgeber mithilfe des Azure Web PubSub SDK, um eine Nachricht für den verbundenen Client zu veröffentlichen. Für dieses Projekt müssen Sie eine weitere Befehlsshell öffnen.

  1. Erstellen Sie zuerst ein Projektverzeichnis namens publisher, und installieren Sie die erforderlichen Abhängigkeiten:

    mkdir publisher
    cd publisher
    dotnet new console
    dotnet add package Azure.Messaging.WebPubSub
    
  2. Aktualisieren Sie die Datei Program.cs, um die Klasse WebPubSubServiceClient zu verwenden und Nachrichten an die Clients zu senden.

    using System;
    using System.Threading.Tasks;
    using Azure.Messaging.WebPubSub;
    
    namespace publisher
    {
        class Program
        {
            static async Task Main(string[] args)
            {
                if (args.Length != 3) {
                    Console.WriteLine("Usage: publisher <connectionString> <hub> <message>");
                    return;
                }
                var connectionString = args[0];
                var hub = args[1];
                var message = args[2];
    
                // Either generate the token or fetch it from server or fetch a temp one from the portal
                var serviceClient = new WebPubSubServiceClient(connectionString, hub);
                await serviceClient.SendToAllAsync(message);
            }
        }
    }
    
    

    Der Aufruf SendToAllAsync() sendet einfach eine Nachricht an alle verbundenen Clients im Hub.

  3. Senden Sie eine Nachricht, indem Sie den folgenden Befehl ausführen. Ersetzen Sie <Web-PubSub-connection-string> durch die Verbindungszeichenfolge, die Sie zuvor kopiert haben.

    dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"
    
  4. Überprüfen Sie in der Befehlsshell des Abonnenten, ob dieser die Nachricht empfangen hat:

    Message received: Hello World
    

Bereinigen

Sie können die Ressourcen löschen, die Sie in dieser Schnellstartanleitung erstellt haben, indem Sie die Ressourcengruppe löschen, die sie enthält.

az group delete --name myResourceGroup --yes

Wenn Sie nicht planen, Azure Cloud Shell weiterhin zu verwenden, können weitere Kosten vermeiden, indem Sie die Ressourcengruppe löschen, die das zugeordnete Speicherkonto enthält. Die Ressourcengruppe heißt cloud-shell-storage-<your-region>. Führen Sie den folgenden Befehl aus, und ersetzen Sie <CloudShellResourceGroup> durch den Cloud Shell-Gruppennamen.

az group delete --name <CloudShellResourceGroup> --yes

Achtung

Durch das Löschen von Ressourcengruppen werden alle Ressourcen gelöscht, einschließlich solcher, die außerhalb dieses Tutorials erstellt wurden.

Nächste Schritte

In diesem Tutorial haben Sie grundlegende Informationen dazu erhalten, wie Sie eine Verbindung mit dem Web PubSub-Dienst herstellen und Nachrichten für die verbundenen Clients veröffentlichen.

Bearbeiten Sie weitere Tutorials, um mehr über die Nutzung des Diensts zu erfahren.