Azure Web PubSub Chat клиентская библиотека для JavaScript - версия 1.0.0-beta.1

Клиентская библиотека Azure Web PubSub Chat позволяет серверным приложениям управлять ролями в чате, пользователями, комнатами, членством в комнатах, разговорами и сообщениями в хабе Azure Web PubSub Chat.

Начало работы

Поддерживаемые в настоящее время среды

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 Web PubSub в портал Azure. Поскольку строка подключения содержит ключ доступа, храните его безопасно и не включайте в исходный код.

Аутентификация с помощью Microsoft Entra ID

Для аутентификации с помощью Microsoft Entra ID вам потребуется endpoint ваш ресурс Azure Web PubSub и учетная запись. Вы можете найти конечную точку в портал Azure.

Вы можете аутентифицироваться с помощью Microsoft Entra ID, используя учетные данные из библиотеки @azure/identity или имея существующий токен Microsoft Entra.

Чтобы использовать поставщик defaultAzureCredential, показанный ниже, или другие поставщики учетных данных, предоставленные пакетом Azure SDK, установите пакет :

npm install @azure/identity

DefaultAzureCredentialподдерживает несколько идентификаторов Microsoft Entra. Во время локальной разработки он может использовать идентификатор разработчика, войдённый через поддерживаемый инструмент разработки. В Azure он может использовать управляемую идентичность. Он также может аутентифицировать идентификатор сервиса или идентификатор рабочей нагрузки при настройке для среды.

Любая идентификация, которую вы используете, должна быть назначена соответствующей роли Azure Web PubSub data-plane. Роли управления ресурсами Azure, такие как Owner не предоставляют права на плоскость данных.

Создайте клиент с помощью строка подключения, учётной записи 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 хабе.

Хаб

Хаб — это логическая граница для чат-приложения. Роли, пользователи, комнаты, разговоры и сообщения, управляемые клиентом, принадлежат хабу, предоставляемому конструктору клиента.

Роли и разрешения

Пользовательская роль управляет действиями на уровне хаба, такими как создание комнат. Роль комнаты управляет действиями внутри комнаты, такими как публикация сообщений, чтение истории сообщений или приглашение пользователей.

Комнаты, участники и беседы

В комнате есть участники, и ведётся стандартный разговор. Добавьте пользователя в комнату, назначив ему роль в комнате. Сообщения публикуются через подключённые чат-клиенты и могут быть перечислены, обновлены или удалены через сервисный клиент.

Теги сущностей

Чат-ресурсы имеют ценность 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}`);
}

Генерируйте токен доступа клиента

Сгенерируйте URL, который чат-клиент сможет использовать для подключения к веб-сервису 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

Logging

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. В альтернативном порядке, логирование можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

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

setLogLevel("info");

Дополнительные инструкции по включению журналов см. в документации по пакету @azure/loger.

Contributing

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по созданию и тестированию кода.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-09-04