Compartir a través de

Biblioteca cliente del servicio Azure Web PubSub para JavaScript: versión 1.1.3

  • Artículo

servicio Azure Web PubSub es un servicio administrado por Azure que ayuda a los desarrolladores a crear fácilmente aplicaciones web con características en tiempo real y patrón de publicación y suscripción. Cualquier escenario que requiera mensajería de publicación y suscripción en tiempo real entre el servidor y los clientes o entre clientes puede usar el servicio Azure Web PubSub. Las características tradicionales en tiempo real que a menudo requieren sondeo desde el servidor o el envío de solicitudes HTTP también pueden usar el servicio Azure Web PubSub.

Puede usar esta biblioteca en el lado servidor de la aplicación para administrar las conexiones de cliente de WebSocket, como se muestra en el diagrama siguiente:

desbordamiento .

  • Enviar mensajes a centros y grupos.
  • Enviar mensajes a usuarios y conexiones concretos.
  • Organice los usuarios y las conexiones en grupos.
  • Cerrar conexiones
  • Concesión, revocación y comprobación de permisos para una conexión existente

Los detalles sobre los términos que se usan aquí se describen en sección Conceptos clave.

documentación de referencia de | Package (NPM) | API | Documentación del producto | Ejemplos

Empezar

Entornos admitidos actualmente

Prerrequisitos

  • Una suscripción de Azure .
  • Una instancia de servicio de Azure Web PubSub existente.

1. Instalar el paquete de @azure/web-pubsub

npm install @azure/web-pubsub

2. Crear y autenticar un WebPubSubServiceClient

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

También puede autenticar el WebPubSubServiceClient mediante un punto de conexión y un AzureKeyCredential:

const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");

const key = new AzureKeyCredential("<Key>");
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

O autentique el mediante de Azure Active Directory

  1. Instalación de la dependencia de @azure/identity
npm install @azure/identity
  1. Actualice el código fuente para usar DefaultAzureCredential:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const { DefaultAzureCredential } = require("@azure/identity");

const key = new DefaultAzureCredential();
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

Conceptos clave

Conexión

Una conexión, también conocida como un cliente o una conexión de cliente, representa una conexión WebSocket individual conectada al servicio Web PubSub. Cuando se conecta correctamente, el servicio Web PubSub asigna un identificador de conexión único a esta conexión.

Concentrador

Un concentrador es un concepto lógico para un conjunto de conexiones de cliente. Normalmente, se usa un concentrador para un propósito, por ejemplo, un centro de chat o un centro de notificaciones. Cuando se crea una conexión de cliente, se conecta a un centro y, durante su duración, pertenece a ese centro. Las distintas aplicaciones pueden compartir un servicio Azure Web PubSub mediante nombres de concentrador diferentes.

Grupo

Un grupo es un subconjunto de conexiones al centro. Puede agregar una conexión de cliente a un grupo o quitar la conexión de cliente del grupo en cualquier momento que desee. Por ejemplo, cuando un cliente se une a un salón de chat o cuando un cliente sale de la sala de chat, este salón de chat puede considerarse un grupo. Un cliente puede unirse a varios grupos y un grupo puede contener varios clientes.

Usuario

Las conexiones a Web PubSub pueden pertenecer a un usuario. Un usuario puede tener varias conexiones, por ejemplo, cuando un único usuario está conectado entre varios dispositivos o varias pestañas del explorador.

Mensaje

Cuando el cliente está conectado, puede enviar mensajes a la aplicación ascendente o recibir mensajes de la aplicación ascendente a través de la conexión WebSocket.

Ejemplos

Obtención del token de acceso de un cliente para iniciar la conexión de WebSocket

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Get the access token for the WebSocket client connection to use
let token = await serviceClient.getClientAccessToken();

// Or get the access token and assign the client a userId
token = await serviceClient.getClientAccessToken({ userId: "user1" });

// Or get the access token that the client will join group GroupA when it connects using the access token
token = await serviceClient.getClientAccessToken({ userId: "user1", groups: [ "GroupA" ] });

// return the token to the WebSocket client

Difusión de mensajes a todas las conexiones de un centro

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Send a JSON message
await serviceClient.sendToAll({ message: "Hello world!" });

// Send a plain text message
await serviceClient.sendToAll("Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToAll(payload.buffer);

Envío de mensajes a todas las conexiones de un centro con sintaxis de filtro de OData

Para más información sobre filter sintaxis, consulte sintaxis de filtro de OData para Azure Web PubSub.

const { WebPubSubServiceClient, odata } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Send a JSON message to anonymous connections
await serviceClient.sendToAll(
  { message: "Hello world!" },
  { filter: "userId eq null" }
  );

// Send a text message to connections in groupA but not in groupB
const groupA = 'groupA';
const groupB = 'groupB';
await serviceClient.sendToAll(
  "Hello world!",
  { 
    contentType: "text/plain",
    // use plain text "'groupA' in groups and not('groupB' in groups)"
    // or use the odata helper method
    filter: odata`${groupA} in groups and not(${groupB} in groups)` 
  });

Enviar mensajes a todas las conexiones de un grupo

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

const groupClient = serviceClient.group("<groupName>");

// Add user to the group
await groupClient.addUser("user1");

// Send a JSON message
await groupClient.sendToAll({ message: "Hello world!" });

// Send a plain text message
await groupClient.sendToAll("Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await groupClient.sendToAll(payload.buffer);

Enviar mensajes a todas las conexiones de un usuario

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Send a JSON message
await serviceClient.sendToUser("user1", { message: "Hello world!" });

// Send a plain text message
await serviceClient.sendToUser("user1", "Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToUser("user1", payload.buffer);

Compruebe si el grupo tiene alguna conexión

const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const WebSocket = require("ws");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

const groupClient = serviceClient.group("<groupName>");

// close all the connections in the group
await groupClient.closeAllConnections({ reason: "<closeReason>" });

// check if the group has any connections
const hasConnections = await serviceClient.groupExists("<groupName>");

Acceso a la respuesta HTTP sin procesar para una operación

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

function onResponse(rawResponse) {
  console.log(rawResponse);
}
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

Solución de problemas

Habilitación de registros

Puede establecer la siguiente variable de entorno para obtener los registros de depuración al usar esta biblioteca.

  • Obtención de registros de depuración de la biblioteca cliente de SignalR
export AZURE_LOG_LEVEL=verbose

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.

Seguimiento dinámico

Use live Trace desde el portal del servicio Web PubSub para ver el tráfico activo.

Pasos siguientes

Eche un vistazo al directorio ejemplos para obtener ejemplos detallados sobre cómo usar esta biblioteca.

Contribuyendo

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.