Compartir a través de

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

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

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

npm install @azure/web-pubsub

2. Crear y autenticar un WebPubSubServiceClient

import { WebPubSubServiceClient } from "@azure/web-pubsub";

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

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

import { AzureKeyCredential, WebPubSubServiceClient } from "@azure/web-pubsub";

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

O autentique el WebPubSubServiceClient 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:
import { DefaultAzureCredential } from "@azure/identity";
import { WebPubSubServiceClient } from "@azure/web-pubsub";

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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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"] });

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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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.

import { WebPubSubServiceClient, odata } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

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

function onResponse(rawResponse) {
  console.log(rawResponse);
}

await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

Solución de problemas

Habilitación de registros

La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info.

export AZURE_LOG_LEVEL=verbose

Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en @azure/logger:

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos del paquete @azure/logger.

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.