Partager via

Bibliothèque cliente du service Azure Web PubSub pour Java - version 1.2.9

  • Article

Le service Azure Web PubSub est un service géré Azure qui aide les développeurs à créer facilement des applications web avec des fonctionnalités en temps réel et un modèle publication-abonnement. Tout scénario qui nécessite une messagerie de type publication-abonnement en temps réel entre un serveur et des clients ou entre des clients peut avoir recours au service Azure Web PubSub. Les fonctionnalités en temps réel traditionnelles qui demandent souvent d’interroger un serveur ou d’envoyer des requêtes HTTP peuvent aussi utiliser le service Azure Web PubSub.

Vous pouvez utiliser cette bibliothèque dans vos applications côté serveur pour gérer les connexions client WebSocket, comme indiqué dans le diagramme ci-dessous :

Débordement

Utilisez cette bibliothèque pour effectuer les opérations suivantes :

  • Envoyer des messages aux hubs et aux groupes.
  • Envoyer des messages à des utilisateurs particuliers et à des connexions.
  • Organiser les utilisateurs et les connexions en groupes.
  • Fermer les connexions
  • Accorder, révoquer et vérifier des autorisations pour une connexion existante

Les détails des termes utilisés ici sont décrits dans la section Concepts clés.

Code source | Documentation de référence de l’API | Documentation du produit | Exemples

Prise en main

Prérequis

Inclure le package

Inclure le fichier de nomenclature

Incluez le kit azure-sdk-bom à votre projet pour qu’il soit dépendant de la version disponibilité générale (GA) de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez LE FICHIER README DE NOMENCLATURE DU KIT DE DÉVELOPPEMENT LOGICIEL AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

puis incluez la dépendance directe dans la section dépendances sans la balise de version comme indiqué ci-dessous.

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

Inclure une dépendance directe

Si vous souhaitez prendre la dépendance sur une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

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

Créer un WebPubSubServiceClient à l’aide d’une chaîne de connexion

WebPubSubServiceClient webPubSubServiceClient = new WebPubSubServiceClientBuilder()
    .connectionString("{connection-string}")
    .hub("chat")
    .buildClient();

Créer un WebPubSubServiceClient à l’aide d’une clé d’accès

WebPubSubServiceClient webPubSubServiceClient = new WebPubSubServiceClientBuilder()
    .credential(new AzureKeyCredential("{access-key}"))
    .endpoint("<Insert endpoint from Azure Portal>")
    .hub("chat")
    .buildClient();

Concepts clés

Connexion

Une connexion, également appelée client ou connexion client, représente une connexion WebSocket individuelle connectée au service Web PubSub. Une fois la connexion réussie, un ID de connexion unique est affecté à cette connexion par le service Web PubSub.

Hub

Un hub est un concept logique pour un ensemble de connexions client. En règle générale, vous utilisez un hub dans un seul but, par exemple un hub de conversations ou un hub de notifications. Lorsqu’une connexion client est créée, elle se connecte à un hub et, pendant toute sa durée de vie, elle appartient à ce hub. Différentes applications peuvent partager un service Azure Web PubSub en utilisant différents noms de hubs.

Groupe

Un groupe est un sous-ensemble de connexions au hub. Vous pouvez ajouter une connexion cliente à un groupe, ou la supprimer du groupe, quand vous le souhaitez. Par exemple, quand un client rejoint une salle de conversation ou quand il la quitte, cette salle de conversation peut être considérée comme un groupe. Un client peut rejoindre plusieurs groupes, et un groupe peut contenir plusieurs clients.

Utilisateur

Les connexions à Web PubSub ne peuvent appartenir qu’à un seul utilisateur. Un utilisateur peut avoir plusieurs connexions. C’est le cas, par exemple, quand un seul utilisateur est connecté sur plusieurs appareils ou plusieurs onglets de navigateur.

Message

Quand le client est connecté, il peut envoyer des messages à l’application en amont ou recevoir des messages de l’application en amont par le biais de la connexion WebSocket.

Exemples

Diffuser un message à l’ensemble d’un hub

webPubSubServiceClient.sendToAll("Hello world!", WebPubSubContentType.TEXT_PLAIN);

Diffuser le message sur l’ensemble du hub avec filtre

// send a text message to the entire hub with a filter on userId
BinaryData message = BinaryData.fromString("Hello World - Broadcast test!");
webPubSubServiceClient.sendToAllWithResponse(
    message,
    WebPubSubContentType.TEXT_PLAIN,
    message.getLength(),
    new RequestOptions().addQueryParam("filter", "userId ne 'user1'"));

// send a text message to the entire hub with another filter on group
webPubSubServiceClient.sendToAllWithResponse(
    message,
    WebPubSubContentType.TEXT_PLAIN,
    message.getLength(),
    new RequestOptions().addQueryParam("filter", "'GroupA' in groups and not('GroupB' in groups)"));

Diffusez un message à un groupe

webPubSubServiceClient.sendToGroup("java", "Hello Java!", WebPubSubContentType.TEXT_PLAIN);

Envoyer un message à une connexion

webPubSubServiceClient.sendToConnection("myconnectionid", "Hello connection!", WebPubSubContentType.TEXT_PLAIN);

Envoyer un message à un utilisateur

webPubSubServiceClient.sendToUser("Andy", "Hello Andy!", WebPubSubContentType.TEXT_PLAIN);

Dépannage

Activer la journalisation du client

Vous pouvez définir la variable d’environnement AZURE_LOG_LEVEL pour afficher les instructions de journalisation figurant dans la bibliothèque de client. Par exemple, le paramètre AZURE_LOG_LEVEL=2 affiche tous les messages d’information, d’avertissement et de journal des erreurs. Les niveaux de journal se trouvent ici : niveaux de journal.

Client HTTP par défaut

Toutes les bibliothèques de client utilisent par défaut le client HTTP Netty. L’ajout de la dépendance ci-dessus configure automatiquement la bibliothèque de client pour utiliser le client HTTP Netty. La configuration ou la modification du client HTTP sont détaillées dans le wiki pour clients HTTP.

Bibliothèque SSL par défaut

Toutes les bibliothèques de client utilisent par défaut la bibliothèque BoringSSL Tomcat native pour permettre des performances de niveau natif pour les opérations SSL. La bibliothèque BoringSSL est un fichier uber jar contenant des bibliothèques natives pour Linux/macOS/Windows. Elle offre de meilleures performances que l’implémentation SSL par défaut au sein du JDK. Pour plus d’informations, notamment sur la réduction de la taille des dépendances, consultez la section du wiki consacrée à l’optimisation des performances.

Étapes suivantes

  • Les exemples sont expliqués en détail ici.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) spécifiant que vous avez le droit de nous accorder les droits d’utiliser votre contribution, et que vous nous les accordez.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions