Azure Web PubSub Chat biblioteca cliente para JavaScript - versión 1.0.0-beta.1

La biblioteca cliente de Azure Web PubSub Chat permite a las aplicaciones servidor gestionar roles de chat, usuarios, salas, membresía en salas, conversaciones y mensajes en un hub de chat de Azure Web PubSub.

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 nombre de hub para la aplicación de chat.

Instalación del paquete @azure/web-pubsub-chat

Instala la biblioteca cliente Azure WebPubSubChatService para JavaScript con npm:

npm install @azure/web-pubsub-chat

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

DefaultAzureCredentialsoporta 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

WebPubSubChatServiceClient

WebPubSubChatServiceClient es la interfaz principal para gestionar los recursos de chat en un hub Web PubSub.

Hub

Un hub es el límite lógico para una aplicación de chat. Roles, usuarios, salas, conversaciones y mensajes gestionados por un cliente pertenecen todos al hub proporcionado al constructor del cliente.

Roles y permisos

Un rol de usuario controla acciones a nivel de hub, como crear habitaciones. Un rol de sala controla acciones dentro de una sala, como publicar mensajes, leer el historial de mensajes o invitar a usuarios.

Salas, miembros y conversaciones

Una sala contiene miembros y tiene una conversación predeterminada. Añade un usuario a una sala asignándole un rol de sala. Los mensajes son publicados por clientes de chat conectados y pueden ser listados, actualizados o eliminados a través del cliente de servicio.

Etiquetas de entidad

Los recursos de chat tienen un etag valor. Pasar ese valor por la opción de ifMatch una operación para realizar una actualización condicional o eliminar y evitar sobrescribir una versión de recurso más reciente.

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.

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

Listar mensajes en una conversación

Utiliza iteraciones asíncronas para leer mensajes de una conversación en todas las páginas de resultados.

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

Troubleshooting

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.

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.

  • Last updated on