Partager via

Bibliothèque cliente Azure Communication Chat pour .NET - version 1.1.2

  • Article

Ce package contient un Kit de développement logiciel (SDK) C# pour Azure Communication Services pour la conversation.

| Code sourcePackage (NuGet) | Documentation produit

Prise en main

Installer le package

Installez la bibliothèque de client Azure Communication Chat pour .NET avec NuGet :

dotnet add package Azure.Communication.Chat

Prérequis

Vous avez besoin d’un abonnement Azure et d’une ressource Communication Service pour utiliser ce package.

Pour créer un service communication, vous pouvez utiliser le portail Azure, le Azure PowerShell ou la bibliothèque de client de gestion .NET.

Authentifier le client

Jetons 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. Pour la génération de jetons d’accès utilisateur, reportez-vous à Jetons d’accès utilisateur.

Utilisation d’instructions

using Azure.Communication.Identity;
using Azure.Communication.Chat;

Créer un ChatClient

Cela vous permet de créer, d’obtenir ou de supprimer des threads de conversation.

ChatClient chatClient = new ChatClient(
    endpoint,
    new CommunicationTokenCredential(userToken));

Créer un ChatThreadClient

ChatThreadClient vous permet d’effectuer des opérations spécifiques à un fil de conversation, telles que la mise à jour de la rubrique du fil de conversation, l’envoi d’un message, l’ajout de participants au fil de conversation, etc.

Vous pouvez instancier un nouveau ChatThreadClient à l’aide de l’opération GetChatThread de ChatClient avec un ID de thread existant :

ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(chatThread.Id);

Concepts clés

Une conversation de conversation est représentée par un thread. Chaque utilisateur du thread est appelé participant au thread. Les participants au thread peuvent discuter les uns avec les autres en privé dans une conversation 1:1 ou se blottir dans une conversation de groupe 1:N. Les utilisateurs obtiennent également des mises à jour en quasi-temps réel quand d’autres utilisateurs tapent et quand ils ont lu les messages.

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

Créer un thread

CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new ChatParticipant[] { });
ChatThreadProperties chatThread = createChatThreadResult.ChatThread;

Obtenir un thread

ChatThread chatThread = chatClient.GetChatThread(chatThread.Id);

Obtenir tous les threads pour l’utilisateur

Pageable<ChatThreadItem> threads = chatClient.GetChatThreads();

Supprimer un thread

chatClient.DeleteChatThread(chatThread.Id);

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

Mettre à jour un thread

chatThreadClient.UpdateTopic(topic: "Launch meeting");

Envoyer un message

SendChatMessageResult sendChatMessageResult = chatThreadClient.SendMessage("Let's meet at 11am");

Mettre à jour un message

chatThreadClient.UpdateMessage(sendChatMessageResult.Id, content: "Instead of 11am, let's meet at 2pm");

Obtenir un message

ChatMessage message = chatThreadClient.GetMessage(sendChatMessageResult.Id);

Supprimer un message

chatThreadClient.DeleteMessage(sendChatMessageResult.Id);

Obtenir des messages

Pageable<ChatMessage> messages = chatThreadClient.GetMessages();

Obtenir la liste des participants

Pageable<ChatParticipant> chatParticipants = chatThreadClient.GetParticipants();

Ajouter des participants

chatThreadClient.AddParticipants(participants: new[] { new ChatParticipant(participantIdentifier) });

Supprimer un participant

chatThreadClient.RemoveParticipant(identifier: participantIdentifier);

Envoyer une notification de saisie

chatThreadClient.SendTypingNotification();

Obtenir la liste des confirmations de lecture

Pageable<ChatMessageReadReceipt> readReceipts = chatThreadClient.GetReadReceipts();

Envoyer une confirmation de lecture

chatThreadClient.SendReadReceipt(sendChatMessageResult.Id);

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont thread-safe et indépendantes les unes des autres (instructions). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options | du clientAccès à la réponse | Opérations | de longue duréeGestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

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

Opérations de thread

Créer un thread

Utilisez CreateChatThread pour créer un objet client de thread de conversation.

  • Utilisez topic pour donner une rubrique de thread.
  • Les attributs pris en charge pour chaque participant au thread sont les suivants :
    • communicationUser, obligatoire, il s’agit de l’identification du participant au thread.
    • displayName, facultatif, est le nom complet du participant au thread
    • shareHistoryTime, facultatif. Il s’agit du moment à partir duquel l’historique de conversation est partagé avec le participant.

ChatThreadClient est le résultat retourné par la création d’un thread, vous pouvez l’utiliser pour effectuer d’autres opérations sur le thread de conversation.

ChatClient chatClient = new ChatClient(
    endpoint,
    new CommunicationTokenCredential(userToken));

var chatParticipant = new ChatParticipant(identifier: kimberly)
{
    DisplayName = "Kim"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
string threadId = createChatThreadResult.ChatThread.Id;
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId);

