你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
适用于 Java 的 Azure Web PubSub 服务客户端库 - 版本 1.2.9
Azure Web PubSub 服务是一项 Azure 托管服务，可帮助开发者轻松构建具有实时功能和发布-订阅模式的 Web 应用程序。 任何需要在服务器和客户端或客户端之间进行实时发布-订阅消息传送的方案都可以使用 Azure Web PubSub 服务。 通常需要从服务器轮询或提交 HTTP 请求的传统实时功能也可以使用 Azure Web PubSub 服务。
可以在应用服务器端使用此库来管理 WebSocket 客户端连接，如下图所示：
可以使用此库来执行以下操作：
- 将消息发送到中心和组。
- 将消息发送到特定用户和连接。
- 将用户和连接组织到组中。
- 关闭连接
- 授予、撤销、检查现有连接的权限
有关此处使用的术语的详细信息，请参阅主要概念部分。
入门
先决条件
- Java 开发工具包 (JDK) 8 或更高版本。
- Azure 订阅
添加包
包括 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-messaging-webpubsub</artifactId>
</dependency>
</dependencies>
包括直接依赖项
如果要依赖于 BOM 中不存在的特定库版本，请将直接依赖项添加到项目，如下所示。
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-messaging-webpubsub</artifactId>
<version>1.2.9</version>
</dependency>
使用连接字符串创建 WebPubSubServiceClient
WebPubSubServiceClient webPubSubServiceClient = new WebPubSubServiceClientBuilder()
.connectionString("{connection-string}")
.hub("chat")
.buildClient();
使用访问密钥创建 WebPubSubServiceClient
WebPubSubServiceClient webPubSubServiceClient = new WebPubSubServiceClientBuilder()
.credential(new AzureKeyCredential("{access-key}"))
.endpoint("<Insert endpoint from Azure Portal>")
.hub("chat")
.buildClient();
关键概念
连接
连接（也称为客户端或客户端连接）表示连接到 Web PubSub 服务的单个 WebSocket 连接。 成功连接后，Web PubSub 服务会向此连接分配唯一的连接 ID。
集线器
中心是客户端连接集的逻辑概念。 通常将一个中心用于一种用途，例如聊天中心或通知中心 。 创建客户端连接后，它会连接到某个中心，并且在其生存期内属于该中心。 不同的应用程序可以使用不同的中心名称共享一个 Azure Web PubSub 服务。
组
组是与中心的连接的子集。 可以随时向组添加客户端连接或者从组中删除客户端连接。 例如，当某个客户端加入聊天室，或某个客户端离开聊天室，此类聊天室可以看成是一个组。 一个客户端可以加入多个组，一个组可以包含多个客户端。
用户
与 Web PubSub 的连接可以属于一个用户。 用户可能具有多个连接，例如当单个用户跨多个设备或多个浏览器选项卡进行连接时。
Message
客户端连接后，可以通过 WebSocket 连接将消息发送到上游应用程序或是从上游应用程序接收消息。
示例
将消息广播到整个中心
webPubSubServiceClient.sendToAll("Hello world!", WebPubSubContentType.TEXT_PLAIN);
使用筛选器将消息广播到整个中心
// send a text message to the entire hub with a filter on userId
BinaryData message = BinaryData.fromString("Hello World - Broadcast test!");
webPubSubServiceClient.sendToAllWithResponse(
message,
WebPubSubContentType.TEXT_PLAIN,
message.getLength(),
new RequestOptions().addQueryParam("filter", "userId ne 'user1'"));
// send a text message to the entire hub with another filter on group
webPubSubServiceClient.sendToAllWithResponse(
message,
WebPubSubContentType.TEXT_PLAIN,
message.getLength(),
new RequestOptions().addQueryParam("filter", "'GroupA' in groups and not('GroupB' in groups)"));
将消息广播到组
webPubSubServiceClient.sendToGroup("java", "Hello Java!", WebPubSubContentType.TEXT_PLAIN);
将消息发送到连接
webPubSubServiceClient.sendToConnection("myconnectionid", "Hello connection!", WebPubSubContentType.TEXT_PLAIN);
向用户发送消息
webPubSubServiceClient.sendToUser("Andy", "Hello Andy!", WebPubSubContentType.TEXT_PLAIN);
故障排除
启用客户端日志记录
可以设置 AZURE_LOG_LEVEL 环境变量，以便查看在客户端库中生成的日志记录语句。 例如，设置 AZURE_LOG_LEVEL=2 会显示所有信息性消息、警告消息和错误日志消息。 日志级别可在此处找到：日志级别。
默认的 HTTP 客户端
默认情况下，所有客户端库都使用 Netty HTTP 客户端。 添加上述依赖项会自动将客户端库配置为使用 Netty HTTP 客户端。 HTTP 客户端 Wiki 中详述了如何配置或更改 HTTP 客户端。
默认 SSL 库
默认情况下，所有客户端库均使用 Tomcat 原生 Boring SSL 库来为 SSL 操作启用原生级别性能。 Boring SSL 库是一个 uber jar，其中包含适用于 Linux/macOS/Windows 的原生库。与 JDK 内的默认 SSL 实现相比，它提供更好的性能。 有关详细信息（包括如何减小依赖项大小），请参阅 Wiki 的性能优化部分。
后续步骤
- 此处详细介绍了示例。
贡献
本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。
提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。
此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。
