Udostępnij za pośrednictwem


Samouczek: publikowanie i subskrybowanie komunikatów przy użyciu interfejsu API protokołu WebSocket i zestawu SDK usługi Azure Web PubSub

Usługa Azure Web PubSub ułatwia tworzenie aplikacji do obsługi komunikatów internetowych w czasie rzeczywistym. Z tego samouczka dowiesz się, jak subskrybować usługę przy użyciu interfejsu API protokołu WebSocket i publikować komunikaty przy użyciu zestawu SDK usługi Web PubSub.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

  • Tworzenie wystąpienia usługi Web PubSub
  • Generowanie pełnego adresu URL w celu ustanowienia połączenia protokołu WebSocket
  • Tworzenie klienta subskrybenta Web PubSub w celu odbierania komunikatów przy użyciu standardowego protokołu WebSocket
  • Tworzenie klienta wydawcy Web PubSub w celu publikowania komunikatów przy użyciu zestawu SDK usługi Web PubSub

Wymagania wstępne

  • Subskrypcja platformy Azure umożliwia utworzenie bezpłatnego konta.
  • Powłoka poleceń powłoki Bash. Użyj lokalnej powłoki lub środowiska powłoki Bash w usłudze Azure Cloud Shell.
  • W przypadku uruchomienia na komputerze lokalnym zainstaluj interfejs wiersza polecenia platformy Azure.

Aby uruchomić polecenia w tym samouczku, możesz użyć powłoki poleceń systemu Windows cmd.exe zamiast powłoki Bash.

Jeśli tworzysz projekt na komputerze lokalnym, musisz zainstalować zależności dla używanego języka:

Przygotowywanie środowiska

Konfiguracja interfejsu wiersza polecenia platformy Azure na potrzeby programowania lokalnego

Wykonaj następujące kroki, aby skonfigurować interfejs wiersza polecenia platformy Azure i środowisko projektu.

  1. Otwórz powłokę poleceń.

  2. Uaktualnij do najnowszej wersji interfejsu wiersza polecenia platformy Azure.

    az upgrade
    
  3. Zainstaluj rozszerzenie interfejsu wiersza polecenia platformy Azure dla usługi Web PubSub.

    az extension add --name webpubsub
    
  4. Zaloguj się do interfejsu wiersza polecenia platformy Azure. Po wyświetleniu monitów wprowadź poświadczenia platformy Azure.

    az login
    

Tworzenie grupy zasobów

Grupa zasobów to logiczny kontener przeznaczony do wdrażania zasobów platformy Azure i zarządzania nimi. Użyj polecenia az group create, aby utworzyć grupę zasobów o nazwie myResourceGroup w eastus lokalizacji.

az group create --name myResourceGroup --location EastUS

1. Tworzenie wystąpienia usługi Azure Web PubSub

Tworzenie wystąpienia usługi Web PubSub

Aby utworzyć wystąpienie Web PubSub w utworzonej grupie zasobów, użyj polecenia az webpubsub create interfejsu wiersza polecenia platformy Azure. Następujące polecenie tworzy zasób Free Web PubSub w grupie myResourceGroup zasobów w programie EastUS:

Każdy zasób Web PubSub musi mieć unikatową nazwę. Zastąp <ciąg your-unique-resource-name> nazwą wystąpienia web PubSub w poniższym poleceniu.

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

Dane wyjściowe tego polecenia pokazują właściwości nowo utworzonego zasobu. Zanotuj następujące właściwości:

  • name: nazwa Web PubSub podana w powyższym parametrze --name .
  • hostName: w przykładzie nazwa hosta to <your-unique-resource-name>.webpubsub.azure.com/.

W tym momencie Twoje konto platformy Azure jest jedynym autoryzowanym do wykonywania jakichkolwiek operacji na tym nowym zasobie.

Pobieranie parametrów połączenia

Ważne

Parametry połączenia zawiera informacje o autoryzacji wymagane przez aplikację w celu uzyskania dostępu do usługi Azure Web PubSub. Klucz dostępu wewnątrz parametry połączenia jest podobny do hasła głównego usługi. W środowiskach produkcyjnych należy zawsze zachować ostrożność w celu ochrony kluczy dostępu. Usługa Azure Key Vault umożliwia bezpieczne zarządzanie kluczami i obracanie ich. Unikaj dystrybuowania kluczy dostępu do innych użytkowników, kodowania ich lub zapisywania ich w dowolnym miejscu w postaci zwykłego tekstu, który jest dostępny dla innych użytkowników. Obracanie kluczy, jeśli uważasz, że mogły one zostać naruszone.

