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

Az Azure Web PubSub Chat kliens könyvtára lehetővé teszi a szerveralkalmazások számára, hogy kezeljék a chat szerepeket, felhasználókat, szobákat, szobatagságot, beszélgetéseket és üzeneteket egy Azure Web PubSub Chat hubban.

Kezdő lépések

Jelenleg támogatott környezetek

További részletekért tekintse meg a támogatási szabályzat.

Prerequisites

  • Egy Azure-előfizetés.
  • Egy meglévő Azure Web PubSub-erőforrás.
  • Egy központi név a chat alkalmazáshoz.

Telepítse a(z) @azure/web-pubsub-chat csomagot

Install the Azure WebPubSubChatService client library for JavaScript with npm:

npm install @azure/web-pubsub-chat

WebPubSubChatServiceClient létrehozása és hitelesítése

Támogatja WebPubSubChatServiceClient a hitelesítést egy kapcsolati karakterlánc-vel, Microsoft Entra hitelesítéssel, vagy egy AzureKeyCredential.

Hitelesítés egy kapcsolati karakterlánc-vel

Az Azure Web PubSub erőforrásod kapcsolati karakterlánc az Azure Portal-ban található. Mivel a kapcsolati karakterlánc hozzáférési kulcsot tartalmaz, tárold biztonságosan, és ne vegyék be a forráskódba.

Microsoft Entra ID-val hitelesítse magát

A Microsoft Entra ID-vel való hitelesítéshez szükséged lesz endpoint az Azure Web PubSub erőforrásodra és egy hitelesítő igazolványra. A végpontot az Azure Portal-ban találhatod.

Hitelesítést a Microsoft Entra ID-vel lehet a @azure/identity könyvtár vagy egy meglévő Microsoft Entra token hitelesítésével.

Az alább látható DefaultAzureCredential szolgáltató vagy az Azure SDK-hoz biztosított egyéb hitelesítő adatok szolgáltatójának használatához telepítse a @azure/identity csomagot:

npm install @azure/identity

DefaultAzureCredentialtöbb Microsoft Entra identitást támogat. A helyi fejlesztés során egy támogatott fejlesztői eszközön keresztül beírt fejlesztői identitást használhat. Az Azure-ban kezelt identitást is használhat. A környezethez konfigurálva szolgáltatásalapot vagy munkaterhelés identitását is hitelesíteni.

Bármelyik identitást is használod, megfelelő Azure Web PubSub adatsík szerepet kell rendelni. Azure erőforrás-kezelő szerepek, például Owner nem adnak adatsík engedélyeket.

Hozza létre az ügyfelet egy kapcsolati karakterlánc-vel, egy Microsoft Entra hitelesítő igazolvánnyal, például DefaultAzureCredential, vagy egy 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>",
);

főbb fogalmak

WebPubSubChatServiceClient

WebPubSubChatServiceClient ez a fő felület a chat erőforrások kezelésére egy Web PubSub hubban.

Központ

A hub a logikus határ egy csevegőalkalmazás számára. A kliens által kezelt szerepek, felhasználók, szobák, beszélgetések és üzenetek mind a kliens konstruktorának biztosított hubhoz tartoznak.

Szerepkörök és engedélyek

A felhasználói szerep irányítja a központi szintű műveleteket, például a szobák létrehozását. A szobaszerep irányítja a szobán belüli műveleteket, például üzenetek közzétételét, üzenetelőzmények olvasását vagy felhasználók meghívását.

Szobák, tagok és beszélgetések

Egy teremben tagok vannak, és alapértelmezett beszélgetés van. Hozzáadj egy felhasználót a szobához úgy, hogy kijelölsz neki egy szobaszerepet. Az üzeneteket összekapcsolt csevegőkliensek teszik közzé, és a szolgáltatási kliensen keresztül felsorolhatók, frissíthetők vagy törölhetők.

Entitáscímkék

A chat forrásoknak van értékük etag . Ezt az értéket továbbítsd egy művelet azon opcióján, hogy feltételes frissítést hajtson végre vagy törölje, és megakadályozza, hogy ifMatch egy újabb erőforrás verzió felülírja.

Példák

Állíts be szerepeket, egy felhasználót és egy szobát

Hozz létre felhasználói és szobaszerepeket, hozz létre egy emberi felhasználót és egy szobát, majd add hozzá a felhasználót a szobához.

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

Beépített szerepek és ismert jogosultságok használata

Használat BuiltInChatRoles szolgáltatás által definiált szerep hozzárendelésekor és KnownChatPermission egyedi szerep létrehozásakor. Az ismert értékeken kívüli engedély stringeket is elfogadják az előrehaladási kompatibilitás érdekében.

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,
  ],
});

Szerepkörök kezelése

Hozz létre egy egyedi szerepet, kérd le, listázd fel a szerepeket a hubban, és töröld az egyedi szerepet, ha befejezte.

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

A szobát kezelni

Hozz létre egy szobát, kérd vissza a jelenlegi állapotát, és töröld.

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

Felhasználókezelés

Hozz létre egy beépített felhasználót, kérd vissza a profilt, és töröld azt.

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

Üzenetek listázása egy beszélgetésben

Használj aszinkron iterációt egy beszélgetés üzeneteinek olvasására az összes eredményoldalon.

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

Generálj kliens hozzáférési tokent

Generálj egy URL-t, amelyet egy csevegőkliens használhat, hogy egy adott felhasználóként csatlakozzon a Web PubSub szolgáltatáshoz.

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

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a környezeti változót a AZURE_LOG_LEVEL következőre info: . Alternatívaként a naplózás futásidőben is engedélyezhető a setLogLevel hívásával a @azure/logger.

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

setLogLevel("info");

A naplók engedélyezésére vonatkozó részletesebb útmutatásért tekintse meg a @azure/logger csomag dokumentációit.

Közreműködés

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót, amelyből többet is megtudhat a kód összeállításáról és teszteléséről.

  • Utolsó frissítés időpontja: