Partager via

Bibliothèque cliente Azure Communication Chat pour Java - version 1.3.13

  • Article

Azure Communication Chat contient les API utilisées dans les applications de conversation pour Azure Communication Services.

| Code sourcePackage (Maven) | Documentation de référence sur les | APIDocumentation produit

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>

Incluez ensuite la dépendance directe dans la section des dépendances sans la balise de version.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</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-communication-chat</artifactId>
    <version>1.3.13</version>
</dependency>

Concepts clés

Une conversation de conversation est représentée par un thread de conversation. Les utilisateurs d’un fil de conversation sont des « participants ». Les participants peuvent discuter entre eux en privé dans une conversation 1 :1 ou s’entretrer dans une conversation de groupe 1 :N.

Une fois que vous avez initialisé une ChatClient classe et une ChatThreadClient classe, vous pouvez effectuer les opérations de conversation suivantes :

Créer, obtenir, répertorier, mettre à jour et supprimer des threads de conversation

Envoyer, obtenir, répertorier, mettre à jour et supprimer des messages de conversation

Obtenir, ajouter et supprimer des participants

Envoyer et obtenir des reçus de lecture

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.

Définir le point de terminaison de ressource de communication Azure après sa création

endpoint = « https:// Azure-Communication-Resource-Name.communications.azure.com »

Demander un jeton d’accès utilisateur

Les jetons d’accès utilisateur vous permettent de créer des applications clientes qui s’authentifient directement auprès d’Azure Communication Services. Vous générez ces jetons sur votre serveur, vous les transmettez à un appareil client, puis vous les utilisez pour initialiser les sdk Communication Services.

Découvrez comment générer des jetons d’accès utilisateur à partir de jetons d’accès utilisateur

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches les plus courantes, notamment :

Créer le client de conversation

String endpoint = "https://<RESOURCE_NAME>.communcationservices.azure.com";

// Your user access token retrieved from your trusted service
String token = "SECRET";
CommunicationTokenCredential credential = new CommunicationTokenCredential(token);

// Initialize the chat client
final ChatClientBuilder builder = new ChatClientBuilder();
builder.endpoint(endpoint)
    .credential(credential);
ChatClient chatClient = builder.buildClient();

Opérations de thread de conversation

Créer un fil de conversation

Pour créer un client de conversation, vous allez utiliser le point de terminaison Communications Service et le jeton d’accès qui a été généré dans le cadre des étapes préalables requises. Les jetons d’accès utilisateur vous permettent de créer des applications clientes qui s’authentifient directement auprès d’Azure Communication Services. Une fois que vous avez généré ces jetons sur votre serveur, transmettez-les en retour à un appareil client. Vous devez utiliser la classe CommunicationTokenCredential du kit de développement logiciel (SDK) commun pour transmettre le jeton à votre client de conversation.

Utilisez la méthode createChatThread pour créer un fil de conversation. createChatThreadOptions est utilisé pour décrire la demande de thread. Un exemple est illustré dans l’extrait de code ci-dessous.

  • Utilisez topic pour donner une rubrique de thread ;
  • Permet participants de répertorier les participants au thread à ajouter au thread ;

CreateChatThreadResult correspond à la réponse renvoyée par la création d’un fil de conversation. Elle contient une méthode getChatThread() qui renvoie l'objet ChatThread permettant d’obtenir le client de fil de conversation à partir duquel obtenir ChatThreadClient pour effectuer des opérations sur la conversation créée : ajout de participants, envoi d’un message, etc. L'objet ChatThread contient également la méthode getId() qui récupère l’ID unique de la conversation.

List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

ChatParticipant firstParticipant = new ChatParticipant()
    .setCommunicationIdentifier(user1)
    .setDisplayName("Participant Display Name 1");

ChatParticipant secondParticipant = new ChatParticipant()
    .setCommunicationIdentifier(user2)
    .setDisplayName("Participant Display Name 2");

participants.add(firstParticipant);
participants.add(secondParticipant);

CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions("Topic")
    .setParticipants(participants);
CreateChatThreadResult result = chatClient.createChatThread(createChatThreadOptions);

String chatThreadId = result.getChatThread().getId();

Obtenir les propriétés d’un thread de conversation

La getChatThreadProperties méthode récupère les propriétés d’un thread à partir du service.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient("Id");
ChatThreadProperties chatThreadProperties = chatThreadClient.getProperties();

