Tutorial: Veröffentlichen und Abonnieren von Nachrichten mithilfe der WebSocket-API und des Azure Web PubSub-Dienst-SDK
Artikel
Der Azure Web PubSub-Dienst hilft Ihnen dabei, ganz einfach Echtzeit-Webmessaginganwendungen zu erstellen. In diesem Tutorial erfahren Sie, wie Sie den Dienst über die WebSocket-API abonnieren und Nachrichten mithilfe des SDK für Web PubSub-Dienst veröffentlichen.
In diesem Tutorial lernen Sie Folgendes:
Erstellen einer Web PubSub-Dienstinstanz
Generieren der vollständigen URL zum Herstellen der WebSocket-Verbindung
Erstellen eines Web PubSub-Abonnentenclients zum Empfangen von Nachrichten über das WebSocket-Standardprotokoll
Erstellen eines Web PubSub-Herausgeberclients zum Veröffentlichen von Nachrichten mithilfe des SDK für den Web PubSub-Dienst
Führen Sie die folgenden Schritte aus, um die Azure-Befehlszeilenschnittstelle (Azure CLI) und Ihre Projektumgebung einzurichten.
Öffnen Sie eine Befehlsshell.
Führen Sie ein Upgrade auf die neueste Version der Azure CLI durch.
az upgrade
Installieren Sie die Azure CLI-Erweiterung für Web PubSub.
az extension add --name webpubsub
Melden Sie sich bei Azure CLI an. Folgen Sie den Eingabeaufforderungen, und geben Sie Ihre Azure-Anmeldeinformationen ein.
az login
Erstellen einer Ressourcengruppe
Eine Ressourcengruppe ist ein logischer Container, in dem Azure-Ressourcen bereitgestellt und verwaltet werden. Erstellen Sie mithilfe des Befehls az group create eine Ressourcengruppe namens myResourceGroup in der Region eastus.
az group create --name myResourceGroup --location EastUS
1. Erstellen einer Azure Web PubSub-Instanz
Erstellen einer Web PubSub-Instanz
Verwenden Sie den Azure CLI-Befehl az webpubsub create, um eine Web PubSub-Instanz in der erstellten Ressourcengruppe zu erstellen. Mit dem folgenden Befehl wird eine Kostenlose Web-PubSub-Ressource unter der Ressourcengruppe myResourceGroup in EastUS erstellt:
Jede Web PubSub-Ressource muss einen eindeutigen Namen haben. Ersetzen Sie im folgenden Befehl <your-unique-resource-name> durch den Namen Ihrer Web PubSub-Instanz.
In der Ausgabe dieses Befehls werden die Eigenschaften der neu erstellten Ressource angezeigt. Notieren Sie sich die folgenden Eigenschaften:
name: Der Web PubSub-Name, den Sie im --name-Parameter angegeben haben.
hostName: Im Beispiel lautet der Hostname <your-unique-resource-name>.webpubsub.azure.com/.
An diesem Punkt ist nur Ihr Azure-Konto zum Ausführen von Vorgängen für die neue Ressource autorisiert.
Abrufen der Verbindungszeichenfolge
Wichtig
Eine Verbindungszeichenfolge enthält die Autorisierungsinformationen, die Ihre Anwendung für den Zugriff auf den Azure Web PubSub-Dienst benötigt. Der Zugriffsschlüssel in der Verbindungszeichenfolge ähnelt einem Stammkennwort für Ihren Dienst. Achten Sie in Produktionsumgebungen immer gut darauf, Ihre Zugriffsschlüssel zu schützen. Verwenden Sie Azure Key Vault zum sicheren Verwalten und Rotieren Ihrer Schlüssel. Geben Sie Zugriffsschlüssel nicht an andere Benutzer weiter, vermeiden Sie das Hartcodieren, und speichern Sie die Schlüssel nicht als Klartext, auf den andere Benutzer Zugriff haben. Rotieren Sie die Schlüssel, wenn Sie glauben, dass sie möglicherweise gefährdet sind.
Verwenden Sie den Azure CLI-Befehl az webpubsub key, um die Verbindungszeichenfolge (ConnectionString) des Diensts abzurufen. Ersetzen Sie den Platzhalter <your-unique-resource-name> durch den Namen Ihrer Azure Web PubSub-Instanz.
az webpubsub key show --resource-group myResourceGroup --name <your-unique-resource-name> --query primaryConnectionString --output tsv
Kopieren Sie die Verbindungszeichenfolge zur späteren Verwendung.
Erstellen eines Abonnentenclients
Clients verbinden sich mit dem Azure Web PubSub-Dienst über das WebSocket-Standardprotokoll unter Verwendung der JSON-Webtoken-Authentifizierung. Das Dienst-SDK stellt Hilfsmethoden zum Generieren des Tokens bereit. In diesem Tutorial generiert der Abonnent das Token direkt aus ConnectionString. In echten Anwendungen wird der Workflow für die Authentifizierung/Autorisierung üblicherweise von einer serverseitigen Anwendung verarbeitet. Informationen zu diesem Workflow finden Sie im Tutorial Erstellen einer Chat-App.
Erstellen Sie zuerst ein Projektverzeichnis namens subscriber für dieses Projekt, und installieren Sie die erforderlichen Abhängigkeiten:
Das Paket Websocket.Client ist ein Drittanbieterpaket, das WebSocket-Verbindungen unterstützt. Sie können jede beliebige API/Bibliothek verwenden, die WebSocket unterstützt.
Das SDK-Paket Azure.Messaging.WebPubSub hilft beim Generieren des JWT-Tokens.
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
Ersetzen Sie den Code in Program.cs durch den folgenden Code, der eine Verbindung mit dem Dienst herstellt:
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();
}
}
}
}
Der Code erstellt eine WebSocket-Verbindung mit einem Hub in Web PubSub. Ein Hub ist eine logische Einheit in Web PubSub, in der Sie Nachrichten für eine Gruppe von Clients veröffentlichen können. Unter Wichtige Konzepte finden Sie ausführliche Erläuterungen der in Web PubSub verwendeten Begriffe.
Der Web PubSub-Dienst verwendet die Authentifizierung über ein JSON Web Token (JWT). Der Beispielcode verwendet WebPubSubServiceClient.GetClientAccessUri() im Web PubSub SDK, um eine URL zum Dienst zu generieren, die die vollständige URL mit einem gültigen Zugriffstoken umfasst.
Nachdem die Verbindung hergestellt wurde, erhält Ihr Client Nachrichten über die WebSocket-Verbindung. Der Client verwendet client.MessageReceived.Subscribe(msg => ...));, um auf eingehende Nachrichten zu lauschen.
Führen Sie zum Starten des Abonnenten den folgenden Befehl aus, und ersetzen Sie <Web-PubSub-connection-string> dabei durch die Verbindungszeichenfolge, die Sie zuvor kopiert haben:
dotnet run <Web-PubSub-connection-string> "myHub1"
Erstellen Sie zuerst ein Projektverzeichnis namens subscriber, und installieren Sie die erforderlichen Abhängigkeiten:
Verwenden Sie die WebSocket-API, um eine Verbindung mit dem Web PubSub-Dienst herzustellen. Erstellen Sie eine Datei subscribe.js mit dem folgenden Code:
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();
Der Code erstellt eine WebSocket-Verbindung mit einem Hub in Web PubSub. Ein Hub ist eine logische Einheit in Web PubSub, in der Sie Nachrichten für eine Gruppe von Clients veröffentlichen können. Unter Wichtige Konzepte finden Sie ausführliche Erläuterungen der in Web PubSub verwendeten Begriffe.
Der Web PubSub-Dienst verwendet die Authentifizierung über ein JSON Web Token (JWT). Der Beispielcode verwendet WebPubSubServiceClient.GetClientAccessUri() im Web PubSub SDK, um eine URL zum Dienst zu generieren, die die vollständige URL mit einem gültigen Zugriffstoken umfasst.
Nachdem die Verbindung hergestellt wurde, erhält Ihr Client Nachrichten über die WebSocket-Verbindung. Der Client verwendet client.MessageReceived.Subscribe(msg => ...));, um auf eingehende Nachrichten zu lauschen.
Führen Sie den folgenden Befehl aus, und ersetzen Sie <Web-PubSub-connection-string> dabei durch die Verbindungszeichenfolge, die Sie zuvor kopiert haben. Wenn Sie die Windows-Befehlsshell verwenden, können Sie set anstelle von export verwenden.
Verwenden Sie die WebSocket-API, um eine Verbindung mit dem Web PubSub-Dienst herzustellen. Erstellen Sie eine Datei subscribe.py mit dem folgenden Code:
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
Der Code erstellt eine WebSocket-Verbindung mit einem Hub in Web PubSub. Ein Hub ist eine logische Einheit in Web PubSub, in der Sie Nachrichten für eine Gruppe von Clients veröffentlichen können. Unter Wichtige Konzepte finden Sie ausführliche Erläuterungen der in Web PubSub verwendeten Begriffe.
Der Web PubSub-Dienst verwendet die Authentifizierung über ein JSON Web Token (JWT). Der Beispielcode verwendet WebPubSubServiceClient.GetClientAccessUri() im Web PubSub SDK, um eine URL zum Dienst zu generieren, die die vollständige URL mit einem gültigen Zugriffstoken umfasst.
Nachdem die Verbindung hergestellt wurde, erhält Ihr Client Nachrichten über die WebSocket-Verbindung. Verwenden Sie await ws.recv(), um auf eingehende Nachrichten zu lauschen.
Führen Sie den folgenden Befehl aus, und ersetzen Sie <Web-PubSub-connection-string> dabei durch die Verbindungszeichenfolge, die Sie zuvor kopiert haben:
Erstellen Sie zuerst ein Projektverzeichnis namens pubsub für dieses Tutorial.
mkdir pubsub
cd pubsub
Verwenden Sie im Verzeichnis pubsub Maven, um eine neue Konsolen-App namens webpubsub-quickstart-subscriber zu erstellen, und wechseln Sie dann zum Verzeichnis webpubsub-quickstart-subscriber:
In Web PubSub können Sie eine Verbindung mit dem Dienst herstellen und Nachrichten über WebSocket-Verbindungen abonnieren. WebSocket ist ein Vollduplex-Kommunikationskanal, über den der Dienst Nachrichten in Echtzeit an Ihren Client pushen kann. Sie können jede beliebige API oder Bibliothek verwenden, die WebSocket unterstützt. Für dieses Beispiel verwenden wir das Paket Java-WebSocket.
Wechseln Sie zum Verzeichnis /src/main/java/com/webpubsub/quickstart.
Bearbeiten Sie die Datei App.java, und ersetzen Sie den Inhalt durch den folgenden Code:
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();
}
}
Dieser Code erstellt eine WebSocket-Verbindung mit einem Hub in Azure Web PubSub. Ein Hub ist eine logische Einheit in Azure Web PubSub, in der Sie Nachrichten für eine Gruppe von Clients veröffentlichen können. Unter Wichtige Konzepte finden Sie ausführliche Erläuterungen der in Azure Web PubSub verwendeten Begriffe.
Der Web PubSub-Dienst verwendet die Authentifizierung über ein JSON Web Token (JWT). Der Beispielcode verwendet WebPubSubServiceClient.GetClientAccessUri() im Web PubSub SDK, um eine URL zum Dienst zu generieren, die die vollständige URL mit einem gültigen Zugriffstoken umfasst.
Nachdem die Verbindung hergestellt wurde, erhält Ihr Client Nachrichten über die WebSocket-Verbindung. Verwenden Sie onMessage(String message), um auf eingehende Nachrichten zu lauschen.
Navigieren Sie zum Starten der Abonnenten-App zum Verzeichnis webpubsub-quickstart-subscriber, und führen Sie den folgenden Befehl aus. Ersetzen Sie <Web-PubSub-connection-string> durch die Verbindungszeichenfolge, die Sie zuvor kopiert haben.
2. Veröffentlichen von Nachrichten mithilfe des Dienst-SDK
Erstellen Sie einen Herausgeber mithilfe des Azure Web PubSub SDK, um eine Nachricht für den verbundenen Client zu veröffentlichen. Für dieses Projekt müssen Sie eine weitere Befehlsshell öffnen.
Erstellen Sie zuerst ein Projektverzeichnis namens publisher, und installieren Sie die erforderlichen Abhängigkeiten:
mkdir publisher
cd publisher
dotnet new console
dotnet add package Azure.Messaging.WebPubSub
Aktualisieren Sie die Datei Program.cs, um die Klasse WebPubSubServiceClient zu verwenden und Nachrichten an die Clients zu senden.
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);
}
}
}
Der Aufruf SendToAllAsync() sendet einfach eine Nachricht an alle verbundenen Clients im Hub.
Senden Sie eine Nachricht, indem Sie den folgenden Befehl ausführen. Ersetzen Sie <Web-PubSub-connection-string> durch die Verbindungszeichenfolge, die Sie zuvor kopiert haben.
dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"
Vergewissern Sie sich, dass die Befehlsshell des Abonnenten diese Nachricht empfängt:
Message received: Hello World
Erstellen Sie zuerst ein Projektverzeichnis namens publisher, und installieren Sie die erforderlichen Abhängigkeiten:
Verwenden Sie das Azure Web PubSub SDK, um eine Nachricht für den Dienst zu veröffentlichen. Erstellen Sie eine Datei publish.js mit dem folgenden Code:
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" });
Der Aufruf service.sendToAll() sendet einfach eine Nachricht an alle verbundenen Clients in einem Hub.
Führen Sie zum Senden einer Nachricht den folgenden Befehl aus, und ersetzen Sie <Web-PubSub-connection-string> dabei durch die Verbindungszeichenfolge, die Sie zuvor kopiert haben. Wenn Sie die Windows-Befehlsshell verwenden, können Sie set anstelle von export verwenden.
Sie sehen, dass der Abonnent die Nachricht erhalten hat:
Message received: Hello World
Erstellen Sie zuerst ein Projektverzeichnis namens publisher, und installieren Sie die erforderlichen Abhängigkeiten:
mkdir publisher
cd publisher
# Create venv
python -m venv env
# Active venv
source ./env/bin/activate
pip install azure-messaging-webpubsubservice
Verwenden Sie das Azure Web PubSub SDK, um eine Nachricht für den Dienst zu veröffentlichen. Erstellen Sie eine Datei publish.py mit dem folgenden Code:
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)
Mit send_to_all() wird die Nachricht an alle verbundenen Clients in einem Hub gesendet.
Führen Sie zum Senden einer Nachricht den folgenden Befehl aus, und ersetzen Sie <Web-PubSub-connection-string> dabei durch die Verbindungszeichenfolge, die Sie zuvor kopiert haben.
Überprüfen Sie in der vorherigen Befehlsshell, ob der Abonnent die Nachricht empfangen hat:
Received message: Hello World
Wechseln Sie zum Verzeichnis pubsub. Verwenden Sie Maven, um eine Herausgeberkonsolen-App namens webpubsub-quickstart-publisher zu erstellen, und wechseln Sie zum Verzeichnis webpubsub-quickstart-publisher:
Verwenden Sie das Azure Web PubSub SDK, um eine Nachricht für den Dienst zu veröffentlichen. Wechseln Sie zum Verzeichnis /src/main/java/com/webpubsub/quickstart, öffnen Sie die Datei App.java in Ihrem Editor, und ersetzen Sie den Inhalt durch folgenden Code:
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);
}
}
Der Aufruf sendToAll() sendet eine Nachricht an alle verbundenen Clients in einem Hub.
Wechseln Sie zum Senden einer Nachricht zum Verzeichnis webpubsub-quickstart-publisher, und führen Sie das Projekt mit dem folgenden Befehl aus. Ersetzen Sie <Web-PubSub-connection-string> durch die Verbindungszeichenfolge, die Sie zuvor kopiert haben.
Sie sehen, dass der Abonnent die Nachricht erhalten hat:
Message received: Hello World
Bereinigen
Sie können die Ressourcen löschen, die Sie in dieser Schnellstartanleitung erstellt haben, indem Sie die Ressourcengruppe löschen, die sie enthält.
az group delete --name myResourceGroup --yes
Wenn Sie nicht planen, Azure Cloud Shell weiterhin zu verwenden, können weitere Kosten vermeiden, indem Sie die Ressourcengruppe löschen, die das zugeordnete Speicherkonto enthält. Die Ressourcengruppe heißt cloud-shell-storage-<your-region>. Führen Sie den folgenden Befehl aus, und ersetzen Sie <CloudShellResourceGroup> durch den Cloud Shell-Gruppennamen.
az group delete --name <CloudShellResourceGroup> --yes
Achtung
Durch das Löschen von Ressourcengruppen werden alle Ressourcen gelöscht, einschließlich solcher, die außerhalb dieses Tutorials erstellt wurden.
Nächste Schritte
In diesem Tutorial haben Sie grundlegende Informationen dazu erhalten, wie Sie eine Verbindung mit dem Web PubSub-Dienst herstellen und Nachrichten für die verbundenen Clients veröffentlichen.
Bearbeiten Sie weitere Tutorials, um mehr über die Nutzung des Diensts zu erfahren.