Obtenir un thread

Utilisez GetChatThread pour récupérer un thread de conversation à partir du service. threadId est l’ID unique du thread.

ChatThreadProperties chatThread = await chatThreadClient.GetPropertiesAsync();

Obtenir des threads (pour un participant)

Utilisez GetChatThreads pour obtenir la liste des threads de conversation pour le participant qui a instancié le chatClient.

AsyncPageable<ChatThreadItem> chatThreadItems = chatClient.GetChatThreadsAsync();
await foreach (ChatThreadItem chatThreadItem in chatThreadItems)
{
    Console.WriteLine($"{ chatThreadItem.Id}");
}

Supprimer un thread

Utilisez DeleteChatThread pour supprimer un thread. threadId est l’ID unique du thread.

await chatClient.DeleteChatThreadAsync(threadId);

Mettre à jour un thread

Utilisez UpdateTopic pour mettre à jour la rubrique du fil de conversation.

  • topic est utilisé pour décrire la rubrique mise à jour pour le thread.
await chatThreadClient.UpdateTopicAsync(topic: "new topic !");

Opérations de message

Envoyer un message

Utilisez SendMessage pour envoyer un message à un fil de conversation.

  • Utilisez content pour fournir le contenu du message (obligatoire).
  • Utilisez type pour le type de contenu du message tel que « Text » ou « Html ». S’il n’est pas indiqué, « Text » est défini.
  • Utilisez senderDisplayName pour spécifier le nom d’affichage de l’expéditeur. S’il n’est pas spécifié, une chaîne vide est définie.
SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(content:"hello world");
var messageId = sendChatMessageResult.Id;

Obtenir un message

Utilisez GetMessage pour récupérer un message à partir du service. messageId est l’ID unique du message.

ChatMessage est la réponse retournée par l’obtention d’un message, elle contient un ID, qui est l’identificateur unique du message, entre autres champs. Reportez-vous à Azure.Communication.Chat.ChatMessage

ChatMessage chatMessage = await chatThreadClient.GetMessageAsync(messageId);

Obtenir des messages

Utilisez GetMessages pour récupérer tous les messages du fil de conversation.

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

Mettre à jour un message

Utilisez UpdateMessage pour mettre à jour un message.

  • messageId est l’identificateur unique du message.
  • content est le contenu du message à mettre à jour.
await chatThreadClient.UpdateMessageAsync(messageId, "updated message content");

Supprimer un message

Utilisez DeleteMessage pour supprimer un message.

  • messageId est l’identificateur unique du message.
await chatThreadClient.DeleteMessageAsync(messageId);

Opérations des participants de thread

Obtenir les participants au fil de conversation

Utilisez GetParticipants pour récupérer les participants au fil de conversation.

AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
    Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}

Ajouter des participants au thread

Utilisez AddParticipants pour ajouter un ou plusieurs participants au fil de conversation. Voici les attributs pris en charge pour chaque participant au fil de conversation :

  • communicationUser, obligatoire, il s’agit de l’identification du participant au thread.
  • displayName, facultatif, est le nom d’affichage pour le participant au fil.
  • shareHistoryTime, facultatif. Il s’agit du moment à partir duquel l’historique de conversation est partagé avec le participant.
var participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants);

Supprimer le participant au thread

Utilisez RemoveParticipant pour supprimer un participant de thread du thread. communicationUser est l’identification du participant à la conversation.

await chatThreadClient.RemoveParticipantAsync(gloria);

Opérations d’événements

Envoyer une notification de saisie

Utilisez SendTypingNotification pour indiquer que l’utilisateur est en train de taper une réponse dans le fil de conversation.

await chatThreadClient.SendTypingNotificationAsync();

Envoyer une confirmation de lecture

Utilisez SendReadReceipt pour informer les autres participants que le message est lu par l’utilisateur.

await chatThreadClient.SendReadReceiptAsync(messageId);

Obtenir des confirmations de lecture

Utilisez GetReadReceipts pour vérifier l’état des messages et déterminer ceux qui sont lus par d’autres participants d’un fil de conversation.

AsyncPageable<ChatMessageReadReceipt> allReadReceipts = chatThreadClient.GetReadReceiptsAsync();
await foreach (ChatMessageReadReceipt readReceipt in allReadReceipts)
{
    Console.WriteLine($"{readReceipt.ChatMessageId}:{((CommunicationUserIdentifier)readReceipt.Sender).Id}:{readReceipt.ReadOn}");
}

Résolution des problèmes

Réponses du service

Un RequestFailedException est levée en tant que réponse de service pour toutes les demandes ayant échoué. L’exception contient des informations sur le code de réponse retourné par le service.

try
{
    CreateChatThreadResult createChatThreadErrorResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { josh });
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.Message);
}

Étapes suivantes

En savoir plus sur Conversation dans Azure Communication Services

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

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.