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.
Otwórz wiersz poleceń.
Zaktualizuj do najnowszej wersji Azure CLI.
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. 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.
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
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.
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"
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 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.
Uruchom następujące polecenie, zastępując <Web-PubSub-connection-string> skopiowanym wcześniej ciągiem połączenia. Jeśli używasz powłoki poleceń systemu Windows, możesz użyć polecenia 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 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 będzie odbierał komunikaty za pośrednictwem połączenia protokołu WebSocket. Użyj await ws.recv(), aby nasłuchiwać przychodzących wiadomości.
Uruchom następujące polecenie, zastępując <Web-PubSub-connection-string> ciągi połączenia skopiowanymi wcześniej:
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 WebSocket i Azure Web PubSub SDK do węzła 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 do grupy klientów.
Kluczowe pojęcia zawierają szczegółowe wyjaśnienie terminów używanych w usłudze Azure 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 będzie odbierał komunikaty za pośrednictwem połączenia protokołu WebSocket. Użyj onMessage(String message), 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 wartość <Web-PubSub-connection-string> parametrami połączenia skopiowanymi wcześniej.
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. Aby zrealizować ten projekt, musisz otworzyć nową konsolę.
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.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.
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"
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:
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 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ągi połączenia skopiowanymi wcześniej. Jeśli używasz powłoki poleceń systemu Windows, możesz użyć polecenia 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 następującym 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)
Wyślij send_to_all() komunikat do wszystkich połączonych klientów w hubie.
Aby wysłać komunikat, uruchom następujące polecenie, zastępując <Web-PubSub-connection-string> ciągi połączenia skopiowanymi wcześniej.
python publish.py <Web-PubSub-connection-string> "myHub1" "Hello World"
Sprawdź poprzednią powłokę poleceń, aby upewnić się, że 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ść pakietu Azure Web PubSub SDK do węzła dependenciespom.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 hubie.
Aby wysłać komunikat, przejdź do katalogu webpubsub-quickstart-publisher i uruchom projekt przy użyciu następującego polecenia. Zastąp element <Web-PubSub-connection-string> parametrami połączenia skopiowanymi wcześniej.
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
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.