Azure Web PubSub Chat-Clientbibliothek für JavaScript – Version 1.0.0-beta.2

Die Azure Web PubSub Chat-Clientbibliothek ermöglicht es Serveranwendungen, Chat-Rollen, Benutzer, Räume, Themen, Raummitgliedschaft, Gespräche und Nachrichten in einem Azure Web PubSub Chat-Hub zu verwalten. Verwenden Sie es, um Diskussionen in Raumthemen zu organisieren, Benutzer und deren Räume zu entdecken und Chatressourcen von Ihrer Serveranwendung aus zu verwalten.

Wichtige Links:

Erste Schritte

Derzeit unterstützte Umgebungen

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Voraussetzungen

  • Ein Azure-Abonnement.
  • Eine bestehende Azure Web PubSub-Ressource.
  • Ein Hub, der mit aktiviertem Chat und persistentem Speicher konfiguriert ist.

Installieren Sie das @azure/web-pubsub-chat-Paket

Installiere die Azure WebPubSubChatService Client-Bibliothek für JavaScript mit npm:

npm install @azure/web-pubsub-chat

Konfigurieren von TypeScript

Dieses Paket enthält TypeScript-Deklarationen. Installieren Sie für Node.js in TypeScript geschriebene Anwendungen die Node.js Typdefinitionen:

npm install --save-dev @types/node

Es sind keine zusätzlichen, paketspezifischen Compiler-Einstellungen erforderlich.

Erstellen und Authentifizieren einer WebPubSubChatServiceClient

Die unterstützt WebPubSubChatServiceClient die Authentifizierung mit einer Verbindungszeichenfolge, einer Microsoft Entra-Credential oder einer AzureKeyCredential.

Authentifizieren Sie sich mit einer Verbindungszeichenfolge

Die Verbindungszeichenfolge für deine Azure Web PubSub-Ressource findest du im Azure-Portal. Da die Verbindungszeichenfolge einen Zugriffsschlüssel enthält, speichern Sie ihn sicher und fügen Sie ihn nicht in den Quellcode ein.

Authentifizierung mit Microsoft Entra ID

Um sich mit Microsoft Entra ID zu authentifizieren, benötigen Sie die endpoint Quelle Ihrer Azure Web PubSub und eine Zugangsdaten. Den Endpunkt findest du im Azure-Portal.

Sie können sich mit der Microsoft Entra ID authentifizieren, indem Sie eine Zugangsdaten aus der @azure/identity-Bibliothek oder ein bestehendes Microsoft Entra-Token verwenden.

Um den unten gezeigten DefaultAzureCredential Anbieter oder andere Anmeldeinformationsanbieter zu verwenden, die mit dem Azure SDK bereitgestellt werden, installieren Sie bitte das @azure/identity Paket:

npm install @azure/identity

DefaultAzureCredentialunterstützt mehrere Microsoft Entra-Identitäten. Während der lokalen Entwicklung kann sie eine Entwickleridentität verwenden, die über ein unterstütztes Entwicklungstool angemeldet ist. In Azure kann eine verwaltete Identität verwendet werden. Es kann auch einen Service Principal oder eine Workload-Identität authentifizieren, wenn es für die Umgebung konfiguriert ist.

Welche Identität du auch immer verwendest, muss eine entsprechende Azure Web PubSub-Dataplane-Rolle zugewiesen bekommen. Azure-Ressourcenmanagement-Rollen wie z. Owner B. gewähren keine Data-Plane-Berechtigungen.

Erstelle den Client mit einer Verbindungszeichenfolge, einer Microsoft Entra-Credential wie DefaultAzureCredential, oder einer 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>",
);

Wichtige Konzepte

Drehscheibe

Ein Hub ist eine logische Sammlung von WebSocket-Verbindungen. Ein Chat-Hub fügt integrierte Räume, Mitgliederverwaltung, Nachrichtenpersistenz und chatspezifische APIs hinzu.

Dieses SDK gilt nur für Chat-Hubs. Der Chat muss auf dem Ziel-Hub aktiviert sein, bevor das SDK Rollen, Benutzer, Räume, Mitglieder, Konversationen oder Nachrichten verwalten kann.

