Udostępnij przez


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.

W tym poradniku nauczysz się, jak:

  • 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

Prerequisites

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

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

Important

Nieprzetworzone parametry połączenia są wyświetlane tylko w tym artykule w celach demonstracyjnych.

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 ciągu połączenia jest podobny do hasła głównego dla Twojej usługi. W środowiskach produkcyjnych zawsze chroń klucze dostępu. Użyj usługi Azure Key Vault, aby bezpiecznie zarządzać kluczami i obracać je oraz zabezpieczać połączenie za pomocą usługi WebPubSubServiceClient.

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. Obróć klucze, jeśli uważasz, że zostały naruszone.

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 wiersz poleceń.

  2. Zaktualizuj do najnowszej wersji Azure CLI.

    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. Utwórz wystąpienie 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 w Azure CLI. Następujące polecenie tworzy zasób Free Web PubSub w grupie zasobów myResourceGroup w lokalizacji 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

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.

Nieprzetworzone parametry połączenia są wyświetlane tylko w tym artykule w celach demonstracyjnych. W środowiskach produkcyjnych zawsze chroń klucze dostępu. Użyj usługi Azure Key Vault, aby bezpiecznie zarządzać kluczami i obracać je oraz zabezpieczać połączenie za pomocą usługi WebPubSubServiceClient.

  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 SDK Azure.Messaging.WebPubSub pomaga wygenerować 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 usługi Web PubSub, w której można publikować komunikaty do grupy 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() w Web PubSub SDK do wygenerowania adresu URL do usługi, który zawiera 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> ciągi połączenia skopiowanymi 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. Aby zrealizować ten projekt, musisz otworzyć nową konsolę.

  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, aby używał klasy WebPubSubServiceClient 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 wartość <Web-PubSub-connection-string> parametrami połączenia skopiowanymi wcześniej.

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

    Message received: Hello World
    

Cleanup

Zasoby utworzone w tym szybkim starcie 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> nazwą grupy Cloud Shell.

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

Caution

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

Dalsze 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.