Użyj polecenia az webpubsub key interfejsu wiersza polecenia platformy Azure, aby pobrać ciąg ConnectionString usługi. Zastąp <your-unique-resource-name> symbol zastępczy nazwą wystąpienia usługi Azure Web PubSub.

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

Skopiuj parametry połączenia do późniejszego użycia.

Tworzenie klienta subskrybenta

Klienci łączą się z usługą Azure Web PubSub za pośrednictwem standardowego protokołu WebSocket przy użyciu uwierzytelniania tokenu internetowego JSON (JWT). Zestaw SDK usługi udostępnia metody pomocnicze do generowania tokenu. W tym samouczku subskrybent generuje bezpośrednio token z parametru ConnectionString. W rzeczywistych aplikacjach aplikacja po stronie serwera zwykle obsługuje przepływ pracy uwierzytelniania/autoryzacji. Aby lepiej zrozumieć przepływ pracy, zobacz samouczek Tworzenie aplikacji do czatu.

  1. Najpierw utwórz katalog projektu o nazwie subscriber dla tego projektu i zainstaluj wymagane zależności:

    • Pakiet Websocket.Client to pakiet innej firmy obsługujący połączenia protokołu WebSocket. Możesz użyć dowolnego interfejsu API/biblioteki obsługującej protokół WebSocket.
    • Pakiet Azure.Messaging.WebPubSub SDK pomaga wygenerować token JWT.
    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. Zastąp kod w pliku Program.cs następującym kodem, który łączy się z usługą:

    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();
                }
            }
        }
    }
    
    

    Kod tworzy połączenie protokołu WebSocket, które jest połączone z koncentratorem w usłudze Web PubSub. Koncentrator to jednostka logiczna w usłudze Web PubSub, w której można publikować komunikaty w grupie klientów. Kluczowe pojęcia zawierają szczegółowe wyjaśnienie terminów używanych w usłudze Web PubSub.

    Usługa Web PubSub używa uwierzytelniania JSON Web Token (JWT). Przykładowy kod używa WebPubSubServiceClient.GetClientAccessUri() zestawu WEB PubSub SDK do wygenerowania adresu URL usługi zawierającej pełny adres URL z prawidłowym tokenem dostępu.

    Po nawiązaniu połączenia klient odbiera komunikaty za pośrednictwem połączenia protokołu WebSocket. Klient używa client.MessageReceived.Subscribe(msg => ...)); do nasłuchiwania komunikatów przychodzących.

  3. Aby uruchomić subskrybenta, uruchom następujące polecenie zastępując <Web-PubSub-connection-string> parametry połączenia skopiowane wcześniej:

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

2. Publikowanie komunikatów przy użyciu zestawu SDK usługi

Utwórz wydawcę przy użyciu zestawu AZURE Web PubSub SDK, aby opublikować komunikat na połączonym kliencie. W tym projekcie należy otworzyć kolejną powłokę poleceń.

  1. Najpierw utwórz katalog projektu o nazwie publisher i zainstaluj wymagane zależności:

    mkdir publisher
    cd publisher
    dotnet new console
    dotnet add package Azure.Messaging.WebPubSub
    
  2. Zaktualizuj plik, Program.cs WebPubSubServiceClient aby używał klasy i wysyłał komunikaty do klientów.

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

    Wywołanie SendToAllAsync() po prostu wysyła komunikat do wszystkich połączonych klientów w centrum.

  3. Wyślij komunikat, uruchamiając następujące polecenie. Zastąp <Web-PubSub-connection-string> wartość skopiowaną wcześniej parametry połączenia.

    dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"
    
  4. Sprawdź, czy powłoka poleceń subskrybenta odbiera komunikat:

    Message received: Hello World
    

Czyszczenie

Zasoby utworzone w tym przewodniku Szybki start można usunąć, usuwając grupę zasobów, która je zawiera.

az group delete --name myResourceGroup --yes

Jeśli nie planujesz kontynuować korzystania z usługi Azure Cloud Shell, możesz uniknąć gromadzenia kosztów, usuwając grupę zasobów zawierającą skojarzone konto magazynu. Grupa zasobów ma nazwę cloud-shell-storage-<your-region>. Uruchom następujące polecenie, zastępując <CloudShellResourceGroup> ciąg nazwą grupy usługi Cloud Shell.

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

Uwaga

Usunięcie grup zasobów spowoduje usunięcie wszystkich zasobów, w tym zasobów utworzonych poza zakresem tego samouczka.

Następne kroki

Ten samouczek zawiera podstawowe informacje na temat nawiązywania połączenia z usługą Web PubSub i publikowania komunikatów na połączonych klientach.

Zapoznaj się z innymi samouczkami, aby dowiedzieć się więcej na temat korzystania z usługi.