Java 用 Azure Communication Chat クライアント ライブラリ - バージョン 1.3.13

  • [アーティクル]

Azure Communication Chat には、Azure Communication Servicesのチャット アプリケーションで使用される API が含まれています。

ソースコード | パッケージ (Maven) | API リファレンス ドキュメント | 製品ドキュメント

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

ライブラリの一般提供 (GA) バージョンに依存するには、azure-sdk-bom をプロジェクトに含めてください。 次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

<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>

次に、バージョン タグのない依存関係セクションに直接依存関係を含めます。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
  </dependency>
</dependencies>

直接依存関係を含める

BOM に存在しないライブラリの特定のバージョンに依存する場合は、次のように直接依存関係をプロジェクトに追加します。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
    <version>1.3.13</version>
</dependency>

主要な概念

チャット会話は、チャット スレッドによって表されます。 チャット スレッド内の各ユーザーは、参加者と呼ばれます。 参加者は、1 対 1 のチャットで個人的にチャットしたり、1:N グループ チャットに参加したりできます。

クラスと クラスをChatClientChatThreadClient初期化したら、次のチャット操作を実行できます。

チャット スレッドの作成、取得、一覧表示、更新、削除

チャット メッセージの送信、取得、一覧表示、更新、削除

参加者の取得、追加、削除

開封確認メッセージを送信して取得する

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

Azure Communication Resource エンドポイントの作成後に設定する

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

ユーザー アクセス トークンを要求する

ユーザーのアクセス トークンを使用することで、Azure Communication Services に対して直接認証を行うクライアント アプリケーションを作成できます。 サーバーでこれらのトークンを生成し、クライアント デバイスに渡してから、それらを使用して Communication Services SDK を初期化します。

ユーザー アクセス トークンからユーザー アクセス トークンを生成する方法について説明します

例

次のセクションでは、次のような最も一般的なタスクをカバーするいくつかのコード スニペットを示します。

チャット クライアントを作成する

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

チャット スレッド操作

チャット スレッドの作成

チャット クライアントを作成するには、Communications Service エンドポイントと、前提条件の手順の一部として生成されたアクセス トークンを使用します。 ユーザーのアクセス トークンを使用することで、Azure Communication Services に対して直接認証を行うクライアント アプリケーションを作成できます。 サーバーでこれらのトークンを生成した後、それらをクライアント デバイスに渡します。 チャット クライアントにトークンを渡すには、Common SDK の CommunicationTokenCredential クラスを使用する必要があります。

チャット スレッドは、createChatThread メソッドを使用して作成します。 createChatThreadOptions はスレッド要求を記述するために使用されます。例を次のコード スニペットに示します。

  • を使用して topic スレッド トピックを指定します。
  • を使用して participants 、スレッドに追加するスレッドの参加者を一覧表示します。

CreateChatThreadResult は、チャット スレッドの作成から返された応答です。 これには、スレッド クライアントを取得するために使用できる ChatThread オブジェクトを返す getChatThread() メソッドが含まれています。そのスレッド クライアントからは、作成されたスレッドに対して参加者の追加、メッセージの送信などを含む操作を実行するための ChatThreadClient を取得できます。ChatThread オブジェクトには、スレッドの一意の ID を取得する getId() メソッドも含まれています。

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

チャット スレッドのプロパティを取得する

メソッドは getChatThreadProperties 、サービスからスレッドのプロパティを取得します。

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

スレッドを削除する

チャット スレッドchatThreadIdを削除するには、 メソッドを使用deleteChatThreadします。これは、チャット スレッドの一意の ID です。

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

チャット スレッド クライアントを取得する

getChatThreadClient メソッドは、既に存在するスレッドのスレッド クライアントを返します。 作成したスレッドに対し、参加者の追加、メッセージの送信などの操作を実行するときに使用できます。chatThreadId は、既存のチャット スレッドの一意の ID です。

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

チャット スレッド トピックを更新する

Use メソッドを使用して updateTopic スレッドのトピック topic を更新し、スレッドの新しいトピックを保持します。

chatThreadClient.updateTopic("New Topic");

チャット メッセージ操作

チャット メッセージを送信する

メソッドを sendMessage 使用して、 が作成されたチャット スレッドにチャット メッセージを chatThreadClient 送信します。 sendChatMessageOptions はチャット メッセージ要求を記述するために使用されます。例を次のコード スニペットに示します。

  • チャット メッセージの内容は、content を使用して設定します。
  • [通常] や [高] などのチャット メッセージの優先度レベルを指定するには、 を使用 priority します。
  • 送信者の表示名を指定するには、senderDisplayName を使用します。

