Azure Web PubSub Chat client library for JavaScript - version 1.0.0-beta.1

Azure Web PubSub Chatクライアントライブラリは、サーバーアプリケーションがAzure Web PubSubチャットハブ内でチャットロール、ユーザー、ルーム、ルームメンバーシップ、会話、メッセージを管理できるようにします。

作業の開始

現在サポートされている環境

Node.js の LTS バージョン

詳細については、サポートポリシーのを参照してください。

Prerequisites

Azure サブスクリプション。
既存のAzure Web PubSubリソースです。
チャットアプリケーションのハブ名です。

`@azure/web-pubsub-chat` パッケージをインストールする

JavaScript用のAzure WebPubSubChatServiceクライアントライブラリをnpmでインストールしてください:

npm install @azure/web-pubsub-chat

`WebPubSubChatServiceClient` を作成して認証する

WebPubSubChatServiceClientは接続文字列、Microsoft Entra認証情報、またはAzureKeyCredentialによる認証をサポートしています。

接続文字列で認証する

Azure Web PubSubリソースの接続文字列はAzure portalで見つけることができます。接続文字列にはアクセスキーが含まれているため、安全に保存し、ソースコードには含めないでください。

Microsoft Entra ID を使用して認証する

Microsoft Entra IDで認証するには、Azure Web PubSubリソースのendpointと資格証明書が必要です。エンドポイントはAzure portalで見つけることができます。

Microsoft Entra IDで認証するには、@azure/identityライブラリの認証情報や既存のMicrosoft Entraトークンを使って認証できます。

以下に示す DefaultAzureCredential プロバイダー、または Azure SDK で提供されているその他の資格情報プロバイダーを使用するには、@azure/identity パッケージをインストールしてください。

npm install @azure/identity

DefaultAzureCredential複数のMicrosoft Entraアイデンティティをサポートしています。ローカル開発中は、サポートされた開発ツールを通じてサインインした開発者IDを使用できます。 Azureでは管理型アイデンティティを使用できます。また、環境に合わせて設定されたサービスプリンシパルやワークロードの識別を認証することも可能です。

使用するアイデンティティには、適切なAzure Web PubSubデータプレーンロールが割り当てられなければなりません。 Azure、Ownerのようなリソース管理役割はデータプレーン権限を付与しません。

クライアントには接続文字列、DefaultAzureCredentialのようなMicrosoft Entra認証情報、またはAzureKeyCredentialが必要です。

import { WebPubSubChatServiceClient, AzureKeyCredential } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const connectionStringClient = new WebPubSubChatServiceClient("<connectionString>", "<hubName>");
const tokenCredentialClient = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const keyCredentialClient = new WebPubSubChatServiceClient(
  "<endpoint>",
  new AzureKeyCredential("<accessKey>"),
  "<hubName>",
);

主な概念

WebPubSubChatServiceClient

WebPubSubChatServiceClient はWeb PubSubハブにおけるチャットリソース管理の主要なインターフェースです。

ハブ

ハブはチャットアプリケーションの論理的な境界線です。クライアントが管理するロール、ユーザー、ルーム、会話、メッセージはすべてクライアント構築者に提供されるハブに属します。

役割と権限

ユーザーロールは部屋の作成などのハブレベルの操作を制御します。ルームロールは、メッセージの公開、メッセージ履歴の閲覧、ユーザーの招待など、ルーム内の操作を制御します。

部屋、メンバー、会話

部屋にはメンバーがいて、デフォルトの会話が行われます。ユーザーにルームロールを割り当ててルームに追加します。メッセージは接続されたチャットクライアントによって公開され、サービスクライアントを通じてリスト、更新、削除が可能です。

エンティティタグ

チャットリソースには etag 値が含まれています。その値を操作の ifMatch オプションに通し、条件付き更新や削除を行い、新しいリソースバージョンの上書きを防ぎます。

例示

ロール、ユーザー、ルームを設定しましょう

ユーザーロールとルームロールを作成し、人間のユーザーとルームを作成し、そのユーザーをルームに追加します。

