Azure Web PubSub-Clientbibliothek für Java

Hinweis

Details zu den hier verwendeten Begriffen werden im Artikel Wichtige Begriffe beschrieben.

Das clientseitige SDK soll den Entwicklungsworkflow insbesondere durch Folgendes beschleunigen:

• Vereinfachung der Verwaltung von Clientverbindungen
• Vereinfachung der Nachrichtenübermittlung zwischen Clients
• Automatische Wiederholungen nach unbeabsichtigten Abbrüchen von Clientverbindungen
• Zuverlässige Übermittlung aller Nachrichten in der richtigen Reihenfolge bei der Wiederherstellung nach Verbindungsabbrüchen

Wie in der Abbildung dargestellt, richten Ihre Clients WebSocket-Verbindungen mit Ihrer Web PubSub-Ressource ein.

Wichtig

Unformatierte Verbindungszeichenfolgen werden in diesem Artikel nur zu Demonstrationszwecken angezeigt.

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. Schützen Sie Ihre Zugriffsschlüssel in Produktionsumgebungen immer sorgfältig. Verwenden Sie Azure Key Vault zum sicheren Verwalten und Rotieren Ihrer Schlüssel und zum Schützen Ihrer Verbindung mit WebPubSubServiceClient.

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.

Erste Schritte

Voraussetzungen

• Java Development Kit (JDK), Version 8 oder höher
• Azure-Abonnement
• Eine vorhandene Web PubSub-Instanz

Hinzufügen des Pakets zu Ihrem Produkt

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

Authentifizieren des Clients

Ein Client verwendet eine Client Access URL, um eine Verbindung herzustellen und sich beim Dienst zu authentifizieren. Diese URL hat folgendes Muster: wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Es verschiedene Möglichkeiten, eine Client Access URL abzurufen. Als Schnellstart können Sie sie aus dem Azure-Portal kopieren und einfügen. In der Produktion benötigen Sie in der Regel einen Aushandlungsserver, um die URL zu generieren. Details anzeigen

Verwenden der Client Access URL im Azure-Portal

Als Schnellstart können Sie zum Azure-Portal navigieren und die Clientzugriffs-URL auf dem Blatt Schlüssel kopieren.

Wie in der Abbildung dargestellt, erhält der Client die Berechtigung zum Senden von Nachrichten an bestimmte Gruppen und zum Beitreten zu bestimmten Gruppen. Weitere Informationen zu Clientberechtigungen finden Sie unter Berechtigungen.

WebPubSubClient client = new WebPubSubClientBuilder()
    .clientAccessUrl("<client-access-url>")
    .buildClient();

Verwenden des Aushandlungsservers zum Generieren einer Client Access URL

In der Produktion ruft ein Client die Client Access URL in der Regel von einem Aushandlungsserver ab. Der Server hat die connection string und generiert die Client Access URL mit WebPubSubServiceClient. Der Codeschnipsel zeigt lediglich ein Beispiel, wie die Client Access URL innerhalb eines einzelnen Prozesses generiert wird.

Unformatierte Verbindungszeichenfolgen werden in diesem Artikel nur zu Demonstrationszwecken angezeigt. Schützen Sie Ihre Zugriffsschlüssel in Produktionsumgebungen immer sorgfältig. Verwenden Sie Azure Key Vault zum sicheren Verwalten und Rotieren Ihrer Schlüssel und zum Schützen Ihrer Verbindung mit WebPubSubServiceClient.

// WebPubSubServiceAsyncClient is from com.azure:azure-messaging-webpubsub
// create WebPubSub service client
WebPubSubServiceAsyncClient serverClient = new WebPubSubServiceClientBuilder()
    .connectionString("<connection-string>")
    .hub("<hub>>")
    .buildAsyncClient();

