適用於 JAVA 的 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.com/client/hubs/<hub_name>?access_token=<token> 模式。 取得 Client Access URL 的方法有好幾種。 若要快速開始，您可以從 Azure 入口網站複製並貼上，而針對實際執行環境，您通常需要交涉伺服器來產生 URL。 查看詳細資料。

使用 Azure 入口網站的 Client Access URL

若要快速開始，您可以前往 Azure 入口網站，並從 [金鑰]刀鋒視窗複製[用戶端存取 URL]。

顯示如何在 Azure 入口網站 上取得用戶端存取 URL 的螢幕快照

如圖所示，用戶端已獲授與將訊息傳送至特定群組並加入特定群組的權限。 深入了解用戶端權限，請參閱權限。

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

使用交涉伺服器產生 Client Access URL

在實際執行環境中，用戶端通常會從交涉伺服器擷取 Client Access URL。 伺服器會保存 connection string，並透過 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 入口網站使用 Live Trace 工具，透過 Web PubSub 資源檢查即時訊息流量。

  • Last updated on