Compartir vía

SDK de JavaScript para Azure Web PubSub

El 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.

Hay dos bibliotecas que se ofrecen para JavaScript: la biblioteca de cliente del servicio y el middleware de Express. Las secciones siguientes contienen más información sobre estas bibliotecas.

Biblioteca cliente del servicio Azure Web PubSub para JavaScript

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:

El diagrama de desbordamiento muestra el desbordamiento que supone el uso de la biblioteca cliente del servicio.

  • 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

Código fuente | Paquete (NPM) | Documentación | Documentación | del productoMuestras

Cómo empezar

Entornos admitidos actualmente

Prerrequisitos

1. Instalar el @azure/web-pubsub paquete

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 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 autentíquelo WebPubSubServiceClient mediante el identificador de Entra de Microsoft

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

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

Examples

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

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

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: FullOperationResponse): void {
  console.log(rawResponse);
}
const serviceClient = new WebPubSubServiceClient(
  "<ConnectionString>",
  "<hubName>"
);
await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

Solución de problemas del cliente de servicio

Habilitación de registros

Puede establecer la siguiente variable de entorno para obtener los registros de depuración cuando se usa esta biblioteca.

  • Obtención de registros de depuración de la biblioteca cliente de Azure Web PubSub
export AZURE_LOG_LEVEL=verbose

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

Seguimiento en vivo

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

Controladores de CloudEvents de Azure Web PubSub para Express

Cuando se conecta una conexión WebSocket, el servicio Web PubSub transforma el ciclo de vida de la conexión y los mensajes en eventos en formato CloudEvents. Esta biblioteca proporciona un middleware rápido para controlar eventos que representan el ciclo de vida y los mensajes de la conexión de WebSocket, como se muestra en el diagrama siguiente:

El diagrama de desbordamiento muestra el desbordamiento del uso del middleware para controladores de eventos.

Código fuente | Paquete (NPM) | Documentación | Documentación | del productoMuestras

Cómo empezar

Entornos admitidos actualmente

Prerrequisitos

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

npm install @azure/web-pubsub-express

2. Crear un WebPubSubEventHandler

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat");

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Ejemplos concisos

Gestionar la connect solicitud y la asignación de <userId>

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      userId: "<userId>",
    });
  },
  allowedEndpoints: ["https://<yourAllowedService>.webpubsub.azure.com"],
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Permitir solo puntos de conexión especificados

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  allowedEndpoints: [
    "https://<yourAllowedService1>.webpubsub.azure.com",
    "https://<yourAllowedService2>.webpubsub.azure.com",
  ],
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Configurar la ruta de acceso del controlador de eventos personalizado

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  path: "/customPath1",
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  // Azure WebPubSub Upstream ready at http://localhost:3000/customPath1
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Establecimiento y lectura del estado de conexión

const express = require("express");

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

const handler = new WebPubSubEventHandler("chat", {
  handleConnect(req, res) {
    // You can set the state for the connection, it lasts throughout the lifetime of the connection
    res.setState("calledTime", 1);
    res.success();
  },
  handleUserEvent(req, res) {
    var calledTime = req.context.states.calledTime++;
    console.log(calledTime);
    // You can also set the state here
    res.setState("calledTime", calledTime);
    res.success();
  },
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Solución de problemas

Habilitación de registros

Puede establecer la siguiente variable de entorno para obtener los registros de depuración cuando se usa esta biblioteca.

  • Obtención de registros de depuración de la biblioteca cliente de Azure Web PubSub
export AZURE_LOG_LEVEL=verbose

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos de paquetes de @azure/registrador.

Seguimiento en vivo

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

Pasos siguientes

Use estos recursos para empezar a compilar su propia aplicación:

Tutorial: Publicación y suscripción de mensajes en Azure Web PubSub

Tutorial: Creación de una sala de chat simple con Azure Web PubSub

Tutorial: Uso de un subprotocolo compatible con el servicio para streaming de clientes

Tutorial: Creación de chat sin servidor con Azure Functions y Web PubSub

Tutorial: Configuración de un cliente de escucha de eventos

Reproducción con demostraciones dinámicas

Explore más ejemplos de Azure Web PubSub.

  • Last updated on