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 識別碼驗證

要使用 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 資源管理角色例如 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 是管理 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}`);
}

產生一個用戶端存取權杖

產生一個 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