Supprimer un thread

Utiliser deleteChatThread la méthode pour supprimer un thread chatThreadId de conversation est l’ID unique du thread de conversation.

String chatThreadId = "Id";
chatClient.deleteChatThread(chatThreadId);

Obtenir un client de fil de conversation

La méthode getChatThreadClient retourne un client de fil pour un fil qui existe déjà. Elle peut être utilisée pour effectuer des opérations sur le fil créé : ajout de participants, envoi d’un message, etc. chatThreadId est l’ID unique du fil de conversation existant.

String chatThreadId = "Id";
ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Mettre à jour une rubrique de thread de conversation

La méthode d’utilisation updateTopic pour mettre à jour la rubrique topic d’un thread est utilisée pour contenir la nouvelle rubrique du thread.

chatThreadClient.updateTopic("New Topic");

Opérations de message de conversation

Envoyer un message de conversation

Utilisez la sendMessage méthode pour envoyer un message de conversation au thread de conversation avec lequel le chatThreadClient a été créé. sendChatMessageOptions est utilisé pour décrire la demande de message de conversation. Un exemple est illustré dans l’extrait de code ci-dessous.

  • Utilisez content pour fournir le contenu du message de conversation ;
  • Permet priority de spécifier le niveau de priorité du message de conversation, tel que « Normal » ou « Élevé » ;
  • Utilisez senderDisplayName pour spécifier le nom d’affichage de l’expéditeur ;

Réponse SendChatMessageResult retournée par l’envoi d’un message de conversation, elle contient un ID, qui est l’ID unique du message.

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
    .setContent("Message content")
    .setSenderDisplayName("Sender Display Name");

SendChatMessageResult sendResult = chatThreadClient.sendMessage(sendChatMessageOptions);

Obtenir un message de conversation

La getMessage méthode récupère un message de conversation à partir du service. chatMessageId est l’ID unique du message de conversation.

String chatMessageId = "Id";
ChatMessage chatMessage = chatThreadClient.getMessage(chatMessageId);

Obtenir des messages de conversation

Vous pouvez récupérer des messages de conversation à l’aide de la listMessages méthode sur le client de thread de conversation à des intervalles spécifiés (interrogation).

PagedIterable<ChatMessage> chatMessagesResponse = chatThreadClient.listMessages();
chatMessagesResponse.iterableByPage().forEach(resp -> {
    System.out.printf("Response headers are %s. Url %s  and status code %d %n", resp.getHeaders(),
        resp.getRequest().getUrl(), resp.getStatusCode());
    resp.getElements().forEach(message ->
        System.out.printf("Message id is %s.", message.getId()));
});

listMessages retourne la version la plus récente du message, avec les modifications ou les suppressions dont le message a éventuellement fait l’objet via .editMessage() et .deleteMessage().

Pour les messages supprimés, chatMessage.getDeletedOn() retourne une valeur datetime indiquant à quel moment ce message a été supprimé.

Pour les messages modifiés, chatMessage.getEditedOn() retourne une valeur datetime indiquant à quel moment ce message a été modifié.

Il est possible d’accéder à l’heure initiale de création du message à l’aide de chatMessage.getCreatedOn() ; elle peut être utilisée à des fins de classement des messages.

listMessages retourne différents types de messages qui peuvent être identifiés par chatMessage.getType(). Ces types sont les suivants :

  • text : Message de conversation ordinaire envoyé par un participant au fil de conversation.

  • html : message de conversation envoyé par un participant au fil de conversation.

  • topicUpdated: Message système qui indique que le sujet a été mis à jour

  • participantAdded : Message système qui indique qu’un ou plusieurs participants ont été ajoutés au fil de conversation.

  • participantRemoved : Message système qui indique qu’un participant a été supprimé du fil de conversation.

Pour plus d’informations, consultez Types de messages.

Mettre à jour un message de conversation

Utilisez updateMessage pour mettre à jour un message de conversation identifié par chatThreadId et messageId. chatMessageId est l’ID unique du message de conversation. updateChatMessageOptions est utilisé pour décrire la demande de mise à jour d’un message de conversation. Un exemple est illustré dans l’extrait de code ci-dessous.

  • Utilisez content pour fournir un nouveau contenu de message de conversation ;