Rolle und Berechtigung

Eine Rolle ist eine benannte Sammlung von Chat-Berechtigungen. Benutzerrollennamen beginnen mit , und Raumrollennamen beginnen mit user.room.. Kombinieren Sie Benutzer- und Raumberechtigungen nicht in einer einzigen Rolle.

Benutzerrollen steuern Vorgänge wie das Erstellen von Räumen. Raumrollen steuern, was ein Mitglied in einem bestimmten Raum tun darf, etwa Nachrichten zu veröffentlichen oder Nachrichtenverlauf zu lesen.

User

Ein Benutzer repräsentiert eine Identität, die am Chat teilnimmt, wie etwa einen menschlichen Endnutzer oder eine Anwendung. Client-Zugangsdaten verknüpfen WebSocket-Verbindungen mit einer Benutzer-ID.

Zimmer

Ein Raum gruppiert Nutzer zusammen und ist die primäre organisatorische Einheit für Chat-Interaktionen. Jeder Raum hat eine automatisch erstellte Standardkonversation.

Zimmermitglied

Ein Raummitglied repräsentiert einen Benutzer, der einem Raum hinzugefügt wurde. Die Mitgliedschaft kontrolliert, welche Nutzer Nachrichten im Raum empfangen und senden können. In der Service-API wird jedem Raummitglied eine Raumrolle zugewiesen.

Konversations- und Nachrichtenverlauf

Ein Gespräch ist ein geordneter Nachrichtenstrom innerhalb eines Raumes. Jeder Raum hat eine Standardkonversation, und zusätzliche benannte Gespräche können über Themen erstellt werden.

Nachrichten, die an ein Gespräch gesendet werden, werden in Echtzeit an die verbundenen Mitglieder des Raumes übermittelt. Der Chat-Dienst verwaltet die Reihenfolge und Persistenz, sodass Mitglieder den Nachrichtenverlauf laden können, nachdem sie sich wieder verbinden oder später beitreten können. Der Dienstclient kann gespeicherte Nachrichten auflisten, aktualisieren und löschen.

Thema

Ein Thema repräsentiert ein benanntes Gespräch innerhalb eines Raumes. Themen können unabhängig von der Standardkonversation des Raums erstellt, umbenannt, archiviert und softgelöscht werden.

Examples

Stellen Sie Rollen, einen Benutzer und einen Raum ein

Erstelle Benutzer- und Raumrollen, erstelle einen menschlichen Nutzer und einen Raum und füge dann den Benutzer dem Raum hinzu.

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

Verwenden Sie eingebaute Rollen und bekannte Berechtigungen

Verwenden BuiltInChatRoles Sie bei der Zuweisung einer dienstdefinierten Rolle und KnownChatPermission beim Erstellen einer benutzerdefinierten Rolle. Berechtigungszeichenketten außerhalb der bekannten Werte werden ebenfalls für die Vorwärtskompatibilität akzeptiert.

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

Rollen verwalten

Erstelle eine benutzerdefinierte Rolle, rufe sie ab, liste die Rollen im Hub auf und lösche die benutzerdefinierte Rolle, wenn du fertig bist.

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

Einen Raum verwalten

Erstelle einen Raum, rufe seinen aktuellen Zustand ab und lösche ihn.

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

Verwaltung eines Benutzers

Erstelle einen Benutzer mit einer eingebauten Rolle, rufe das Profil ab und lösche es. Die Anfrage akzeptiert HumanChatUserCreateOrReplace, was , nickname, und roleNameerfordertkind: "Human". Zurückgegebene Profile behalten die Ressourcenfelder bei und können unbekannte Benutzertypen darstellen.

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

Nachricht aktualisieren

Beim Aktualisieren einer Nachricht ChatMessageUpdate.createdBy sind und content optional. Geben Sie nur die zu ändernden Felder an; ausgelassene Felder behalten ihre aktuellen Werte.

Listen Sie Nachrichten in einem Gespräch auf

