适用于 Java 的 Azure WebPubSub 客户端库

客户端 SDK 旨在加快开发人员的工作流；更具体地说，即：

• 简化客户端连接的管理
• 简化在客户端之间发送消息
• 在意外删除客户端连接后自动重试
• 从连接断开恢复后，按数量和顺序可靠地传递消息

如图所示，客户端与 Web PubSub 资源建立 WebSocket 连接。

• Java 开发工具包 (JDK) 版本 8 或更高版本
• Azure 订阅
• 现有 Web PubSub 实例

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub-client</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

客户端使用 Client Access URL 以连接服务并对其进行身份验证。 此 URL 遵循 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token> 的模式。 有多种方法可以获取 Client Access URL。 作为快速入门，可以从 Azure 门户复制和粘贴，而对于生产环境，通常需要协商服务器来生成 URL。 查看详细信息。

作为快速入门，可以转到 Azure 门户并从“密钥”边栏选项卡复制“客户端访问 URL”。

如图所示，向客户端授予向特定组发送消息和加入特定组的权限。 请参阅权限，详细了解客户端权限。

WebPubSubClient client = new WebPubSubClientBuilder()
    .clientAccessUrl("<client-access-url>")
    .buildClient();

在生产环境下，客户端通常从协商服务器提取 Client Access URL。 服务器存放 connection string 并通过 WebPubSubServiceClient 生成 Client Access URL。 作为示例，代码片段只是演示如何在单个进程中生成 Client Access URL。

本文中出现的原始连接字符串仅用于演示目的。 在生产环境中，请始终保护访问密钥。 使用 Azure Key Vault 安全地管理和轮换密钥，并使用 WebPubSubServiceClient 对连接进行保护。

// WebPubSubServiceAsyncClient is from com.azure:azure-messaging-webpubsub
// create WebPubSub service client
WebPubSubServiceAsyncClient serverClient = new WebPubSubServiceClientBuilder()
    .connectionString("<connection-string>")
    .hub("<hub>>")
    .buildAsyncClient();

// wrap WebPubSubServiceAsyncClient.getClientAccessToken as WebPubSubClientCredential
WebPubSubClientCredential clientCredential = new WebPubSubClientCredential(Mono.defer(() ->
    serverClient.getClientAccessToken(new GetClientAccessTokenOptions()
            .setUserId("<user-name>")
            .addRole("webpubsub.joinLeaveGroup")
            .addRole("webpubsub.sendToGroup"))
        .map(WebPubSubClientAccessToken::getUrl)));

// create WebPubSub client
WebPubSubClient client = new WebPubSubClientBuilder()
    .credential(clientCredential)
    .buildClient();

区分 WebPubSubClient 和 WebPubSubServiceClient 的功能。

客户端可以添加回调以使用来自服务器和组的消息。 请注意，客户端只能接收已加入的组消息。

client.addOnGroupMessageEventHandler(event -> {
    System.out.println("Received group message from " + event.getFromUserId() + ": "
        + event.getData().toString());
});
client.addOnServerMessageEventHandler(event -> {
    System.out.println("Received server message: "
        + event.getData().toString());
});

当客户端连接连接到服务时，将触发 connected 事件。

当客户端连接断开且无法恢复连接时，将触发 disconnected 事件。

当客户端停止（这意味着客户端连接断开且客户端停止尝试重新连接）时，将触发 stopped 事件。 这通常在调用 client.StopAsync() 或禁用 AutoReconnect 后发生。 如果要重启客户端，可以在事件 Stopped 中调用 client.StartAsync()。

client.addOnConnectedEventHandler(event -> {
    System.out.println("Connection is connected: " + event.getConnectionId());
});
client.addOnDisconnectedEventHandler(event -> {
    System.out.println("Connection is disconnected");
});
client.addOnStoppedEventHandler(event -> {
    System.out.println("Client is stopped");
});

默认情况下，操作（如 client.joinGroup()、client.leaveGroup()、client.sendToGroup()、client.sendEvent()）有三次重试机会。 可以使用 WebPubSubClientBuilder.retryOptions() 进行更改。 如果所有重试都失败，则会引发错误。 可以通过传入与之前的重试相同的 ackId 来继续重试，以便服务可以帮助删除相同 ackId 的重复操作。

try {
    client.joinGroup("testGroup");
} catch (SendMessageFailedException e) {
    if (e.getAckId() != null) {
        client.joinGroup("testGroup", e.getAckId());
    }
}

使用此库时，可设置以下环境变量来获取调试日志。

export AZURE_LOG_LEVEL=verbose

有关如何启用日志的更详细说明，请查看 @azure/logger 包文档。

使用来自 Azure 门户的实时跟踪工具来检查通过 Web PubSub 资源的实时消息流量。