String chatMessageId = "Id";
UpdateChatMessageOptions updateChatMessageOptions = new UpdateChatMessageOptions()
    .setContent("Updated message content");

chatThreadClient.updateMessage(chatMessageId, updateChatMessageOptions);

Supprimer un message de conversation

Utilisez updateMessage pour mettre à jour un message de conversation identifié par chatMessageId. chatMessageId est l’ID unique du message de conversation.

String chatMessageId = "Id";
chatThreadClient.deleteMessage(chatMessageId);

Opérations des participants au thread de conversation

Répertorier les participants à la conversation

Utilisez listParticipants pour récupérer une collection paginée contenant les participants du fil de conversation.

PagedIterable<ChatParticipant> chatParticipantsResponse = chatThreadClient.listParticipants();
chatParticipantsResponse.iterableByPage().forEach(resp -> {
    System.out.printf("Response headers are %s. Url %s  and status code %d %n", resp.getHeaders(),
        resp.getRequest().getUrl(), resp.getStatusCode());
    resp.getElements().forEach(chatParticipant ->
        System.out.printf("Participant id is %s.", ((CommunicationUserIdentifier) chatParticipant.getCommunicationIdentifier()).getId()));
});

Ajouter des participants

Utilisez addParticipants la méthode pour ajouter des participants au fil de conversation. participants liste des participants à ajouter au thread ;

  • communicationIdentifier, obligatoire, est le CommunicationIdentifier que vous avez créé à l’aide de CommunicationIdentityClient. Plus d’informations sur : Créer un utilisateur.
  • display_name, facultatif, est le nom d’affichage du membre du fil.
  • share_history_time, facultatif, est le moment à partir duquel l’historique de conversation est partagé avec le membre. Pour partager l’historique depuis le début du fil de conversation, attribuez à cette propriété une date égale ou antérieure à la date de création du fil. Pour ne partager aucun historique antérieur au moment où le membre a été ajouté, attribuez-lui l’heure actuelle. Pour partager un historique partiel, attribuez-lui la date de votre choix.
List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

ChatParticipant firstParticipant = new ChatParticipant()
    .setCommunicationIdentifier(user1)
    .setDisplayName("Display Name 1");

ChatParticipant secondParticipant = new ChatParticipant()
    .setCommunicationIdentifier(user2)
    .setDisplayName("Display Name 2");

participants.add(firstParticipant);
participants.add(secondParticipant);

chatThreadClient.addParticipants(participants);

Retirer un participant

Utilisez removeParticipant la méthode pour supprimer un participant du fil de conversation. identifier est le CommunicationIdentifier que vous avez créé.

chatThreadClient.removeParticipant(user);

Opérations de confirmation de lecture

Envoyer une confirmation de lecture

Utilisez sendReadReceipt la méthode pour publier un événement de confirmation de lecture sur un fil de conversation, au nom d’un utilisateur. chatMessageId correspond à ID unique du message de conversation lu.

String chatMessageId = "Id";
chatThreadClient.sendReadReceipt(chatMessageId);

Obtenir des confirmations de lecture

getReadReceipts la méthode récupère les confirmations de lecture pour un fil de conversation.

PagedIterable<ChatMessageReadReceipt> readReceiptsResponse = chatThreadClient.listReadReceipts();
readReceiptsResponse.iterableByPage().forEach(resp -> {
    System.out.printf("Response headers are %s. Url %s  and status code %d %n", resp.getHeaders(),
        resp.getRequest().getUrl(), resp.getStatusCode());
    resp.getElements().forEach(readReceipt ->
        System.out.printf("Read message id is %s.", readReceipt.getChatMessageId()));
});

Opérations de notification de saisie

Envoyer une notification de saisie

Utilisez sendTypingNotification la méthode pour publier un événement de notification de saisie sur un thread de conversation, au nom d’un utilisateur. typingNotificationOptions est utilisé pour décrire la demande de notification de saisie.

  • Utilisez senderDisplayName pour définir le nom d’affichage de l’expéditeur de la notification ;
TypingNotificationOptions options = new TypingNotificationOptions();
options.setSenderDisplayName("Sender Display Name");
chatThreadClient.sendTypingNotificationWithResponse(options, Context.NONE);

Dépannage

En cours.

Étapes suivantes

Consulter d’autres bibliothèques clientes pour le service de communication Azure