チャット メッセージの SendChatMessageResult 送信から返された応答には、メッセージの一意の ID である ID が含まれています。

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

SendChatMessageResult sendResult = chatThreadClient.sendMessage(sendChatMessageOptions);

チャット メッセージを取得する

メソッドは getMessage 、サービスからチャット メッセージを取得します。 chatMessageId はチャット メッセージの一意の ID です。

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

チャット メッセージを取得する

チャット メッセージは、チャット スレッド クライアントの メソッドを listMessages 使用して、指定した間隔 (ポーリング) で取得できます。

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 は、メッセージに対して .editMessage() や .deleteMessage() を使用して行われた編集や削除を含む、最新バージョンのメッセージを返します。

削除されたメッセージについては、そのメッセージがいつ削除されたかを示す datetime 値が chatMessage.getDeletedOn() から返されます。

編集されたメッセージについては、メッセージがいつ編集されたかを示す datetime が chatMessage.getEditedOn() から返されます。

メッセージの最初の作成日時には、chatMessage.getCreatedOn() を使用してアクセスできます。これをメッセージの並べ替えに使用することができます。

listMessages は、 で chatMessage.getType()識別できるさまざまな種類のメッセージを返します。 次の種類があります。

  • text:スレッド参加者によって送信された通常のチャット メッセージ。

  • html: スレッド参加者によって送信された HTML チャット メッセージ。

  • topicUpdated:トピックが更新されたことを示すシステム メッセージ。

  • participantAdded:1 人以上の参加者がチャット スレッドに追加されたことを示すシステム メッセージ。

  • participantRemoved:参加者がチャット スレッドから削除されたことを示すシステム メッセージ。

詳細については、「メッセージの種類」を参照してください。

チャット メッセージを更新する

chatThreadId と messageId で識別されるチャット メッセージを更新するために使用 updateMessage します。 chatMessageId はチャット メッセージの一意の ID です。 updateChatMessageOptions はチャット メッセージの更新の要求を記述するために使用されます。例を次のコード スニペットに示します。

  • を使用して content 、新しいチャット メッセージ コンテンツを提供します。
String chatMessageId = "Id";
UpdateChatMessageOptions updateChatMessageOptions = new UpdateChatMessageOptions()
    .setContent("Updated message content");

chatThreadClient.updateMessage(chatMessageId, updateChatMessageOptions);

チャット メッセージを削除する

chatMessageId で識別されるチャット メッセージを更新するには、 を使用 updateMessage します。 chatMessageId はチャット メッセージの一意の ID です。

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

チャット スレッド参加者の操作

チャット参加者を一覧表示する

チャット スレッドの参加者を含むページ コレクションを取得するには、 を使用 listParticipants します。

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

参加者を追加する

メソッドを使用して addParticipants 、参加者をチャット スレッドに追加します。 participants スレッドに追加する参加者のリスト。

  • communicationIdentifierは、CommunicationIdentityClient を使用して作成した CommunicationIdentifier です。 詳細情報: ユーザーの作成。
  • display_name (省略可) は、スレッド メンバーの表示名です。
  • share_history_time (省略可) は、メンバーとの間でチャット履歴が共有される際の起点となる時刻です。 チャット スレッドの始めから履歴を共有する場合は、スレッドの作成日時と同じかそれ以前の任意の日付にこのプロパティを設定してください。 メンバーが追加された時点よりも前の履歴は共有しない場合は、現在の日付に設定します。 部分的に履歴を共有するには、必要な日付に設定します。
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);

参加者を削除する

メソッドを使用して removeParticipant 、チャット スレッドから参加者を削除します。 identifier は、作成した CommunicationIdentifier です。

chatThreadClient.removeParticipant(user);

開封確認操作

開封確認メッセージを送信する

メソッドを使用して sendReadReceipt 、ユーザーの代わりに開封確認イベントをチャット スレッドに投稿します。 `messageId` は、開封されたチャット メッセージの一意の ID です。

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

開封確認メッセージを取得する

getReadReceipts メソッドは、チャット スレッドの開封確認メッセージを取得します。

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

通知操作の入力

入力通知を送信する

ユーザーの代わりに、入力通知イベントをチャット スレッドに投稿するには、 メソッドを使用 sendTypingNotification します。 typingNotificationOptions は、入力通知要求を記述するために使用されます。

  • 通知送信者の表示名を設定するには、 を使用 senderDisplayName します。
TypingNotificationOptions options = new TypingNotificationOptions();
options.setSenderDisplayName("Sender Display Name");
chatThreadClient.sendTypingNotificationWithResponse(options, Context.NONE);

トラブルシューティング

進行中。

次の手順

Azure 通信サービス用の他のクライアント ライブラリを確認する