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

Azure Web PubSub Chat-klientbiblioteket gör det möjligt för serverapplikationer att hantera chattroller, användare, rum, rumsmedlemskap, konversationer och meddelanden i en Azure Web PubSub Chat-hubb.

Komma igång

Miljöer som stöds för närvarande

Mer information finns i vår supportprincip.

Förutsättningar

Installera @azure/web-pubsub-chat-paketet

Installera Azure WebPubSubChatService-klientbiblioteket för JavaScript mednpm:

npm install @azure/web-pubsub-chat

Skapa och autentisera en WebPubSubChatServiceClient

Stöder WebPubSubChatServiceClient autentisering med en reťazec pripojenia, en Microsoft Entra-legitimation eller en AzureKeyCredential.

Autentisera med en reťazec pripojenia

Du kan hitta reťazec pripojenia för din Azure Web PubSub-resurs i Azure Portal. Eftersom reťazec pripojenia innehåller en accessnyckel, lagra den säkert och inkludera den inte i källkoden.

Autentisera med Microsoft Entra ID

För att autentisera med Microsoft Entra ID behöver endpoint du din Azure Web PubSub-resurs och en legitimation. Du kan hitta endpointen i Azure Portal.

Du kan autentisera dig med Microsoft Entra ID med en legitimation från @azure/identity-biblioteket eller en befintlig Microsoft Entra-token.

Installera -paketet om du vill använda @azure/identity som visas nedan eller andra leverantörer av autentiseringsuppgifter som tillhandahålls med Azure SDKs:

npm install @azure/identity

DefaultAzureCredentialstöder flera Microsoft Entra-identiteter. Under lokal utveckling kan den använda en utvecklaridentitet inloggad via ett stödd utvecklingsverktyg. I Azure kan den använda en hanterad identitet. Den kan också autentisera en tjänstehuvudperson eller arbetsbelastningsidentitet när den är konfigurerad för miljön.

Oavsett vilken identitet du använder måste den tilldelas en lämplig Azure Web PubSub-dataplansroll. Azure-resurshanteringsroller såsom Owner ger inte dataplansbehörigheter.

Skapa klienten med en reťazec pripojenia, en Microsoft Entra-legitimation såsom DefaultAzureCredential, eller en 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>",
);

Viktiga begrepp

WebPubSubChatServiceClient

WebPubSubChatServiceClient är det primära gränssnittet för att hantera chattresurser i en Web PubSub-hubb.

Hub

En hubb är den logiska gränsen för en chattapplikation. Roller, användare, rum, konversationer och meddelanden som hanteras av en klient tillhör alla hubben som tillhandahålls klientkonstruktören.

Roller och behörigheter

En användarroll styr navnivå-åtgärder såsom att skapa rum. En rumsroll styr handlingar inom ett rum, såsom att publicera meddelanden, läsa meddelandehistorik eller bjuda in användare.

Rum, medlemmar och samtal

Ett rum innehåller medlemmar och har en standardkonversation. Lägg till en användare i ett rum genom att tilldela användaren en rumsroll. Meddelanden publiceras av anslutna chattklienter och kan listas, uppdateras eller raderas via tjänsteklienten.

Entitetstaggar

Chattresurser inkluderar ett etag värde. Skicka det värdet genom en operations ifMatch alternativ för att utföra en villkorlig uppdatering eller ta bort och förhindra att en nyare resursversion skrivs över.

Examples

Sätt upp roller, en användare och ett rum

Skapa användar- och rumsroller, skapa en mänsklig användare och ett rum, och lägg sedan till användaren i rummet.

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

Använd inbyggda roller och kända behörigheter

Använd BuiltInChatRoles när du tilldelar en tjänstedefinierad roll och KnownChatPermission när du skapar en anpassad roll. Behörighetssträngar utanför de kända värdena accepteras också för framåtkompatibilitet.

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

Hantera roller

Skapa en anpassad roll, hämta den, lista rollerna i hubben och ta bort den anpassade rollen när du är klar.

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

Sköt ett rum

Skapa ett rum, hämta dess nuvarande tillstånd och radera det.

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

Hantera en användare

Skapa en användare med en inbyggd roll, hämta profilen och ta bort den.

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

Lista meddelanden i en konversation

Använd asynkron iteration för att läsa meddelanden från en konversation över alla resultatsidor.

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

Generera en klientåtkomsttoken

Generera en URL som en chattklient kan använda för att ansluta till Web PubSub-tjänsten som en specifik användare.

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

Loggning / Skogsavverkning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokument för @azure/logger-paket.

Contributing

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

  • Uppdaterades senast