你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Java 的 Azure 通信聊天客户端库 - 版本 1.3.13

  • 项目

Azure 通信聊天包含聊天应用程序中用于Azure 通信服务的 API。

源代码 | 包 (Maven) | API 参考文档 | 产品文档

入门

先决条件

添加包

包括 BOM 文件

请将 azure-sdk-bom 包含在项目中，以依赖于库的正式发布 (GA) 版本。 在以下代码段中，将 {bom_version_to_target} 占位符替换为版本号。 若要详细了解 BOM，请参阅 AZURE SDK BOM 自述文件。

<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 群组聊天中挤在一起。

初始化 ChatClient 和 ChatThreadClient 类后，可以执行以下聊天操作：

创建、获取、列出、更新和删除聊天线程

发送、获取、列出、更新和删除聊天消息

获取、添加和删除参与者

发送和获取已读回执

贡献

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。

创建 Azure 通信资源终结点后设置它

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

请求用户访问令牌

使用用户访问令牌可以生成直接对 Azure 通信服务进行身份验证的客户端应用程序。 在服务器上生成这些令牌，将其传递回客户端设备，然后使用它们初始化通信服务 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();

聊天线程操作

创建聊天会话

若要创建聊天客户端，你将使用作为先决条件步骤的一部分生成的通信服务终结点和访问令牌。 使用用户访问令牌可以生成直接对 Azure 通信服务进行身份验证的客户端应用程序。 在服务器上生成这些令牌后，将它们传回客户端设备。 你需要使用 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();

删除线程

使用 deleteChatThread 删除聊天线程 chatThreadId 的方法是聊天线程的唯一 ID。

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

获取聊天会话客户端

getChatThreadClient 方法返回某个已存在的会话的会话客户端。 可使用该方法对创建的会话执行操作：添加参与者、发送消息等。chatThreadId 是现有聊天会话的唯一 ID。

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

更新聊天线程主题

使用 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() 对消息执行的任何编辑或删除。

对于已删除的消息，chatMessage.getDeletedOn() 返回日期/时间值，该值指示该消息删除的时间。

对于已编辑的消息，chatMessage.getEditedOn() 返回一个日期/时间值，指示编辑该消息的时间。

可以使用 chatMessage.getCreatedOn() 访问消息创建的原始时间，还可使用它对消息进行排序。

listMessages 返回不同类型的消息，这些消息可由 标识 chatMessage.getType()。 这些类型包括：

  • text：会话参与者发送的普通聊天消息。

  • html：会话参与者发送的 HTML 聊天消息。

  • topicUpdated：指示主题已更新的系统消息。

  • participantAdded：指示一个或多个参与者已添加到聊天会话的系统消息。

  • participantRemoved：指示已从聊天会话中删除参与者的系统消息。

有关详细信息，请参阅消息类型。

更新聊天消息

用于 updateMessage 更新由 chatThreadId 和 messageId 标识的聊天消息。 chatMessageId 是聊天消息的唯一 ID。 updateChatMessageOptions 用于描述聊天消息更新的请求，下面的代码片段中显示了一个示例。

  • 用于 content 提供新的聊天消息内容;
String chatMessageId = "Id";
UpdateChatMessageOptions updateChatMessageOptions = new UpdateChatMessageOptions()
    .setContent("Updated message content");

chatThreadClient.updateMessage(chatMessageId, updateChatMessageOptions);

删除聊天消息

用于 updateMessage 更新由 chatMessageId 标识的聊天消息。 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 方法代表用户将已读回执事件发布到聊天线程。 chatMessageId 是已读聊天消息的唯一 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);

疑难解答

In progress。

后续步骤

查看 Azure 通信服务的其他客户端库