.NET 用 Azure Web PubSub サービス クライアント ライブラリ - バージョン 1.3.0
Azure Web PubSub サービスは、開発者がリアルタイムの機能とパブリッシュ-サブスクライブ パターンを使って Web アプリケーションを簡単に作成できるようにするための Azure マネージド サービスです。 サーバーとクライアント間、またはクライアント間で、リアルタイムのパブリッシュ-サブスクライブ メッセージングを必要とするあらゆるシナリオに、Azure Web PubSub サービスを使用できます。 従来のリアルタイム機能は、多くの場合、サーバーからのポーリングや HTTP 要求の送信を必要としますが、そのようなリアルタイム機能にも Azure Web PubSub サービスを使用できます。
次の図に示すように、このライブラリをアプリ サーバー側で使用して、WebSocket クライアント接続を管理できます。
このライブラリは次のことに使うことができます。
- ハブとグループにメッセージを送信します。
- 特定のユーザーと接続にメッセージを送信します。
- ユーザーと接続をグループに整理します。
- 接続を終了します
- 既存の接続のアクセス許可を付与、取り消し、確認します
ここで使われている用語の詳細は、主な概念のセクションを参照してください。
ソース コード | パッケージ | API リファレンス ドキュメント | 製品ドキュメント | サンプル
作業の開始
パッケージをインストールする
NuGet からクライアント ライブラリをインストールします:
dotnet add package Azure.Messaging.WebPubSub
前提条件
- Azure サブスクリプション。
- 既存の Azure Web PubSub サービス インスタンス。
WebPubSubServiceClient
を作成して認証する
サービスと対話するには、WebPubSubServiceClient
クラスのインスタンスを作成する必要があります。 これを可能にするには、Microsoft Azure portal でアクセスできる接続文字列またはキーが必要です。
// Create a WebPubSubServiceClient that will authenticate using a key credential.
var serviceClient = new WebPubSubServiceClient(new Uri(endpoint), "some_hub", new AzureKeyCredential(key));
主要な概念
Connection
接続は、クライアントまたはクライアント接続とも呼ばれ、Web PubSub サービスに接続されている個々の WebSocket 接続を表します。 正常に接続されると、一意の接続 ID が Web PubSub サービスによってこの接続に割り当てられます。
ハブ
ハブは、一連のクライアント接続の論理的な概念です。 通常、"チャット" ハブや "通知" ハブなど、1 つの目的に 1 つのハブを使います。 クライアント接続は、作成されると 1 つのハブに接続され、その有効期間中はそのハブに属します。 異なるアプリケーションでは、異なるハブ名を使用して、1 つの Azure Web PubSub サービスを共有できます。
グループ
グループはハブへの接続のサブセットです。 必要な場合はいつでも、クライアント接続をグループに追加したり、グループからクライアント接続を削除したりできます。 たとえば、クライアントがチャット ルームに参加したり、クライアントがチャット ルームを離れたりするときに、このチャット ルームをグループと見なすことができます。 クライアントは複数のグループに参加できます。また、1 つのグループに複数のクライアントを含めることもできます。
User
Web PubSub への接続を 1 人のユーザーに属させることができます。 1 人のユーザーが複数のデバイスまたは複数のブラウザー タブに接続されている場合など、ユーザーが複数の接続を持つ場合があります。
Message
クライアントが接続されている場合は、WebSocket 接続を介して、アップストリーム アプリケーションにメッセージを送信したり、アップストリーム アプリケーションからメッセージを受信したりできます。
例
Azure Web PubSub を接続するときに使用する接続のアクセス トークンを含む完全な URI を生成する
// Generate client access URI for userA
serviceClient.GetClientAccessUri(userId: "userA");
// Generate client access URI with initial permissions
serviceClient.GetClientAccessUri(roles: new string[] { "webpubsub.joinLeaveGroup.group1", "webpubsub.sendToGroup.group1" });
// Generate client access URI with initial groups to join when the connection connects
serviceClient.GetClientAccessUri(groups: new string[] { "group1", "group2" });
接続にメッセージを送信する
すべてのクライアントにテキスト メッセージをブロードキャストする
var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");
serviceClient.SendToAll("Hello World!");
すべてのクライアントに JSON メッセージをブロードキャストする
var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");
serviceClient.SendToAll(RequestContent.Create(
new
{
Foo = "Hello World!",
Bar = 42
}),
ContentType.ApplicationJson);
すべてのクライアントにバイナリ メッセージをブロードキャストする
var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");
Stream stream = BinaryData.FromString("Hello World!").ToStream();
serviceClient.SendToAll(RequestContent.Create(stream), ContentType.ApplicationOctetStream);
フィルターを使用してクライアントにメッセージをブロードキャストする
Azure Web PubSub では、メッセージを送信する接続を除外する OData フィルター構文がサポートされています。
構文の詳細 filter
については、「 Azure Web PubSub の OData フィルター構文」を参照してください。
var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");
// Use filter to send text message to anonymous connections
serviceClient.SendToAll(
RequestContent.Create("Hello World!"),
ContentType.TextPlain,
filter: ClientConnectionFilter.Create($"userId eq {null}"));
// Use filter to send JSON message to connections in groupA but not in groupB
var group1 = "GroupA";
var group2 = "GroupB";
serviceClient.SendToAll(RequestContent.Create(
new
{
Foo = "Hello World!",
Bar = 42
}),
ContentType.ApplicationJson,
filter: ClientConnectionFilter.Create($"{group1} in groups and not({group2} in groups)"));
接続管理
一部のユーザーの接続をいくつかのグループに追加します。
client.AddUserToGroup("some_group", "some_user");
// Avoid sending messages to users who do not exist.
if (client.UserExists("some_user").Value)
{
client.SendToUser("some_user", "Hi, I am glad you exist!");
}
client.RemoveUserFromGroup("some_group", "some_user");
すべてのグループから接続を削除する
var client = new WebPubSubServiceClient(connectionString, "some_hub");
client.RemoveConnectionFromAllGroups("some_connection");
トラブルシューティング
コンソール ログの設定
また、サービスに対して行う要求の詳細を確認する場合は、コンソールのログ記録を簡単に有効にすることもできます。
次のステップ
このライブラリの使用方法の詳細な例については、 samples ディレクトリを参照してください。
共同作成
このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、https://cla.microsoft.com. を参照してください。
pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。
このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。
Azure SDK for .NET