你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

Azure Web PubSub 聊天客户端库使服务器应用能够管理聊天角色、用户、房间、房间成员、对话和消息，这些内容在 Azure Web PubSub 聊天中心中。

入门

目前支持的环境

Node.js的 LTS 版本

有关更多详细信息，请参阅我们的支持政策。

先决条件

Azure 订阅。
一个现有的 Azure Web PubSub 资源。
聊天应用的集线器名称。

安装 `@azure/web-pubsub-chat` 包

安装 Azure WebPubSubChatService JavaScript 客户端库，使用：npm

npm install @azure/web-pubsub-chat

创建和验证 `WebPubSubChatServiceClient`

它WebPubSubChatServiceClient支持通过连接字符串、Microsoft Entra凭证AzureKeyCredential或.进行认证。

用连接字符串认证

你可以在Azure 门户中找到Azure Web PubSub资源的连接字符串。由于连接字符串包含访问密钥，请安全存储，且不包含在源代码中。

使用 Microsoft Entra ID 进行身份验证

要用 Microsoft Entra ID 认证，你需要endpoint你的 Azure Web PubSub 资源和凭证。你可以在 Azure 门户中找到该端点。

你可以用@azure/identity库中的凭据或现有的Microsoft Entra令牌进行Microsoft Entra ID认证。

若要使用如下所示的 DefaultAzureCredential 提供程序，或 Azure SDK 提供的其他凭据提供程序，请安装 @azure/identity 包：

npm install @azure/identity

DefaultAzureCredential支持多个 Microsoft Entra 身份。在本地开发过程中，它可以使用通过支持的开发工具登录的开发者身份。在 Azure 中，它可以使用托管身份。在配置时，它还能认证服务主体或工作负载身份。

无论你使用哪种身份，都必须被分配一个合适的 Azure Web PubSub 数据平面角色。 Azure resource-management roles like do Owner not grant data-plane permissions.

创建客户端时，可以使用连接字符串、Microsoft Entra凭证（如DefaultAzureCredential，或）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 是管理网络PubSub中心聊天资源的主要界面。

Hub

集线器是聊天应用的逻辑边界。客户端管理的所有角色、用户、房间、对话和消息都属于客户端构建器提供的枢纽。

角色和权限

用户角色控制枢纽级操作，如创建房间。房间角色控制房间内的操作，如发布消息、阅读消息历史或邀请用户。

房间、成员与对话

一个房间包含成员，并且有默认对话。通过分配房间角色将用户添加到房间。消息由连接的聊天客户端发布，可以通过服务客户端列出、更新或删除。

实体标记

聊天资源包含价值 etag 。通过操作选项 ifMatch 传递该值，以执行条件更新或删除，防止覆盖更新的资源版本。

Examples

设置角色、用户和房间

创建用户和房间角色，创建一个人类用户和一个房间，然后将用户添加到房间。

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}`);

使用内置角色和已知权限

在分配服务定义角色和KnownChatPermission创建自定义角色时使用BuiltInChatRoles。已知值之外的权限字符串也被接受以实现前向兼容性。

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}`);
}

生成客户端访问令牌

生成一个URL，供聊天客户端作为特定用户连接到Web PubSub服务。

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/记录器包文档。

Contributing

若要参与此库，请阅读贡献指南了解有关如何生成和测试代码的详细信息。

反馈

此页面是否有帮助？

Last updated on 2026-09-04