SDK Azure Web PubSub pour Java

Construisez des applications web en temps réel avec le SDK Azure Web PubSub pour Java.

Installation

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

Création du client

Avec une chaîne de connexion

import com.azure.messaging.webpubsub.WebPubSubServiceClient;
import com.azure.messaging.webpubsub.WebPubSubServiceClientBuilder;

WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
    .connectionString("<connection-string>")
    .hub("chat")
    .buildClient();

Avec une clé d'accès

import com.azure.core.credential.AzureKeyCredential;

WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
    .credential(new AzureKeyCredential("<access-key>"))
    .endpoint("<endpoint>")
    .hub("chat")
    .buildClient();

Avec DefaultAzureCredential

import com.azure.identity.DefaultAzureCredentialBuilder;

WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .endpoint("<endpoint>")
    .hub("chat")
    .buildClient();

Client asynchrone

import com.azure.messaging.webpubsub.WebPubSubServiceAsyncClient;

WebPubSubServiceAsyncClient asyncClient = new WebPubSubServiceClientBuilder()
    .connectionString("<connection-string>")
    .hub("chat")
    .buildAsyncClient();

Concepts clés

• Hub : Unité d'isolation logique pour les connexions
• Group : Sous-ensemble de connexions au sein d'un hub
• Connection : Connexion client WebSocket individuelle
• User : Entité pouvant avoir plusieurs connexions

Modèles principaux

Envoyer à toutes les connexions

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

// Envoyer un message texte
client.sendToAll("Hello everyone!", WebPubSubContentType.TEXT_PLAIN);

// Envoyer du JSON
String jsonMessage = "{\"type\": \"notification\", \"message\": \"New update!\"}";
client.sendToAll(jsonMessage, WebPubSubContentType.APPLICATION_JSON);

Envoyer à tous avec filtre

import com.azure.core.http.rest.RequestOptions;
import com.azure.core.util.BinaryData;

BinaryData message = BinaryData.fromString("Hello filtered users!");

// Filtrer par userId
client.sendToAllWithResponse(
    message,
    WebPubSubContentType.TEXT_PLAIN,
    message.getLength(),
    new RequestOptions().addQueryParam("filter", "userId ne 'user1'"));

// Filtrer par groupes
client.sendToAllWithResponse(
    message,
    WebPubSubContentType.TEXT_PLAIN,
    message.getLength(),
    new RequestOptions().addQueryParam("filter", "'GroupA' in groups and not('GroupB' in groups)"));

Envoyer à un groupe

// Envoyer à toutes les connexions d'un groupe
client.sendToGroup("java-developers", "Hello Java devs!", WebPubSubContentType.TEXT_PLAIN);

// Envoyer du JSON à un groupe
String json = "{\"event\": \"update\", \"data\": {\"version\": \"2.0\"}}";
client.sendToGroup("subscribers", json, WebPubSubContentType.APPLICATION_JSON);

Envoyer à une connexion spécifique

// Envoyer à une connexion spécifique par ID
client.sendToConnection("connectionId123", "Private message", WebPubSubContentType.TEXT_PLAIN);

Envoyer à un utilisateur

// Envoyer à toutes les connexions d'un utilisateur spécifique
client.sendToUser("andy", "Hello Andy!", WebPubSubContentType.TEXT_PLAIN);

Gérer les groupes

// Ajouter une connexion à un groupe
client.addConnectionToGroup("premium-users", "connectionId123");

// Retirer une connexion d'un groupe
client.removeConnectionFromGroup("premium-users", "connectionId123");

// Ajouter un utilisateur à un groupe (toutes ses connexions)
client.addUserToGroup("admin-group", "userId456");

// Retirer un utilisateur d'un groupe
client.removeUserFromGroup("admin-group", "userId456");

// Vérifier si un utilisateur est dans un groupe
boolean exists = client.userExistsInGroup("admin-group", "userId456");

Gérer les connexions

// Vérifier si une connexion existe
boolean connected = client.connectionExists("connectionId123");

// Fermer une connexion
client.closeConnection("connectionId123");

// Fermer avec un motif
client.closeConnection("connectionId123", "Session expired");

// Vérifier si un utilisateur existe (a au moins une connexion)
boolean userOnline = client.userExists("userId456");

