次の方法で共有

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

  • [アーティクル]

Note

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

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

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

図に示すように、クライアントは Web PubSub リソースとの WebSocket 接続を確立します。 Screenshot showing clients establishing WebSocket connection with a Web PubSub resource

作業の開始

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

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 をコピーできます。

Screenshot showing how to get Client Access Url on Azure portal

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

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

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

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

クラス名 WebPubSubClient WebPubSubServiceClient
NuGet パッケージ名 Azure.Messaging.WebPubSub.Client Azure.Messaging.WebPubSub
機能 クライアント側で使用されます。 メッセージを発行し、メッセージをサブスクライブします。 サーバー側で使用されます。 クライアント アクセス URI を生成し、クライアントを管理します

例

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

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

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 が無効になった後です。 クライアントを再起動する場合は、Stopped イベントで client.StartAsync() を呼び出すことができます。

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 回再試行できます。 変更するには、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 リソースを介してライブ メッセージ トラフィックを検査します。