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

La libreria client Azure Web PubSub Chat consente alle applicazioni server di gestire ruoli di chat, utenti, stanze, abbonamenti alle stanze, conversazioni e messaggi in un hub di chat Azure Web PubSub.

Come iniziare

Ambienti attualmente supportati

Per altri dettagli, vedere i criteri di supporto .

Prerequisiti

Installare il pacchetto @azure/web-pubsub-chat

Installa la libreria client Azure WebPubSubChatService per JavaScript con npm:

npm install @azure/web-pubsub-chat

Creare ed autenticare un WebPubSubChatServiceClient

Supporta WebPubSubChatServiceClient l'autenticazione con una stringa di connessione, una credenziale Microsoft Entra o un AzureKeyCredential.

Autenticare con una stringa di connessione

Puoi trovare la stringa di connessione per la tua risorsa Azure Web PubSub nell'portale di Azure. Poiché la stringa di connessione contiene una chiave di accesso, memorizzarla in modo sicuro e non includerla nel codice sorgente.

Eseguire l'autenticazione con Microsoft Entra ID

Per autenticarti con Microsoft Entra ID, avrai bisogno della endpoint tua risorsa Azure Web PubSub e di una credenziale. Puoi trovare il punto finale nell'portale di Azure.

Puoi autenticarti con Microsoft Entra ID usando una credenziale dalla libreria @azure/identity o da un token Microsoft Entra esistente.

Per usare il provider DefaultAzureCredential illustrato di seguito o altri provider di credenziali forniti con Azure SDK, installare il pacchetto @azure/identity:

npm install @azure/identity

DefaultAzureCredentialsupporta diverse identità Microsoft Entra. Durante lo sviluppo locale, può utilizzare un'identità di sviluppatore effettuata tramite uno strumento di sviluppo supportato. In Azure, può utilizzare un'identità gestita. Può anche autenticare un'identità di main principale o di carico di lavoro quando configurata per l'ambiente.

Qualunque identità tu utilizzi deve essere assegnata a un ruolo appropriato Azure Web PubSub data-plane. I ruoli di gestione delle risorse Azure, come Owner esempio, non concedono permessi ai piani dati.

Crea il client con una stringa di connessione, una credenziale Microsoft Entra come DefaultAzureCredential, o un 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>",
);

Concetti chiave

WebPubSubChatServiceClient

WebPubSubChatServiceClient è l'interfaccia principale per la gestione delle risorse di chat in un hub Web PubSub.

Hub

Un hub è il confine logico per un'applicazione di chat. Ruoli, utenti, stanze, conversazioni e messaggi gestiti da un client appartengono tutti all'hub fornito al constructor client.

Ruoli e autorizzazioni

Un ruolo utente controlla le azioni a livello di hub come la creazione delle stanze. Un ruolo di stanza controlla le azioni all'interno di una stanza, come pubblicare messaggi, leggere la cronologia dei messaggi o invitare gli utenti.

Stanze, membri e conversazioni

Una stanza contiene membri e ha una conversazione predefinita. Aggiungi un utente a una stanza assegnandogli un ruolo nella stanza. I messaggi sono pubblicati dai client di chat connessi e possono essere elencati, aggiornati o cancellati tramite il client del servizio.

Tag di entità

Le risorse di chat includono un etag valore. Passa quel valore attraverso l'opzione di un'operazione ifMatch per eseguire un aggiornamento condizionale o una cancellazione e evita di sovrascrivere una versione di risorsa più recente.

Esempi

Imposta ruoli, un utente e una stanza

Crea ruoli utente e room, crea un user umano e una stanza, e poi aggiungi l'utente alla stanza.

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

Usa ruoli integrati e permessi noti

Da usare BuiltInChatRoles quando assegni un ruolo definito dal servizio e KnownChatPermission quando crei un ruolo personalizzato. Sono accettate anche stringhe di permessi al di fuori dei valori noti per la compatibilità forward.

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

Gestire i ruoli

Crea un ruolo personalizzato, recuperalo, elenca i ruoli nell'hub e elimina il ruolo personalizzato una volta finito.

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

Gestire una stanza

Crea una stanza, recupera il suo stato attuale e cancella.

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

Gestire un utente

Crea un utente con un ruolo integrato, recupera il profilo ed eliminalo.

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

Elenca i messaggi in una conversazione

Usa l'iterazione asincrona per leggere i messaggi di una conversazione su tutte le pagine dei risultati.

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

Genera un token di accesso client

Genera un URL che un client di chat possa usare per connettersi al servizio Web PubSub come utente specifico.

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

Registrazione

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Contributing

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

  • Last updated on