Samouczek: publikowanie i subskrybowanie komunikatów przy użyciu interfejsu API protokołu WebSocket i zestawu SDK usługi Azure Web PubSub
Artykuł
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.
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.
Otwórz powłokę poleceń.
Uaktualnij do najnowszej wersji interfejsu wiersza polecenia platformy Azure.
az upgrade
Zainstaluj rozszerzenie interfejsu wiersza polecenia platformy Azure dla usługi Web PubSub.
az extension add --name webpubsub
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.
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.
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
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();
}
}
}
}
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.
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"
Najpierw utwórz katalog projektu o nazwie subscriber i zainstaluj wymagane zależności:
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.
Uruchom następujące polecenie, zastępując <Web-PubSub-connection-string> wartość skopiowaną wcześniej parametry połączenia. Jeśli używasz powłoki poleceń systemu Windows, możesz użyć polecenia set zamiast export.
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 będzie odbierał komunikaty za pośrednictwem połączenia protokołu WebSocket. Użyj await ws.recv() polecenia , aby nasłuchiwać przychodzących wiadomości.
Uruchom następujące polecenie, zastępując <Web-PubSub-connection-string> wartość skopiowaną wcześniej parametry połączenia:
Najpierw utwórz katalog projektu o nazwie pubsub na potrzeby tego samouczka.
mkdir pubsub
cd pubsub
pubsub W katalogu użyj narzędzia Maven, aby utworzyć nową aplikację konsolową o nazwie webpubsub-quickstart-subscriber, a następnie przejdź do katalogu webpubsub-quickstart-subscriber:
W usłudze Web PubSub możesz nawiązać połączenie z usługą i subskrybować komunikaty za pośrednictwem połączeń protokołu WebSocket. WebSocket to kanał komunikacji pełnodupleksowej umożliwiający usłudze wypychanie komunikatów do klienta w czasie rzeczywistym. Możesz użyć dowolnego interfejsu API lub biblioteki obsługującej protokół WebSocket. W tym przykładzie używamy pakietu Java-WebSocket.
Przejdź do katalogu /src/main/java/com/webpubsub/quickstart .
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 będzie odbierał komunikaty za pośrednictwem połączenia protokołu WebSocket. Użyj onMessage(String message) polecenia , aby nasłuchiwać przychodzących wiadomości.
Aby uruchomić aplikację subskrybenta, przejdź do katalogu webpubsub-quickstart-subscriber i uruchom następujące polecenie. Zastąp <Web-PubSub-connection-string> wartość skopiowaną wcześniej parametry połączenia.
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ń.
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
Zaktualizuj plik, Program.csWebPubSubServiceClient 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.
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"
Sprawdź, czy powłoka poleceń subskrybenta odbiera komunikat:
Message received: Hello World
Najpierw utwórz katalog projektu o nazwie publisher i zainstaluj wymagane zależności:
Użyj zestawu AZURE Web PubSub SDK, aby opublikować komunikat w usłudze. publish.js Utwórz plik z następującym kodem:
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
const hub = "pubsub";
let service = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);
// by default it uses `application/json`, specify contentType as `text/plain` if you want plain-text
service.sendToAll(process.argv[2], { contentType: "text/plain" });
Wywołanie service.sendToAll() po prostu wysyła komunikat do wszystkich połączonych klientów w centrum.
Aby wysłać komunikat, uruchom następujące polecenie, zastępując <Web-PubSub-connection-string> ciąg skopiowanym wcześniej parametry połączenia. Jeśli używasz powłoki poleceń systemu Windows, możesz użyć polecenia set zamiast export.
Sprawdź poprzednią powłokę poleceń, aby subskrybent otrzymał komunikat:
Received message: Hello World
Przejdź do pubsub katalogu. Użyj narzędzia Maven, aby utworzyć aplikację webpubsub-quickstart-publisher konsolową wydawcy i przejść do katalogu webpubsub-quickstart-publisher :
Użyj zestawu Azure Web PubSub SDK, aby opublikować komunikat w usłudze. Przejdź do katalogu /src/main/java/com/webpubsub/quickstart , otwórz plik App.java w edytorze i zastąp zawartość następującym kodem:
package com.webpubsub.quickstart;
import com.azure.messaging.webpubsub.*;
import com.azure.messaging.webpubsub.models.*;
/**
* Publish messages using Azure Web PubSub service SDK
*
*/
public class App
{
public static void main( String[] args )
{
if (args.length != 3) {
System.out.println("Expecting 3 arguments: <connection-string> <hub-name> <message>");
return;
}
WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
.connectionString(args[0])
.hub(args[1])
.buildClient();
service.sendToAll(args[2], WebPubSubContentType.TEXT_PLAIN);
}
}
Wywołanie sendToAll() wysyła komunikat do wszystkich połączonych klientów w centrum.
Aby wysłać komunikat, przejdź do katalogu webpubsub-quickstart-publisher i uruchom projekt przy użyciu następującego polecenia. Zastąp wartość <Web-PubSub-connection-string> skopiowaną wcześniej parametry połączenia.
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.