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

Biblioteka klienta Azure Web PubSub Chat umożliwia aplikacjom serwerowym zarządzanie rolami czatu, użytkownikami, pokojami, członkostwem w pokojach, rozmowami i wiadomościami w centrum czatu Azure Web PubSub.

Rozpoczęcie pracy

Obecnie obsługiwane środowiska

  • Wersje LTS systemu Node.js

Aby uzyskać więcej informacji, zobacz nasze zasad pomocy technicznej.

Wymagania wstępne

Instalowanie pakietu @azure/web-pubsub-chat

Zainstaluj bibliotekę klienta Azure WebPubSubChatService dla JavaScript z :npm

npm install @azure/web-pubsub-chat

Twórz i uwierzytelnij WebPubSubChatServiceClient

Obsługuje WebPubSubChatServiceClient uwierzytelnianie za pomocą parametry połączenia, danych uwierzytelniających Microsoft Entra lub .AzureKeyCredential

Uwierzytelnij się za pomocą parametry połączenia

Znajdziesz parametry połączenia dla swojego zasobu Azure Web PubSub w Azure Portal. Ponieważ parametry połączenia zawiera klucz dostępu, przechowuj go bezpiecznie i nie uwzględniaj w kodzie źródłowym.

Uwierzytelnij się za pomocą Microsoft Entra ID

Aby uwierzytelnić się za pomocą Microsoft Entra ID, będziesz potrzebować endpoint swojego zasobu Azure Web PubSub oraz danych uwierzytelniających. Punkt końcowy znajdziesz w Azure Portal.

Możesz uwierzytelnić się za pomocą Microsoft Entra ID, używając poświadczenia z biblioteki @azure/identity lub istniejącego tokena Microsoft Entra.

Aby użyć dostawcy DefaultAzureCredential pokazanego poniżej lub innych dostawców poświadczeń dostarczonych z zestawem Azure SDK, zainstaluj pakiet @azure/identity:

npm install @azure/identity

DefaultAzureCredentialobsługuje kilka tożsamości Microsoft Entra. Podczas lokalnego rozwoju może korzystać z tożsamości dewelopera zalogowanej za pomocą wspieranego narzędzia deweloperskiego. W Azure może korzystać z tożsamości zarządzanej (managed identity). Może także uwierzytelniać zasadę usługi lub tożsamość obciążenia, gdy jest skonfigurowana pod kątem środowiska.

Niezależnie od tego, jaką tożsamość wybierzesz, musi być przypisana odpowiednia rola Azure Web PubSub w płaszczyźnie danych. Role zarządzania zasobami w Azure, takie jak Owner nie przyznają uprawnień do poziomu danych.

Stwórz klienta z parametry połączenia, poświadczeniem Microsoft Entra, takim jak DefaultAzureCredential, lub .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>",
);

Kluczowe pojęcia

WebPubSubChatServiceClient

WebPubSubChatServiceClient jest głównym interfejsem do zarządzania zasobami czatu w hubie Web PubSub.

Centrum

Hub to logiczna granica dla aplikacji czatu. Role, użytkownicy, pokoje, rozmowy i wiadomości zarządzane przez klienta należą do hubu dostarczonego konstruktorowi klienta.

Role i uprawnienia

Rola użytkownika kontroluje działania na poziomie huba, takie jak tworzenie pokoi. Rola pokoju kontroluje działania w pomieszczeniu, takie jak publikowanie wiadomości, czytanie historii wiadomości czy zapraszanie użytkowników.

Pokoje, członkowie i rozmowy

Pokój zawiera członków i prowadzi domyślną rozmowę. Dodaj użytkownika do pokoju, przypisując mu rolę pokoju. Wiadomości są publikowane przez połączonych klientów czatu i mogą być wylistowane, aktualizowane lub usuwane za pośrednictwem klienta usługi.

Tagi jednostek

Zasoby czatu mają wartość etag . Przekaż tę wartość przez opcję operacji ifMatch do wykonania zmiany warunkowej lub usunięcia i zapobiegania nadpisowi nowszej wersji zasobu.

Przykłady

Ustaw role, użytkownika i pokój

Stwórz role użytkownika i pokoju, stwórz użytkownika ludzkiego i pokój, a następnie dodaj użytkownika do pokoju.

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

Używaj wbudowanych ról i znanych uprawnień

Użyj przy BuiltInChatRoles przypisywaniu roli zdefiniowanej przez usługę oraz KnownChatPermission przy tworzeniu roli niestandardowej. Ciągi uprawnień spoza znanych wartości są również akceptowane dla zgodności w przyszłości.

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

Zarządzanie rolami

Stwórz niestandardową rolę, pobierz ją, wypisz role w hubie i usuń ją po ukończeniu.

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

Zarządzaj pokojem

Stwórz pokój, odzyskaj jego aktualny stan i usuń go.

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

Zarządzanie użytkownikiem

Stwórz użytkownika z wbudowaną rolą, pobierz profil i usuń go.

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

Wypisz wiadomości w rozmowie

Użyj iteracji asynchronicznej, aby odczytać wiadomości z rozmowy na wszystkich stronach wyników.

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

Wygeneruj token dostępu klienta

Wygeneruj adres URL, którego klient czatu może użyć do połączenia się z usługą Web PubSub jako konkretny użytkownik.

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

Przemysł drzewny

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentacją pakietu @azure/logger.

Contributing

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

  • Last updated on