// Fermer toutes les connexions d'un utilisateur
client.closeUserConnections("userId456");

// Fermer toutes les connexions d'un groupe
client.closeGroupConnections("inactive-group");

Générer un token d'accès client

import com.azure.messaging.webpubsub.models.GetClientAccessTokenOptions;
import com.azure.messaging.webpubsub.models.WebPubSubClientAccessToken;

// Token basique
WebPubSubClientAccessToken token = client.getClientAccessToken(
    new GetClientAccessTokenOptions());
System.out.println("URL: " + token.getUrl());

// Avec un ID utilisateur
WebPubSubClientAccessToken userToken = client.getClientAccessToken(
    new GetClientAccessTokenOptions().setUserId("user123"));

// Avec des rôles (permissions)
WebPubSubClientAccessToken roleToken = client.getClientAccessToken(
    new GetClientAccessTokenOptions()
        .setUserId("user123")
        .addRole("webpubsub.joinLeaveGroup")
        .addRole("webpubsub.sendToGroup"));

// Avec des groupes à rejoindre à la connexion
WebPubSubClientAccessToken groupToken = client.getClientAccessToken(
    new GetClientAccessTokenOptions()
        .setUserId("user123")
        .addGroup("announcements")
        .addGroup("updates"));

// Avec expiration personnalisée
WebPubSubClientAccessToken expToken = client.getClientAccessToken(
    new GetClientAccessTokenOptions()
        .setUserId("user123")
        .setExpiresAfter(Duration.ofHours(2)));

Accorder/révoquer des permissions

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

// Accorder une permission d'envoi à un groupe
client.grantPermission(
    WebPubSubPermission.SEND_TO_GROUP,
    "connectionId123",
    new RequestOptions().addQueryParam("targetName", "chat-room"));

// Révoquer une permission
client.revokePermission(
    WebPubSubPermission.SEND_TO_GROUP,
    "connectionId123",
    new RequestOptions().addQueryParam("targetName", "chat-room"));

// Vérifier une permission
boolean hasPermission = client.checkPermission(
    WebPubSubPermission.SEND_TO_GROUP,
    "connectionId123",
    new RequestOptions().addQueryParam("targetName", "chat-room"));

Opérations asynchrones

asyncClient.sendToAll("Async message!", WebPubSubContentType.TEXT_PLAIN)
    .subscribe(
        unused -> System.out.println("Message sent"),
        error -> System.err.println("Error: " + error.getMessage())
    );

asyncClient.sendToGroup("developers", "Group message", WebPubSubContentType.TEXT_PLAIN)
    .doOnSuccess(v -> System.out.println("Sent to group"))
    .doOnError(e -> System.err.println("Failed: " + e))
    .subscribe();

Gestion des erreurs

import com.azure.core.exception.HttpResponseException;

try {
    client.sendToConnection("invalid-id", "test", WebPubSubContentType.TEXT_PLAIN);
} catch (HttpResponseException e) {
    System.out.println("Status: " + e.getResponse().getStatusCode());
    System.out.println("Error: " + e.getMessage());
}

Variables d'environnement

WEB_PUBSUB_CONNECTION_STRING=Endpoint=https://<resource>.webpubsub.azure.com;AccessKey=...
WEB_PUBSUB_ENDPOINT=https://<resource>.webpubsub.azure.com
WEB_PUBSUB_ACCESS_KEY=<your-access-key>

Rôles client

Bonnes pratiques

1. Utiliser les groupes : Organisez les connexions en groupes pour des messages ciblés
2. IDs utilisateur : Associez les connexions aux IDs utilisateur pour la messagerie au niveau utilisateur
3. Expiration du token : Définissez une expiration appropriée pour la sécurité
4. Rôles : Accordez les permissions minimales requises via les rôles
5. Isolation du hub : Utilisez des hubs séparés pour différentes fonctionnalités de l'application
6. Gestion des connexions : Nettoyez les connexions inactives

Expressions déclencheurs

• "Web PubSub Java"
• "Messagerie WebSocket Azure"
• "Notifications push en temps réel"
• "Événements envoyés par le serveur"
• "Backend d'application de chat"
• "Diffusion de mises à jour en direct"