Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
La biblioteca cliente de Azure Web PubSub Chat permite a las aplicaciones de servidor gestionar roles de chat, usuarios, salas, temas, membresía en salas, conversaciones y mensajes en un hub de chat de Azure Web PubSub. Úsalo para organizar las discusiones por temas de sala, descubrir usuarios y sus salas, y gestionar recursos de chat desde tu aplicación de servidor.
Vínculos clave:
Cómo empezar
Entornos admitidos actualmente
Consulte nuestra de directiva de soporte técnico de para obtener más información.
Prerequisites
- Una suscripción de Azure.
- Un recurso existente de Azure Web PubSub.
- Un hub configurado con Chat habilitado y almacenamiento persistente.
Instalación del paquete @azure/web-pubsub-chat
Instala la biblioteca cliente Azure WebPubSubChatService para JavaScript con npm:
npm install @azure/web-pubsub-chat
Configurar TypeScript
Este paquete incluye declaraciones TypeScript. Para Node.js aplicaciones escritas en TypeScript, instale las definiciones de tipo Node.js:
npm install --save-dev @types/node
No se requieren configuraciones adicionales específicas del compilador para cada paquete.
Creación y autenticación de un WebPubSubChatServiceClient
Soporta WebPubSubChatServiceClient autenticación con una cadena de conexión, una credencial Microsoft Entra o un AzureKeyCredentialarchivo .
Autenticar con una cadena de conexión
Puedes encontrar la cadena de conexión para tu recurso de Azure Web PubSub en Azure Portal. Como la cadena de conexión contiene una clave de acceso, guárdala de forma segura y no incluirla en el código fuente.
Autenticación con Microsoft Entra ID
Para autenticarte con Microsoft Entra ID, necesitarás el endpoint recurso de tu Azure Web PubSub y una credencial. Puedes encontrar el endpoint en el Azure Portal.
Puedes autenticarte con Microsoft Entra ID usando una credencial de la biblioteca @azure/identity o un token Microsoft Entra existente.
Para usar el proveedor de de DefaultAzureCredential que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, instale el paquete de @azure/identity:
npm install @azure/identity
DefaultAzureCredentialadmite varias identidades de Microsoft Entra. Durante el desarrollo local, puede utilizar una identidad de desarrollador iniciada a través de una herramienta de desarrollo soportada. En Azure, puede usar una identidad gestionada. También puede autenticar una identidad de principal de servicio o carga de trabajo cuando está configurada para el entorno.
La identidad que utilices debe tener asignado un rol apropiado en Azure Web PubSub en el plano de datos. Los roles de gestión de recursos de Azure, como Owner no conceden permisos en el plano de datos.
Crea el cliente con una cadena de conexión, una credencial de Microsoft Entra como DefaultAzureCredential, o un AzureKeyCredentialarchivo .
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>",
);
Conceptos clave
Hub
Un hub es una colección lógica de conexiones WebSocket. Un centro de chat añade salas integradas, gestión de miembros, persistencia de mensajes y APIs específicas para cada chat.
Este SDK se aplica solo a los chats hubs. El chat debe estar habilitado en el hub de destino antes de que el SDK pueda gestionar roles, usuarios, salas, miembros, conversaciones o mensajes.
Rol y permiso
Un rol es una colección nombrada de permisos de chat. Los nombres de roles de usuario empiezan con user., y los nombres de roles de sala comienzan con room.. No combine permisos de usuario y de sala en un solo rol.
Los roles de usuario controlan operaciones como la creación de salas. Los roles de sala controlan lo que un miembro puede hacer en una sala concreta, como publicar mensajes o leer el historial de mensajes.
User
Un usuario representa una identidad que participa en el chat, como un usuario final humano o una aplicación. Las credenciales de acceso de cliente asocian las conexiones WebSocket con un ID de usuario.
Sala
Una sala agrupa a los usuarios y es la unidad organizativa principal para las interacciones en chat. Cada sala tiene una conversación predeterminada creada automáticamente.
Miembro de la sala
Un miembro de sala representa a un usuario añadido a una sala. La membresía controla qué usuarios pueden recibir y enviar mensajes en la sala. En la API de servicio, a cada miembro de la sala se le asigna un rol de sala.
Historial de conversaciones y mensajes
Una conversación es un flujo ordenado de mensajes dentro de una sala. Cada sala tiene una conversación predeterminada, y se pueden crear conversaciones adicionales con nombre a través de los temas.
Los mensajes enviados a una conversación se entregan en tiempo real a los miembros conectados de la sala. El servicio de chat gestiona el pedido y la persistencia, permitiendo a los miembros cargar el historial de mensajes tras reconectarse o unirse más tarde. El cliente de servicio puede listar, actualizar y eliminar mensajes persistentes.
Topic
Un tema representa una conversación con nombre dentro de una sala. Los temas pueden crearse, renombrarse, archivarse y eliminarse de forma informal independientemente de la conversación predeterminada de la sala.
Examples
Configura roles, un usuario y una sala
Crea roles de usuario y sala, crea un usuario humano y una sala, y luego añade al usuario a la sala.
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}`);
Utiliza roles integrados y permisos conocidos
Utilízalo BuiltInChatRoles al asignar un rol definido por un servicio y KnownChatPermission al crear un rol personalizado. También se aceptan cadenas de permisos fuera de los valores conocidos para garantizar la compatibilidad hacia adelante.
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,
],
});
Administración de roles
Crea un rol personalizado, recupéralo, lista los roles en el hub y elimina el rol personalizado cuando termines.
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);
}
Gestionar una habitación
Crea una habitación, recupera su estado actual y bórrala.
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);
Gestionar un usuario
Crea un usuario con un rol incorporado, recupera el perfil y elimíralo.
La solicitud acepta HumanChatUserCreateOrReplace, lo que requiere kind: "Human", nickname, y roleName. Los perfiles devueltos conservan los campos de recursos y pueden representar tipos de usuario desconocidos.
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);
Actualizar un mensaje
Al actualizar un mensaje, ChatMessageUpdate.createdBy y content son opcionales.
Suministra solo los campos que deben cambiar; los campos omitidos conservan sus valores actuales.
Listar mensajes en una conversación
Utiliza la iteración asíncrona para leer mensajes de una conversación en todas las páginas de resultados, desde la más reciente hasta la más antigua. Los ID de mensaje son cursores de paginación: el iterador sigue al del servicio nextLink, que contiene el siguiente cursor de ID de mensaje. Para reanudar más tarde, guarda la de continuationToken una página y pásala a byPage({ continuationToken }); usa el token devuelto sin cambios en lugar de pasar un ID de mensaje sin cambios.
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}`);
}
Generar un token de acceso al cliente
Genera una URL que un cliente de chat pueda usar para conectarse al servicio Web PubSub como usuario específico.
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" });
Listar habitaciones en un hub
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}`);
}
Listar usuarios en un hub
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}`);
}
Lista las habitaciones de un usuario
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}`);
}
Crear un tema
Crea un tema en una sala existente. El servicio crea la conversación asociada.
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}`);
Obtener un tema
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}`);
Actualizar un tema
Archiva un tema existente sin cambiar su título. Sustituir <etag> por su etiqueta de entidad actual.
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}`);
Enumerar temas en una sala
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})`);
}
Paginación de temas de currículum
Las operaciones de lista aceptan tokens de continuación a través de byPage({ continuationToken }), no a través de las opciones del método list. Pasa el token devuelto en una página sin cambios.
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);
}
}
Eliminación de un tema
Eliminar suavemente un tema existente. Sustituir <etag> por su etiqueta de entidad actual.
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
Errores de servicio y solicitudes condicionales
Se producen RestError fallos de servicio con un statusCode. HTTP 404 indica un recurso ausente, incluido un tema eliminado. HTTP 412 indica que una ifMatchifNoneMatch precondición o OR falló. Recupere el recurso actual y revise su etiqueta de entidad antes de intentar de nuevo una escritura condicional. Úsalo ifNoneMatch: "*" al crear un recurso solo si aún no existe.
Registro
Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en el @azure/logger:
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.
Pasos siguientes
Explora los ejemplos de JavaScript y TypeScript y la referencia de la API.
Contributing
Si desea contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.
Azure SDK for JavaScript