Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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.
Azure SDK for JavaScript