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

De Azure Web PubSub Chat clientbibliotheek stelt serverapplicaties in staat om chatrollen, gebruikers, kamers, kamerlidmaatschap, gesprekken en berichten te beheren in een Azure Web PubSub Chat-hub.

Aan de slag

Momenteel ondersteunde omgevingen

Zie ons ondersteuningsbeleid voor meer informatie.

Prerequisites

  • Een Azure-abonnement.
  • Een bestaande Azure Web PubSub-bron.
  • Een hubnaam voor de chatapplicatie.

Het @azure/web-pubsub-chat-pakket installeren

Installeer de Azure WebPubSubChatService clientbibliotheek voor JavaScript met npm:

npm install @azure/web-pubsub-chat

Een WebPubSubChatServiceClient maken en verifiëren

De WebPubSubChatServiceClient ondersteunt authenticatie met een verbindingsreeks, een Microsoft Entra-credential, of een AzureKeyCredential.

Authenticeer met een verbindingsreeks

Je kunt de verbindingsreeks voor je Azure Web PubSub-resource vinden in de Azure Portal. Omdat de verbindingsreeks een access key bevat, sla deze dan veilig op en neem deze niet op in de broncode.

Verifiëren met Microsoft Entra-id

Om te authenticeren met Microsoft Entra ID, heb je de endpoint gegevens van je Azure Web PubSub-bron en een inloggegevens nodig. Je kunt het eindpunt vinden in de Azure Portal.

Je kunt authenticeren met Microsoft Entra ID met een inloggegevens uit de @azure/identity-bibliotheek of een bestaand Microsoft Entra-token.

Als u de DefaultAzureCredential- provider wilt gebruiken die hieronder wordt weergegeven, of andere referentieproviders die zijn opgegeven bij de Azure SDK, installeert u het @azure/identity-pakket:

npm install @azure/identity

DefaultAzureCredentialondersteunt verschillende Microsoft Entra-identiteiten. Tijdens lokale ontwikkeling kan het een ontwikkelaarsidentiteit gebruiken die is ingelogd via een ondersteund ontwikkelprogramma. In Azure kan het een beheerde identiteit gebruiken. Het kan ook een serviceprincipal of workloadidentiteit authenticeren wanneer het voor de omgeving is geconfigureerd.

Welke identiteit je ook gebruikt, moet een passende Azure Web PubSub dataplane-rol toegewezen krijgen. Azure resource-management rollen zoals Owner geven geen data-plane permissies.

Maak de client aan met een verbindingsreeks, een Microsoft Entra-credential zoals DefaultAzureCredential, of een 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>",
);

belangrijke concepten

WebPubSubChatServiceClient

WebPubSubChatServiceClient is de primaire interface voor het beheren van chatbronnen in een Web PubSub-hub.

Knooppunt

Een hub is de logische grens voor een chatapplicatie. Rollen, gebruikers, kamers, gesprekken en berichten die door een client worden beheerd, behoren allemaal tot de hub die aan de clientconstructor wordt geleverd.

Rollen en machtigingen

Een gebruikersrol beheert hub-niveau acties zoals het aanmaken van kamers. Een kamerrol beheert acties binnen een kamer, zoals het publiceren van berichten, het lezen van berichtgeschiedenis of het uitnodigen van gebruikers.

Kamers, leden en gesprekken

Een kamer bevat leden en heeft een standaard gesprek. Voeg een gebruiker toe aan een kamer door de gebruiker een kamerrol toe te wijzen. Berichten worden gepubliceerd door verbonden chatclients en kunnen via de serviceclient worden vermeld, bijgewerkt of verwijderd.

Entiteitstags

Chatbronnen bevatten een etag waarde. Geef die waarde door via de ifMatch optie van een operatie om een voorwaardelijke update uit te voeren of te verwijderen en te voorkomen dat een nieuwere resourceversie wordt overschreven.

Voorbeelden

Stel rollen, een gebruiker en een kamer in

Maak gebruikers- en kamerrollen, maak een menselijke gebruiker en een kamer, en voeg die gebruiker dan toe aan de kamer.

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

Gebruik ingebouwde rollen en bekende permissies

Gebruik BuiltInChatRoles bij het toewijzen van een service-defined role en KnownChatPermission bij het aanmaken van een aangepaste rol. Toestemmingsstrings buiten de bekende waarden worden ook geaccepteerd voor forward compatibiliteit.

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 beheren

Maak een aangepaste rol aan, haal deze op, vermeld de rollen in de hub en verwijder de aangepaste rol als je klaar bent.

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

Beheer een kamer

Maak een kamer aan, haal de huidige staat op en verwijder deze.

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

Beheer een gebruiker

Maak een gebruiker aan met een ingebouwde rol, haal het profiel op en verwijder het.

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

Lijst berichten in een gesprek

Gebruik asynchrone iteratie om berichten van een gesprek op alle resultaatpagina's te lezen.

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

Genereer een clienttoegangstoken

Genereer een URL die een chatclient kan gebruiken om als specifieke gebruiker verbinding te maken met de Web PubSub-dienst.

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

Logging

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken, kunt u de @azure/logger pakketdocumentenbekijken.

Contributing

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

  • Laatst bijgewerkt om