.NET 用 Azure Web PubSub クライアント ライブラリ

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

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

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

作業の開始

パッケージをインストールする

NuGet からクライアント ライブラリをインストールします。

dotnet add package Azure.Messaging.WebPubSub.Client --prerelease

[前提条件]

• Azure サブスクリプション
• 既存の Web PubSub インスタンス

クライアントを認証する

クライアントは、 Client Access URL を使用してサービスに接続して認証します。 Client Access URL は、 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>としてパターンに従います。 Client Access URLを取得するには、複数の方法があります。 クイック スタートとして、Azure portal からコピーして貼り付けることができます。運用環境では、通常、 Client Access URLを生成するためのネゴシエーション サーバーが必要です。 詳細を参照してください。

Azure portal からクライアント アクセス URL を使用する

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

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

var client = new WebPubSubClient(new Uri("<client-access-uri>"));

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

運用環境では、通常、クライアントはネゴシエーション サーバーから Client Access URL をフェッチします。 サーバーはconnection stringを保持し、Client Access URLを介してWebPubSubServiceClientを生成します。 サンプルとして、コード スニペットでは、1 つのプロセス内で Client Access URL を生成する方法を示しています。

var client = new WebPubSubClient(new WebPubSubClientCredential(token =>
{
    // In common practice, you will have a negotiation server for generating token. Client should fetch token from it.
    return FetchClientAccessTokenFromServerAsync(token);
}));

public async ValueTask<Uri> FetchClientAccessTokenFromServerAsync(CancellationToken token)
{
    var serviceClient = new WebPubSubServiceClient("<< Connection String >>", "hub");
    return await serviceClient.GetClientAccessUriAsync();
}

WebPubSubClientとWebPubSubServiceClientを区別する機能。

例示

サーバーとグループからのメッセージを使用する

クライアントは、サーバーとグループからのメッセージを使用するコールバックを追加できます。 クライアントは、参加しているグループ メッセージのみを受信できることに注意してください。

client.ServerMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive message: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

client.GroupMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive group message from {eventArgs.Message.Group}: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

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

クライアント接続がサービスに接続されると、サービスから接続されたメッセージを受信すると、 connected イベントがトリガーされます。

client.Connected += eventArgs =>
{
    Console.WriteLine($"Connection {eventArgs.ConnectionId} is connected");
    return Task.CompletedTask;
};

クライアント接続が切断され、回復に失敗すると、 disconnected イベントがトリガーされます。

client.Disconnected += eventArgs =>
{
    Console.WriteLine($"Connection is disconnected");
    return Task.CompletedTask;
};

クライアントが停止すると(つまり、クライアント接続が切断され、クライアントが再接続を停止すると、 stopped イベントがトリガーされます。 これは通常、 client.StopAsync() が呼び出されるか、 AutoReconnect無効になった後に発生します。 クライアントを再起動する場合は、client.StartAsync() イベントでStoppedを呼び出すことができます。

client.Stopped += eventArgs =>
{
    Console.WriteLine($"Client is stopped");
    return Task.CompletedTask;
};

グループの自動再結合と再参加失敗の処理

クライアント接続が切断され、回復に失敗すると、すべてのグループ コンテキストがサービス側でクリーンアップされます。 つまり、クライアントが再接続するときは、グループに再び参加する必要があります。 既定では、クライアントはオプション AutoRejoinGroups 有効になっています。 ただし、この機能には制限があります。 クライアントは、クライアントによって最初に参加したグループにのみ再参加でき、サーバー側によって参加されたグループには再参加できません。 また、クライアントにグループに参加するアクセス許可がないなど、さまざまな理由により、グループの再参加操作が失敗する可能性があります。 このような場合、ユーザーはそのようなエラーを処理するためのコールバックを追加する必要があります。

client.RejoinGroupFailed += eventArgs =>
{
    Console.WriteLine($"Restore group failed");
    return Task.CompletedTask;
};

操作と再試行

既定では、 client.JoinGroupAsync()、 client.LeaveGroupAsync()、 client.SendToGroupAsync()、 client.SendEventAsync() などの操作には 3 つの reties があります。 WebPubSubClientOptions.MessageRetryOptionsを使用して変更できます。 すべての再試行が失敗した場合は、エラーがスローされます。 以前の再試行と同じ ackId を渡すことで再試行を続けることができるため、サービスは同じ ackIdで操作を重複除去するのに役立ちます。

// Send message to group "testGroup"
try
{
    await client.JoinGroupAsync("testGroup");
}
catch (SendMessageFailedException ex)
{
    if (ex.AckId != null)
    {
        await client.JoinGroupAsync("testGroup", ackId: ex.AckId);
    }
}

トラブルシューティング

ログを有効にする

このライブラリを使用する場合は、次の環境変数を設定してデバッグ ログを取得できます。

export AZURE_LOG_LEVEL=verbose

ログを有効にする方法の詳細な手順については、 @azure/logger パッケージのドキュメントを参照してください。

ライブ トレース

Azure portal の ライブ トレース ツール を使用して、Web PubSub リソース経由のライブ メッセージ トラフィックを検査します。