Azure Web PubSub Chat klientská knihovna pro JavaScript - verze 1.0.0-beta.1

Knihovna klientů Azure Web PubSub Chat umožňuje serverovým aplikacím spravovat chatovací role, uživatele, místnosti, členství v místnosti, konverzace a zprávy v Azure Web PubSub Chat hubu.

Začínáme

Aktuálně podporovaná prostředí

Další podrobnosti najdete v zásadách podpory.

Předpoklady

  • Předplatné služby Azure.
  • Existující Azure Web PubSub zdroj.
  • Název hubu pro chatovací aplikaci.

Nainstalujte balíček @azure/web-pubsub-chat.

Nainstalujte klientskou knihovnu Azure WebPubSubChatService pro JavaScript s npm:

npm install @azure/web-pubsub-chat

Vytvořte a ověřte WebPubSubChatServiceClient

Podporuje WebPubSubChatServiceClient autentizaci pomocí připojovací řetězec, přihlašovacího dokladu Microsoft Entra nebo AzureKeyCredential.

Autentizujte pomocí připojovací řetězec

připojovací řetězec pro váš Azure Web PubSub zdroj najdete v Azure Portal. Protože připojovací řetězec obsahuje přístupový klíč, ukládejte jej bezpečně a nezahrňte jej do zdrojového kódu.

Ověřte se pomocí Microsoft Entra ID

Pro autentizaci pomocí Microsoft Entra ID budete potřebovat endpoint svůj Azure Web PubSub zdroj a přihlašovací údaje. Endpoint najdete v Azure Portal.

Můžete se autentizovat pomocí Microsoft Entra ID pomocí přihlašovacích údajů z knihovny @azure/identity nebo existujícího Microsoft Entra tokenu.

Pokud chcete použít poskytovatele DefaultAzureCredential zobrazené níže nebo jiné zprostředkovatele přihlašovacích údajů poskytnuté sadou Azure SDK, nainstalujte balíček @azure/identity:

npm install @azure/identity

DefaultAzureCredentialpodporuje několik Microsoft Entra identit. Během lokálního vývoje může používat identitu vývojáře přihlášenou přes nástroj podporovaného vývoje. V Azure může používat spravovanou identitu. Může také autentizovat princip služby nebo identitu pracovní zátěže, pokud je nakonfigurován pro prostředí.

Ať už použijete jakoukoli identitu, musí být přiřazena odpovídající role v datové rovině Azure Web PubSub. Role správy zdrojů v Azure, například Owner neudělují oprávnění pro datovou rovinu.

Vytvořte klienta s připojovací řetězec, přihlašovacím kritériem Microsoft Entra, například DefaultAzureCredential, nebo .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>",
);

Klíčové koncepty

WebPubSubChatServiceClient

WebPubSubChatServiceClient je hlavní rozhraní pro správu chatovacích zdrojů v hubu Web PubSub.

Centrum

Hub je logickou hranicí pro chatovací aplikaci. Role, uživatelé, místnosti, konverzace a zprávy spravované klientem patří do hubu dodávaného konstruktoru klienta.

Role a oprávnění

Uživatelská role ovládá akce na úrovni hubu, například vytváření místností. Role místnosti řídí akce v místnosti, jako je publikování zpráv, čtení historie zpráv nebo pozvání uživatelů.

Místnosti, členové a konverzace

Místnost obsahuje členy a má výchozí konverzaci. Přidejte uživatele do místnosti přiřazením role místnosti. Zprávy jsou publikovány připojenými chatovými klienty a mohou být uvedeny, aktualizovány nebo smazány prostřednictvím klienta služby.

Značky entit

Chatovací zdroje obsahují etag hodnotu. Tuto hodnotu provést v operaci ifMatch možností podmíněné aktualizace nebo smazat a zabránit přepsání novější verze zdroje.

Examples

Nastavte role, uživatele a místnost

Vytvořte role uživatele a místnosti, vytvořte lidského uživatele a místnost a pak přidejte uživatele do místnosti.

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

Používejte vestavěné role a známá oprávnění

Použijte BuiltInChatRoles při přiřazování role definované službou a KnownChatPermission při vytváření vlastní role. Oprávnění řetězce mimo známé hodnoty jsou také akceptovány pro kompatibilitu dopředu.

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

Správa rolí

Vytvořte vlastní roli, natáhněte ji, vyveďte role v hubu a po dokončení tu roli smažte.

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

Spravovat místnost

Vytvořte místnost, získejte její aktuální stav a smažte ji.

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

Správa uživatele

Vytvořte uživatele s vestavěnou rolí, stáhněte profil a smažte ho.

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

Vyjmenujte zprávy v konverzaci

Použijte asynchronní iterace k přečtení zpráv z konverzace na všech stránkách výsledků.

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

Generujte klientský přístupový token

Vygenerujte URL, kterou může chat klient použít k připojení ke službě Web PubSub jako konkrétní uživatel.

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

Logování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

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

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Contributing

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

  • Last updated on