// wrap WebPubSubServiceAsyncClient.getClientAccessToken as WebPubSubClientCredential
WebPubSubClientCredential clientCredential = new WebPubSubClientCredential(Mono.defer(() ->
    serverClient.getClientAccessToken(new GetClientAccessTokenOptions()
            .setUserId("<user-name>")
            .addRole("webpubsub.joinLeaveGroup")
            .addRole("webpubsub.sendToGroup"))
        .map(WebPubSubClientAccessToken::getUrl)));

// create WebPubSub client
WebPubSubClient client = new WebPubSubClientBuilder()
    .credential(clientCredential)
    .buildClient();

Features zur Unterscheidung von WebPubSubClient und WebPubSubServiceClient

Klassenname	WebPubSubClient	WebPubSubServiceClient
Paketname	azure-messaging-webpubsub-client	azure-messaging-webpubsub
Funktionen	Wird auf Clientseite verwendet Veröffentlicht und abonniert Nachrichten	Wird auf Serverseite verwendet Generiert Client Access URL und verwaltet Clients

Beispiele

Verwenden der Nachrichten vom Server und aus Gruppen

Ein Client kann Rückrufe hinzufügen, um Nachrichten vom Server und aus Gruppen zu nutzen. Beachten Sie, dass Clients nur Gruppennachrichten von Gruppen empfangen können, denen sie beigetreten sind.

client.addOnGroupMessageEventHandler(event -> {
    System.out.println("Received group message from " + event.getFromUserId() + ": "
        + event.getData().toString());
});
client.addOnServerMessageEventHandler(event -> {
    System.out.println("Received server message: "
        + event.getData().toString());
});

Hinzufügen von Rückrufen für die Ereignisse connected, disconnected und stopped

Wenn eine Clientverbindung mit dem Dienst hergestellt wird, löst dies das connected-Ereignis aus.

Wenn eine Clientverbindung getrennt wird und nicht wiederhergestellt werden kann, wird das disconnected-Ereignis ausgelöst.

Wenn ein Client beendet wird, also die Clientverbindung getrennt wird und der Client die keine erneuten Verbindungsversuche durchführt, wird das stopped-Ereignis ausgelöst. Dies passiert in der Regel nach dem Aufruf von client.StopAsync() oder der Deaktivierung von AutoReconnect. Wenn Sie den Client neu starten möchten, können Sie client.StartAsync() im Stopped-Ereignis aufrufen.

client.addOnConnectedEventHandler(event -> {
    System.out.println("Connection is connected: " + event.getConnectionId());
});
client.addOnDisconnectedEventHandler(event -> {
    System.out.println("Connection is disconnected");
});
client.addOnStoppedEventHandler(event -> {
    System.out.println("Client is stopped");
});

Vorgang und Wiederholung

Standardmäßig werden bei Vorgängen wie client.joinGroup(), client.leaveGroup(), client.sendToGroup() oder client.sendEvent() drei Wiederholungen durchgeführt. Sie können dies mit WebPubSubClientBuilder.retryOptions() ändern. Wenn alle Wiederholungen fehlerhaft waren, wird ein Fehler ausgelöst. Sie können den Vorgang weiterhin wiederholen, indem Sie dieselbe ackId wie bei vorherigen Wiederholungen übergeben, sodass der Dienst dazu beitragen kann, den Vorgang mit derselben ackId zu deduplizieren.

try {
    client.joinGroup("testGroup");
} catch (SendMessageFailedException e) {
    if (e.getAckId() != null) {
        client.joinGroup("testGroup", e.getAckId());
    }
}

Problembehandlung

Aktivieren von Protokollen

Sie können die folgende Umgebungsvariable festlegen, um Debugprotokolle anzuzeigen, wenn Sie diese Bibliothek verwenden.

export AZURE_LOG_LEVEL=verbose

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in der Paketdokumentation zu @azure/logger.

Live-Ablaufverfolgung

Verwenden Sie im Azure-Portal das Tool Live-Ablaufverfolgung, um den Nachrichtendatenverkehr über Ihre Web PubSub-Ressource live zu überprüfen.