.NET 用 Azure Communication Chat クライアント ライブラリ - バージョン 1.1.2
このパッケージには、チャット用のAzure Communication Services用の C# SDK が含まれています。
ソースコード | パッケージ (NuGet) | 製品ドキュメント
作業の開始
パッケージをインストールする
NuGet を使用して .NET 用の Azure Communication Chat クライアント ライブラリをインストールします。
dotnet add package Azure.Communication.Chat
前提条件
このパッケージを使用するには、 Azure サブスクリプション と Communication Service リソース が必要です。
新しい Communication Service を作成するには、Azure Portal、Azure PowerShell、または .NET 管理クライアント ライブラリを使用できます。
クライアントを認証する
ユーザー アクセス トークン
ユーザーのアクセス トークンを使用することで、Azure Communication Services に対して直接認証を行うクライアント アプリケーションを作成できます。 ユーザー アクセス トークンの生成については、「 ユーザー アクセス トークン」を参照してください。
ステートメントの使用
using Azure.Communication.Identity;
using Azure.Communication.Chat;
ChatClient を作成する
これにより、チャット スレッドを作成、取得、または削除できます。
ChatClient chatClient = new ChatClient(
endpoint,
new CommunicationTokenCredential(userToken));
ChatThreadClient を作成する
ChatThreadClient を使用すると、チャット スレッド トピックの更新、メッセージの送信、チャット スレッドへの参加者の追加など、チャット スレッドに固有の操作を実行できます。
既存のスレッド ID を使用して ChatClient の GetChatThread 操作を使用して、新しい ChatThreadClient をインスタンス化できます。
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(chatThread.Id);
主要な概念
チャットの会話はスレッドによって表されます。 スレッド内の各ユーザーは、スレッド参加要素と呼ばれます。 スレッドの参加者は、1 対 1 のチャットで互いにプライベートにチャットしたり、1:N グループ チャットに参加したりできます。 また、ユーザーは、他のユーザーが入力しているときやメッセージを読んだときに、ほぼリアルタイムの更新を受け取ります。
クラスを ChatClient 初期化したら、次のチャット操作を実行できます。
スレッドを作成する
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new ChatParticipant[] { });
ChatThreadProperties chatThread = createChatThreadResult.ChatThread;
スレッドを取得する
ChatThread chatThread = chatClient.GetChatThread(chatThread.Id);
ユーザーのすべてのスレッドを取得する
Pageable<ChatThreadItem> threads = chatClient.GetChatThreads();
スレッドを削除する
chatClient.DeleteChatThread(chatThread.Id);
クラスを ChatThreadClient 初期化したら、次のチャット操作を実行できます。
スレッドを更新する
chatThreadClient.UpdateTopic(topic: "Launch meeting");
メッセージの送信
SendChatMessageResult sendChatMessageResult = chatThreadClient.SendMessage("Let's meet at 11am");
メッセージを更新する
chatThreadClient.UpdateMessage(sendChatMessageResult.Id, content: "Instead of 11am, let's meet at 2pm");
メッセージを取得する
ChatMessage message = chatThreadClient.GetMessage(sendChatMessageResult.Id);
メッセージを削除する
chatThreadClient.DeleteMessage(sendChatMessageResult.Id);
メッセージを取得する
Pageable<ChatMessage> messages = chatThreadClient.GetMessages();
参加者の一覧を取得する
Pageable<ChatParticipant> chatParticipants = chatThreadClient.GetParticipants();
参加者を追加する
chatThreadClient.AddParticipants(participants: new[] { new ChatParticipant(participantIdentifier) });
参加者の削除
chatThreadClient.RemoveParticipant(identifier: participantIdentifier);
入力通知を送信する
chatThreadClient.SendTypingNotification();
開封確認メッセージの一覧を取得する
Pageable<ChatMessageReadReceipt> readReceipts = chatThreadClient.GetReadReceipts();
開封確認メッセージを送信する
chatThreadClient.SendReadReceipt(sendChatMessageResult.Id);
スレッド セーフ
すべてのクライアント インスタンス メソッドがスレッド セーフであり、相互に独立していることを保証します (ガイドライン)。 これにより、スレッド間であっても、クライアント インスタンスの再利用に関する推奨事項が常に安全になります。
その他の概念
クライアント オプション | 応答 | へのアクセス実行時間の長い操作 | エラーの | 処理診断 | あざける | クライアントの有効期間
例
次のセクションでは、次のような最も一般的なタスクをカバーするいくつかのコード スニペットを示します。
スレッド操作
スレッドを作成する
を使用して CreateChatThread 、チャット スレッド クライアント オブジェクトを作成します。
- スレッド トピックを指定するには、 を使用
topicします。 - 各スレッド参加要素でサポートされている属性を次に示します。
communicationUserは必須です。これはスレッド参加者の ID です。displayName(省略可能) は、スレッド参加要素の表示名です`shareHistoryTime` (省略可) は、参加者との間でチャット履歴が共有される際の起点となる時刻です。
ChatThreadClient はスレッドの作成から返される結果です。これを使用して、チャット スレッドに対して他の操作を実行できます。
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);
スレッドを取得する
を使用して GetChatThread 、サービスからチャット スレッドを取得します。
threadId はスレッドの一意の ID です。
ChatThreadProperties chatThread = await chatThreadClient.GetPropertiesAsync();
スレッドを取得する (参加者の場合)
chatClient をインスタンス化した参加者のチャット スレッドの一覧を取得するには、 を使用 GetChatThreads します。
AsyncPageable<ChatThreadItem> chatThreadItems = chatClient.GetChatThreadsAsync();
await foreach (ChatThreadItem chatThreadItem in chatThreadItems)
{
Console.WriteLine($"{ chatThreadItem.Id}");
}
スレッドを削除する
スレッドを削除するには、 を使用 DeleteChatThread します。
threadId はスレッドの一意の ID です。
await chatClient.DeleteChatThreadAsync(threadId);
スレッドを更新する
を使用して UpdateTopic 、チャット スレッド トピックを更新します。
topicは、スレッドの更新されたトピックを記述するために使用されます。
await chatThreadClient.UpdateTopicAsync(topic: "new topic !");
メッセージ操作
メッセージの送信
スレッドにメッセージを送信するには、SendMessage を使用します。
- メッセージのコンテンツは、
contentを使用して設定します (必須)。 - "Text" や "Html" などのメッセージのコンテンツの種類には
typeを使用します。 指定しない場合は、'Text' が設定されます。 - 送信者の表示名を指定するには、
senderDisplayNameを使用します。 指定しない場合は、空の文字列が設定されます。
SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(content:"hello world");
var messageId = sendChatMessageResult.Id;
メッセージを取得する
サービスからメッセージを取得するには、GetMessage を使用します。
messageId はメッセージの一意の ID です。
ChatMessage はメッセージの取得から返される応答であり、他のフィールドの中でメッセージの一意識別子である ID が含まれています。 Azure.Communication.Chat.ChatMessage を参照してください
ChatMessage chatMessage = await chatThreadClient.GetMessageAsync(messageId);
メッセージを取得する
を使用して GetMessages 、チャット スレッドのすべてのメッセージを取得します。
AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
Console.WriteLine($"{message.Id}:{message.Content.Message}");
}
メッセージを更新する
メッセージを更新するには、 を使用 UpdateMessage します。
messageIdはメッセージの一意識別子です。contentは、更新するメッセージの内容です。
await chatThreadClient.UpdateMessageAsync(messageId, "updated message content");
メッセージを削除する
メッセージを削除するには、 を使用 DeleteMessage します。
messageIdはメッセージの一意識別子です。
await chatThreadClient.DeleteMessageAsync(messageId);
スレッド参加者操作
スレッド参加者を取得する
チャット スレッドの参加者を取得するには、GetParticipants を使用します。
AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}
スレッド参加者を追加する
チャット スレッドに 1 人以上の参加者を追加するには、AddParticipants を使用します。 各スレッド参加者でサポートされている属性は次のとおりです。
communicationUserは必須です。これはスレッド参加者の ID です。displayName(省略可) は、スレッド参加者の表示名です。`shareHistoryTime` (省略可) は、参加者との間でチャット履歴が共有される際の起点となる時刻です。
var participants = new[]
{
new ChatParticipant(josh) { DisplayName = "Josh" },
new ChatParticipant(gloria) { DisplayName = "Gloria" },
new ChatParticipant(amy) { DisplayName = "Amy" }
};
await chatThreadClient.AddParticipantsAsync(participants);
スレッド参加者を削除する
スレッドからスレッド参加者を削除するには、 を使用 RemoveParticipant します。
communicationUser はチャット参加者の識別です。
await chatThreadClient.RemoveParticipantAsync(gloria);
イベント操作
入力通知を送信する
ユーザーがスレッドに応答を入力していることを示すには、SendTypingNotification を使用します。
await chatThreadClient.SendTypingNotificationAsync();
開封確認メッセージを送信する
メッセージがユーザーに読まれたことを他の参加者に通知するには、SendReadReceipt を使用します。
await chatThreadClient.SendReadReceiptAsync(messageId);
開封確認メッセージを取得する
メッセージの状態をチェックして、チャット スレッドの他の参加者に読まれたメッセージを確認するには、GetReadReceipts を使用します。
AsyncPageable<ChatMessageReadReceipt> allReadReceipts = chatThreadClient.GetReadReceiptsAsync();
await foreach (ChatMessageReadReceipt readReceipt in allReadReceipts)
{
Console.WriteLine($"{readReceipt.ChatMessageId}:{((CommunicationUserIdentifier)readReceipt.Sender).Id}:{readReceipt.ReadOn}");
}
トラブルシューティング
サービス応答
RequestFailedExceptionは、失敗した要求に対するサービス応答としてスローされます。 例外には、サービスから返された応答コードに関する情報が含まれています。
try
{
CreateChatThreadResult createChatThreadErrorResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { josh });
}
catch (RequestFailedException ex)
{
Console.WriteLine(ex.Message);
}
次のステップ
詳細については、Azure Communication Servicesでのチャットに関するページを参照してください
共同作成
このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、「 cla.microsoft.com」を参照してください。
このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。