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

Artykuł
03/10/2024

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.

W przypadku tworzenia projektu na komputerze lokalnym należy zainstalować zależności dla używanego języka:

.NET Core

Przygotowywanie środowiska

Lokalny interfejs wiersza polecenia platformy Azure
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

Użyj polecenia az webpubsub create interfejsu wiersza polecenia platformy Azure, aby utworzyć internetowy pubSub w utworzonej grupie zasobów. 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 dwie poniższe 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 uzyskać Połączenie ionString 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 Połączenie ionString. 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 połą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.

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:

mkdir subscriber
cd subscriber
npm init -y
npm install --save ws
npm install --save @azure/web-pubsub

Użyj interfejsu API protokołu WebSocket, aby nawiązać połączenie z usługą Web PubSub. subscribe.js Utwórz plik z następującym kodem:
```
const WebSocket = require('ws');
const { WebPubSubServiceClient } = require('@azure/web-pubsub');

async function main() {
  const hub = "pubsub";
  let service = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);
  let token = await service.getClientAccessToken();
  let ws = new WebSocket(token.url);
  ws.on('open', () => console.log('connected'));
  ws.on('message', data => console.log('Message received: %s', data));
}

main();
```
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.
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ć set zamiast export.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node subscribe.js
```

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

mkdir subscriber
cd subscriber
# Create venv
python -m venv env
# Activate venv
source ./env/bin/activate

pip install azure-messaging-webpubsubservice
pip install websockets

Użyj interfejsu API protokołu WebSocket, aby nawiązać połączenie z usługą Web PubSub. subscribe.py Utwórz plik z następującym kodem:
```
import asyncio
import sys
import websockets

from azure.messaging.webpubsubservice import WebPubSubServiceClient


async def connect(url):
    async with websockets.connect(url) as ws:
        print('connected')
        while True:
            print('Received message: ' + await ws.recv())

if __name__ == '__main__':

    if len(sys.argv) != 3:
        print('Usage: python subscribe.py <connection-string> <hub-name>')
        exit(1)

    connection_string = sys.argv[1]
    hub_name = sys.argv[2]

    service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
    token = service.get_client_access_token()

    try:
        asyncio.get_event_loop().run_until_complete(connect(token['url']))
    except KeyboardInterrupt:
        pass
```
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 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:
```
python subscribe.py <Web-PubSub-connection-string> "myHub1"
```

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:

mvn archetype:generate --define interactiveMode=n --define groupId=com.webpubsub.quickstart --define artifactId=webpubsub-quickstart-subscriber --define archetypeArtifactId=maven-archetype-quickstart --define archetypeVersion=1.4
cd webpubsub-quickstart-subscriber

Dodaj zestaw WebSocket i zestaw AZURE Web PubSub SDK do węzła w pliku dependenciespom.xml:
- azure-messaging-webpubsub: internetowy zestaw SDK usługi PubSub dla języka Java
- Java-WebSocket: Zestaw SDK klienta protokołu WebSocket dla języka Java
```
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.0.0</version>
</dependency>

<dependency>
    <groupId>org.java-websocket</groupId>
    <artifactId>Java-WebSocket</artifactId>
    <version>1.5.1</version>
</dependency>
```
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 .

Zmodyfikuj zawartość pliku App.java następującym kodem:

package com.webpubsub.quickstart;

import com.azure.messaging.webpubsub.*;
import com.azure.messaging.webpubsub.models.*;

import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;

/**
* Connect to Azure Web PubSub service using WebSocket protocol
*/
public class App 
{
    public static void main( String[] args ) throws IOException, URISyntaxException
    {
        if (args.length != 2) {
            System.out.println("Expecting 2 arguments: <connection-string> <hub-name>");
            return;
        }

        WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
            .connectionString(args[0])
            .hub(args[1])
            .buildClient();

        WebPubSubClientAccessToken token = service.getClientAccessToken(new GetClientAccessTokenOptions());

        WebSocketClient webSocketClient = new WebSocketClient(new URI(token.getUrl())) {
            @Override
            public void onMessage(String message) {
                System.out.println(String.format("Message received: %s", message));
            }

            @Override
            public void onClose(int arg0, String arg1, boolean arg2) {
                // TODO Auto-generated method stub
            }

            @Override
            public void onError(Exception arg0) {
                // TODO Auto-generated method stub
            }

            @Override
            public void onOpen(ServerHandshake arg0) {
                // TODO Auto-generated method stub
            }

        };

        webSocketClient.connect();
        System.in.read();
    }
}

Ten kod tworzy połączenie protokołu WebSocket połączone z centrum w usłudze Azure Web PubSub. Koncentrator to jednostka logiczna w usłudze Azure 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 Azure Web PubSub.

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.
```
mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<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ń.

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ź powłokę poleceń subskrybenta, aby zobaczyć, że odebrano komunikat:
```
Message received: Hello World
```

Najpierw utwórz katalog projektu o nazwie publisher i zainstaluj wymagane zależności:
```
mkdir publisher
cd publisher
npm init -y
npm install --save @azure/web-pubsub
```

Użyj zestawu AZURE Web PubSub SDK, aby opublikować komunikat w usłudze. publish.js Utwórz plik z poniższym 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ć set zamiast export.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node publish "Hello World"
```
Zobaczysz, że subskrybent otrzymał komunikat:
```
Message received: Hello World
```

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

mkdir publisher
cd publisher
# Create venv
python -m venv env
# Active venv
source ./env/bin/activate

pip install azure-messaging-webpubsubservice

Użyj zestawu Azure Web PubSub SDK, aby opublikować komunikat w usłudze. publish.py Utwórz plik z poniższym kodem:

import sys
from azure.messaging.webpubsubservice import WebPubSubServiceClient

if __name__ == '__main__':

    if len(sys.argv) != 4:
        print('Usage: python publish.py <connection-string> <hub-name> <message>')
        exit(1)

    connection_string = sys.argv[1]
    hub_name = sys.argv[2]
    message = sys.argv[3]

    service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
    res = service.send_to_all(message, content_type='text/plain')
    print(res)

Komunikat send_to_all() wyślij do wszystkich połączonych klientów w koncentratonie.

Aby wysłać komunikat, uruchom następujące polecenie, zastępując <Web-PubSub-connection-string> ciąg skopiowanym wcześniej parametry połączenia.
```
python publish.py <Web-PubSub-connection-string> "myHub1" "Hello World"
```
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 :

mvn archetype:generate --define interactiveMode=n --define groupId=com.webpubsub.quickstart --define artifactId=webpubsub-quickstart-publisher --define archetypeArtifactId=maven-archetype-quickstart --define archetypeVersion=1.4
cd webpubsub-quickstart-publisher

Dodaj zależność zestawu AZURE Web PubSub SDK do dependencies węzła :pom.xml

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.0.0</version>
</dependency>

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.
```
mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1' 'Hello World'"
```
Zobaczysz, że subskrybent otrzymał 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.

Samouczek: tworzenie czatroomu za pomocą usługi Azure Web PubSub

Zapoznaj się z więcej przykładów usługi Azure Web PubSub

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