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

Die Azure Web PubSub Chat Client-Bibliothek ermöglicht es Serveranwendungen, Chatrollen, Benutzer, Räume, Raummitgliedschaften, Konversationen und Nachrichten in einem Azure Web PubSub Chat-Hub zu verwalten.

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-Name für die Chat-Anwendung.

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

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

WebPubSubChatServiceClient

WebPubSubChatServiceClient ist die primäre Schnittstelle zur Verwaltung von Chat-Ressourcen in einem Web-PubSub-Hub.

Drehscheibe

Ein Hub ist die logische Grenze für eine Chat-Anwendung. Rollen, Benutzer, Räume, Gespräche und von einem Client verwaltete Nachrichten gehören alle zum Hub, der dem Client-Konstruktor zur Verfügung gestellt wird.

Rollen und Berechtigungen

Eine Benutzerrolle steuert Hub-Aktionen wie das Erstellen von Räumen. Eine Raumrolle steuert Aktionen innerhalb eines Raums, wie das Veröffentlichen von Nachrichten, das Lesen der Nachrichtenhistorie oder das Einladen von Benutzern.

Räume, Mitglieder und Gespräche

Ein Raum enthält Mitglieder und hat standardmäßig ein Gespräch. Fügen Sie einem Raum einen Benutzer hinzu, indem Sie ihm eine Raumrolle zuweisen. Nachrichten werden von verbundenen Chat-Clients veröffentlicht und können über den Service-Client aufgelistet, aktualisiert oder gelöscht werden.

Entity-tags

Chat-Ressourcen enthalten einen Wert etag . Geben Sie diesen Wert durch die ifMatch Option einer Operation weiter, um ein bedingtes Update oder Löschen durchzuführen und eine neuere Ressourcenversion zu vermeiden.

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.

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

Listen Sie Nachrichten in einem Gespräch auf

Verwenden Sie asynchrone Iteration, um Nachrichten aus einem Gespräch über alle Ergebnisseiten hinweg zu lesen.

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

Troubleshooting

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.

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.

  • Last updated on