import { WebPubSubChatServiceClient, KnownChatPermission } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const userRoleName = "user.contoso_member";
const roomRoleName = "room.contoso_member";
const userId = "alice";
const roomId = "general";
await client.createOrReplaceRole(userRoleName, {
  permissions: [KnownChatPermission.UserCreateRoom],
});
await client.createOrReplaceRole(roomRoleName, {
  permissions: [KnownChatPermission.RoomPublishMessage, KnownChatPermission.RoomHistory],
});
await client.createOrReplaceUser(userId, {
  kind: "Human",
  nickname: "Alice",
  roleName: userRoleName,
});
const room = await client.createOrReplaceRoom(roomId, { title: "General" });
await client.createOrReplaceRoomMember(roomId, userId, { roleName: roomRoleName });
console.log(`Created room ${room.id} with conversation ${room.defaultConversation}`);

組み込みの役割と既知の権限を活用してください

サービス定義ロールの割り当て時に BuiltInChatRoles を使い、カスタムロールを作成する際に KnownChatPermission を使いましょう。既知の値外の権限文字列も順方向互換性のために受け入れられます。

import {
  WebPubSubChatServiceClient,
  BuiltInChatRoles,
  KnownChatPermission,
} from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
await client.createOrReplaceUser("alice", {
  kind: "Human",
  nickname: "Alice",
  roleName: BuiltInChatRoles.UserNormal,
});
await client.createOrReplaceRole("room.moderator", {
  permissions: [
    KnownChatPermission.RoomHistory,
    KnownChatPermission.RoomRemoveUser,
    KnownChatPermission.RoomPublishMessage,
  ],
});

ロールの管理

カスタムロールを作成し、それを取り出してハブにロールをリストアップし、完了したらカスタムロールを削除します。

import { WebPubSubChatServiceClient, KnownChatPermission } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const roleName = "user.contoso_member";
try {
  const role = await client.createOrReplaceRole(roleName, {
    permissions: [KnownChatPermission.UserCreateRoom, KnownChatPermission.UserFetchAllRooms],
  });
  console.log(`Created role: ${role.name}`);
  const fetchedRole = await client.getRole(roleName);
  console.log(`Fetched role: ${fetchedRole.name}`);
  for await (const listedRole of client.listRoles()) {
    console.log(`Role: ${listedRole.name}`);
  }
} finally {
  await client.deleteRole(roleName);
}

部屋を管理する

部屋を作成し、その現在の状態を取得して削除します。

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const roomId = "general";
const room = await client.createOrReplaceRoom(roomId, { title: "General" });
console.log(`Created room ${room.id} with conversation ${room.defaultConversation}`);
const fetchedRoom = await client.getRoom(roomId);
console.log(`Fetched room: ${fetchedRoom.id}, title: ${fetchedRoom.title}`);
await client.deleteRoom(roomId);

ユーザーを管理する

組み込みロールを持つユーザーを作成し、プロフィールを取得して削除します。

import { WebPubSubChatServiceClient, BuiltInChatRoles } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const userId = "alice";
const user = await client.createOrReplaceUser(userId, {
  kind: "Human",
  nickname: "Alice",
  roleName: BuiltInChatRoles.UserNormal,
});
console.log(`Created user: ${user.id}, nickname: ${user.nickname}`);
const fetchedUser = await client.getUser(userId);
console.log(`Fetched user: ${fetchedUser.id}, nickname: ${fetchedUser.nickname}`);
await client.deleteUser(userId);

会話中のメッセージをリストアップする

非同期反復を使って、すべての結果ページにわたって会話のメッセージを読み取ることができます。

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
for await (const message of client.listMessages("<conversationId>")) {
  console.log(`${message.createdBy}: ${message.content.text}`);
}

クライアントアクセストークンを生成します

チャットクライアントが特定のユーザーとしてWeb PubSubサービスに接続できるURLを生成してください。

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const accessToken = await client.getClientAccessToken({ userId: "alice" });

Troubleshooting

ログの記録

ログ記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、AZURE_LOG_LEVEL 環境変数を infoに設定します。または、setLogLevelで @azure/logger を呼び出すことによって、実行時にログを有効にすることもできます。

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

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

Contributing

このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-04