Java 用 Azure WebPubSub クライアントライブラリ

2024-12-13

Note

ここで使われている用語の詳細は、主な概念の記事を参照してください。

クライアント側 SDK は、開発者のワークフローを高速化することを目的としています。具体的には、次のとおりです。

クライアント接続の管理を簡素化します
クライアント間でのメッセージの送信を簡素化します
クライアント接続の意図しない切断後に自動的に再試行します
接続の切断からの復旧後に、数と順序を確実にしてメッセージを配信します

図に示すように、クライアントは Web PubSub リソースとの WebSocket 接続を確立します。

Web PubSub リソースとの WebSocket 接続を確立しているクライアントを示すスクリーンショット

重要

この記事に示す生の接続文字列は、デモンストレーションのみを目的としています。

接続文字列には、アプリケーションが Azure Web PubSub サービスにアクセスするために必要な認可情報が含まれています。接続文字列内のアクセスキーは、サービスのルートパスワードに似ています。運用環境では、常にアクセスキーを保護してください。 Azure Key Vault を使ってキーの管理とローテーションを安全に行い、WebPubSubServiceClient を使って接続をセキュリティ保護します。

アクセスキーを他のユーザーに配布したり、ハードコーディングしたり、他のユーザーがアクセスできるプレーンテキストで保存したりしないでください。キーが侵害された可能性があると思われる場合は、キーをローテーションしてください。

概要

前提条件

Java Development Kit (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 portal からコピーして貼り付けることができます。運用環境では、通常、URL を生成するためのネゴシエーションサーバーが必要です。詳細をご覧ください。

Azure portal から `Client Access URL` を使います

クイックスタートとして、Azure portal に移動し、[キー] ブレードからクライアントアクセス URL をコピーできます。

Azure portal でクライアントアクセス URL を取得する方法を示すスクリーンショット

図に示すように、クライアントには、特定のグループにメッセージを送信し、特定のグループに参加する権限が付与されます。クライアントの権限の詳細については、「権限」を参照してください。

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

ネゴシエーションサーバーを使用して `Client Access URL` を生成する

運用環境では、通常、クライアントはネゴシエーションサーバーから Client Access URL を取り込みます。サーバーは connection string を保持し、WebPubSubServiceClient から Client Access URL を生成します。サンプルとして、次のコードスニペットは、1 つのプロセスで 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 を区別する機能。

クラス名	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 が無効になった後です。クライアントを再起動する場合は、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() などの操作では 3 回再試行できます。変更するには、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 portal からライブトレースツールを使用して、Web PubSub リソースを介してライブメッセージトラフィックを検査します。

次の方法で共有

Java 用 Azure WebPubSub クライアント ライブラリ

概要

前提条件

製品へのパッケージの追加

クライアントを認証する

Azure portal から Client Access URL を使います

ネゴシエーション サーバーを使用して Client Access URL を生成する

例

サーバーとグループからメッセージを取り込む

connected、disconnected、stopped イベントのコールバックを追加する