适用于 Java 的 Azure WebPubSub 客户端库

注意

有关此处使用的术语的详细信息，请参阅主要概念一文。

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

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

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

显示客户端与 Web PubSub 资源建立 WebSocket 连接的屏幕截图

重要

本文中出现的原始连接字符串仅用于演示目的。

连接字符串包含应用程序访问 Azure Web PubSub 服务所需的授权信息。连接字符串中的访问密钥就像你服务的根密码一样。在生产环境中，请始终保护访问密钥。使用Azure 密钥保管库安全地管理和轮换密钥，并保护与WebPubSubServiceClient连接的安全。

避免将访问密钥分发给其他用户、对其进行硬编码或将其以纯文本形式保存在其他人可以访问的任何位置。如果你认为访问密钥可能已泄露，请轮换密钥。

入门

先决条件

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.cn/client/hubs/<hub_name>?access_token=<token> 的模式。有多种方法可以获取 Client Access URL。作为快速入门，可以从 Azure 门户复制和粘贴，而对于生产环境，通常需要协商服务器来生成 URL。查看详细信息。

使用 Azure 门户中的 `Client Access URL`

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

显示如何在 Azure 门户上获取客户端访问网址的屏幕截图

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

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

使用协商服务器生成 `Client Access URL`

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

本文中出现的原始连接字符串仅用于演示目的。在生产环境中，请始终保护访问密钥。使用 Azure 密钥保管库安全地管理和轮换密钥，并使用 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 的功能。

类名	WebPubSubClient	WebPubSubServiceClient
包名称	azure-messaging-webpubsub-client	azure-messaging-webpubsub
功能	在客户端使用。发布消息并订阅消息。	在服务器端使用。生成 `Client Access URL` 和管理客户端。

示例

使用来自服务器和组的消息

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

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` 事件添加回调

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

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

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

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 资源的实时消息流量。

Last updated on 2026-09-18