Bibliothèque cliente Azure WebPubSub pour Java

Le SDK côté client vise à accélérer le flux de travail des développeurs ; plus précisément,

• simplifie la gestion des connexions des clients
• simplifie l'envoi de messages entre les clients
• réessaie automatiquement après une interruption involontaire de la connexion du client
• remet de manière fiable les messages en nombre et dans l’ordre après la récupération à partir des suppressions de connexion

Comme le montre le diagramme, vos clients établissent des connexions WebSocket avec votre ressource Web PubSub.

Mise en route

Prérequis

• Kit de développement Java (JDK) avec version 8 ou ultérieure
• Abonnement Azure
• Instance Web PubSub existante

Ajout du package à votre produit

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

Authentifier le client

Un client utilise Client Access URL pour se connecter et s’authentifier auprès du service. L’URL suit le modèle wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Il existe plusieurs options pour obtenir Client Access URL. En guise de démarrage rapide, vous pouvez copier et coller à partir du portail Azure et, pour la production, vous avez généralement besoin d’un serveur de négociation pour générer l’URL. Afficher les détails.

Utiliser Client Access URL depuis le portail Azure

En guise de démarrage rapide, vous pouvez accéder au portail Azure et copier l’URL d’accès client à partir du panneau Clés.

Comme illustré dans le diagramme, le client reçoit l’autorisation d’envoyer des messages à des groupes spécifiques et de joindre des groupes spécifiques. En savoir plus sur l’autorisation du client, consultez autorisations.

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

Utiliser le serveur de négociation pour générer Client Access URL

En production, un client récupère généralement Client Access URL du serveur de négociation. Le serveur contient connection string et génère Client Access URL via WebPubSubServiceClient. En guise d’exemple, l’extrait de code montre simplement comment générer Client Access URL à l’intérieur d’un seul processus.

Des chaînes de connexion brutes sont utilisées dans cet article uniquement à des fins de démonstration. Dans les environnements de production, protégez toujours vos clés d’accès. Utilisez Azure Key Vault pour gérer et faire pivoter vos clés en toute sécurité et sécuriser votre connexion avec 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();

Fonctionnalités permettant de différencier WebPubSubClient et WebPubSubServiceClient.

Exemples

Consommer des messages à partir du serveur et des groupes

Un client peut ajouter des rappels pour consommer des messages à partir du serveur et des groupes. Notez que les clients peuvent uniquement recevoir des messages de groupe qu’ils ont joints.

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());
});

Ajouter des rappels pour des événements connected, disconnected et stopped

Lorsqu’une connexion cliente est connectée au service, l’événement connected est déclenché.

Lorsqu’une connexion cliente est déconnectée et ne parvient pas à récupérer, l’événement disconnected est déclenché.

Lorsqu’un client est arrêté, ce qui signifie que la connexion cliente est déconnectée et que le client cesse de tenter de se reconnecter, l’événement stopped est déclenché. Cela se produit généralement après l’appel de client.StopAsync(), ou après la désactivation de AutoReconnect. Si vous souhaitez redémarrer le client, vous pouvez appeler client.StartAsync() dans l’événement Stopped.

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");
});

Opération et nouvelle tentative

Par défaut, les opérations telle que client.joinGroup(), client.leaveGroup(), client.sendToGroup() et client.sendEvent() ont trois réserves. Vous pouvez utiliser WebPubSubClientBuilder.retryOptions() pour modifier. Si toutes les nouvelles tentatives ont échoué, une erreur est levée. Vous pouvez continuer à réessayer en transmettant les mêmes ackId tentatives que les nouvelles tentatives précédentes, ce qui permet au service de dédupliquer l’opération avec le même ackId.

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

Dépannage

Activer les journaux d’activité

Vous pouvez définir la variable d’environnement suivante pour afficher les journaux de débogage quand vous utilisez cette bibliothèque.

export AZURE_LOG_LEVEL=verbose

Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.

Trace dynamique

Utilisez l’outil Live Trace à partir du Portail Microsoft Azure pour inspecter le trafic des messages en direct via votre ressource Web PubSub.