Verwenden Sie asynchrone Iteration, um Nachrichten aus einer Konversation über alle Ergebnisseiten hinweg zu lesen, von der neuesten bis zur frühesten. Nachrichten-IDs sind Paginierungscursore: Der Iterator folgt dem nextLinkdes Dienstes , der den nächsten Nachrichten-ID-Cursor enthält. Um später fortzufahren, speichern Sie die Seite continuationToken und geben Sie sie an byPage({ continuationToken }); weiter, verwenden Sie das zurückgegebene Token unverändert, anstatt eine blanke Nachrichten-ID zu übergeben.

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

Generiere einen Client-Zugriffstoken

Generiere eine URL, die ein Chat-Client nutzen kann, um sich als spezifischer Nutzer mit dem Web PubSub-Dienst zu verbinden.

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

Räume in einem Hub auflisten

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
for await (const room of client.listRooms({ maxPageSize: 20 })) {
  console.log(`${room.id}: ${room.title}`);
}

Benutzer in einem Hub auflisten

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
for await (const user of client.listUsers({ maxPageSize: 20 })) {
  console.log(`${user.id}: ${user.nickname}`);
}

Listen Sie die Zimmer eines Benutzers auf

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
for await (const room of client.listRoomsForUser("alice", { maxPageSize: 20 })) {
  console.log(`${room.id}: ${room.title}`);
}

Erstellen eines Themas

Erstellen Sie ein Thema in einem bestehenden Raum. Der Dienst erstellt seine zugehörige Konversation.

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const topic = await client.createOrReplaceTopic(
  "general",
  "announcements",
  {
    title: "Announcements",
  },
  { ifNoneMatch: "*" },
);
console.log(`Topic conversation: ${topic.conversationId}`);

Abrufen eines Themas

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const topic = await client.getTopic("general", "announcements");
console.log(`${topic.title}: ${topic.state}, ETag: ${topic.etag}`);

Thema aktualisieren

Archivieren Sie ein bestehendes Thema, ohne seinen Titel zu ändern. Ersetzen Sie <etag> den aktuellen Entity-Tag.

import { WebPubSubChatServiceClient, KnownChatTopicState } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const topic = await client.updateTopic(
  "general",
  "announcements",
  {
    state: KnownChatTopicState.Archived,
  },
  { ifMatch: "<etag>" },
);
console.log(`Topic state: ${topic.state}`);

Themen in einem Raum auflisten

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
for await (const topic of client.listTopics("general", { maxPageSize: 20 })) {
  console.log(`${topic.id}: ${topic.title} (${topic.state})`);
}

Paginierung des Themenbereichs fortsetzen

Listenoperationen akzeptieren Fortsetzungstoken über , nicht über byPage({ continuationToken })die Optionen der Listenmethode. Geben Sie das auf einer Seite zurückgegebene Token unverändert weiter.

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const pages = client.listTopics("general", { maxPageSize: 20 }).byPage();
const firstPage = await pages.next();
if (!firstPage.done) {
  console.log(firstPage.value);
  const continuationToken = firstPage.value.continuationToken;
  if (continuationToken) {
    const resumedPages = client
      .listTopics("general", { maxPageSize: 20 })
      .byPage({ continuationToken });
    const nextPage = await resumedPages.next();
    console.log(nextPage.value);
  }
}

Löschen eines Themas

Ein bestehendes Thema weich löschen. Ersetzen Sie <etag> den aktuellen Entity-Tag.

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
await client.deleteTopic("general", "announcements", { ifMatch: "<etag>" });

Troubleshooting

Servicefehler und bedingte Anfragen

Servicefehler werfen RestError mit einem statusCode. HTTP 404 weist auf eine fehlende Ressource hin, einschließlich eines gelöschten Themen. HTTP 412 zeigt an, dass eine ifMatch oder ifNoneMatch Voraussetzung fehlgeschlagen ist. Rufen Sie die aktuelle Ressource ab und überprüfen Sie deren Entity-Tag, bevor Sie einen bedingten Schreibprozess erneut versuchen. Verwenden Sie ifNoneMatch: "*" dies nur beim Erstellen einer Ressource, wenn sie noch nicht existiert.

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Nächste Schritte

Erkunden Sie die JavaScript- und TypeScript-Beispiele sowie die API-Referenz.

Contributing

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.