Tutorial: Creación de una aplicación de chat con el servicio Azure Web PubSub

En el tutorial sobre publicación de mensajes y suscripción a ellos, aprenderá los conceptos básicos de la publicación de mensajes y la suscripción a ellos con Azure Web PubSub. En este tutorial, conocerá y aprenderá a usar el sistema de eventos de Azure Web PubSub para compilar una aplicación web completa con funcionalidad de comunicación en tiempo real.

En este tutorial, aprenderá a:

• Crear una instancia del servicio Web PubSub
• Configurar opciones del controlador de eventos para Azure Web PubSub
• Control de eventos en el servidor de aplicaciones y compilación de una aplicación de chat en tiempo real

Si no tiene una suscripción a Azure, cree una cuenta gratuita de Azure antes de empezar.

Requisitos previos

• Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en Azure Cloud Shell.

  

• Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.

  • Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.

  • En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.

  • Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

• Esta configuración requiere la versión 2.22.0, o cualquier versión superior, de la CLI de Azure. Si usa Azure Cloud Shell, ya está instalada la versión más reciente.

Creación de una instancia de Azure Web PubSub

Crear un grupo de recursos

Un grupo de recursos es un contenedor lógico en el que se implementan y se administran los recursos de Azure. Use el comando az group create para crear un grupo de recursos denominado myResourceGroup en la ubicación eastus.

az group create --name myResourceGroup --location EastUS

Creación de una instancia de Web PubSub

Ejecute az extension add para instalar o actualizar la extensión webpubsub en la versión actual.

az extension add --upgrade --name webpubsub

Use el comando az webpubsub create de la CLI de Azure para crear una instancia de Web PubSub en el grupo de recursos que ha creado. El comando siguiente crea un recurso Free de Web PubSub en el grupo de recursos myResourceGroup en EastUS:

Importante

Cada recurso de Web PubSub debe tener un nombre único. Reemplace <your-unique-resource-name> por el nombre de Web PubSub en los ejemplos siguientes.

az webpubsub create --name "<your-unique-resource-name>" --resource-group "myResourceGroup" --location "EastUS" --sku Free_F1

La salida de este comando muestra las propiedades del recurso que acaba de crear. Tome nota de las dos propiedades siguientes:

• Nombre del recurso: nombre que proporcionó al parámetro --name anterior.
• hostName: en el ejemplo, el nombre de host es <your-unique-resource-name>.webpubsub.azure.com/.

En este momento, su cuenta de Azure es la única autorizada para realizar operaciones en este nuevo recurso.

Obtención de ConnectionString para usarlo en el futuro

Importante

Las cadenas de conexión sin procesar solo aparecen en este artículo con fines de demostración.

Una cadena de conexión incluye la información de autorización necesaria para que la aplicación acceda al servicio Azure Web PubSub. La clave de acceso dentro de la cadena de conexión es similar a una contraseña raíz para el servicio. En entornos de producción, proteja siempre las claves de acceso. Use Azure Key Vault para administrar y rotar las claves de forma segura y proteja la conexión con WebPubSubServiceClient.

Evite distribuirlas a otros usuarios, codificarlas de forma rígida o guardarlas en un archivo de texto sin formato al que puedan acceder otros usuarios. Rote sus claves si cree que se han puesto en peligro.

Use el comando az webpubsub key de la CLI de Azure para obtener el valor de ConnectionString del servicio. Reemplace el marcador de posición <your-unique-resource-name> por el nombre de la instancia de Azure Web PubSub.

az webpubsub key show --resource-group myResourceGroup --name <your-unique-resource-name> --query primaryConnectionString --output tsv

Copie la cadena de conexión para usarla más adelante.

Copie el ConnectionString capturado y establézcalo en la variable de entorno WebPubSubConnectionString, que el tutorial leerá más adelante. Reemplace <connection-string> por el ConnectionString que ha capturado.

export WebPubSubConnectionString="<connection-string>"

SET WebPubSubConnectionString=<connection-string>

Configuración del proyecto

Prerrequisitos

C#

• ASP.NET Core 8

JavaScript

• Node.js 12.x, o cualquier versión superior

Java

• Kit de desarrollo de Java (JDK), versión 8 o posterior
• Apache Maven

Python

• Python 3.8 o versiones posteriores

Creación de la aplicación

En Azure Web PubSub, hay dos roles: servidor y cliente. Este concepto es similar a los roles de servidor y cliente de una aplicación web. El servidor es responsable de administrar los clientes, escuchar y responder a los mensajes de los clientes. El cliente es responsable de enviar y recibir los mensajes del usuario desde el servidor y visualizarlos para el usuario final.

En este tutorial, compilaremos una aplicación web de chat en tiempo real. En una aplicación web real, la responsabilidad del servidor también incluye autenticar los clientes y proporcionar las páginas web estáticas para la interfaz de usuario de la aplicación.

C#

Usaremos ASP.NET Core 8 para hospedar las páginas web y administrar las solicitudes entrantes.

En primer lugar, vamos a crear una aplicación web de ASP.NET Core en una carpeta chatapp.

1. Cree una aplicación web nueva.

   mkdir chatapp
   cd chatapp
   dotnet new web
   

2. Agregue Program.cs app.UseStaticFiles() para admitir el hospedaje de páginas web estáticas.

   var builder = WebApplication.CreateBuilder(args);
   var app = builder.Build();
   
   app.UseStaticFiles();
   
   app.Run();
   

3. Cree un archivo HTML y guárdelo como wwwroot/index.html; lo usaremos para la interfaz de usuario de la aplicación de chat más adelante.

   <html>
     <body>
       <h1>Azure Web PubSub Chat</h1>
     </body>
   </html>
   

Ejecute dotnet run --urls http://localhost:8080 para probar el servidor y acceda a http://localhost:8080/index.html en el explorador.

JavaScript

Utilizamos express.js, un marco web popular para Node.js para hospedar las páginas web y controlar las solicitudes entrantes.

En primer lugar, vamos a crear una aplicación web express en una carpeta chatapp.

1. Instale express.js.

   mkdir chatapp
   cd chatapp
   npm init -y
   npm install --save express
   

2. A continuación, cree un servidor de Express y guárdelo como server.js.

   const express = require('express');
   
   const app = express();
   app.use(express.static('public'));
   app.listen(8080, () => console.log('server started'));
   

3. Cree también un archivo HTML y guárdelo como public/index.html; lo usaremos para la interfaz de usuario de la aplicación de chat más adelante.

   <html>
   
   <body>
     <h1>Azure Web PubSub Chat</h1>
   </body>
   
   </html>
   

Ejecute node server para probar el servidor y acceda a http://localhost:8080 en el explorador.

Java

Usamos el marco web Javalin para hospedar las páginas web y administrar las solicitudes entrantes.

1. Use Maven para crear una nueva aplicación webpubsub-tutorial-chat y cambiar a la carpeta webpubsub-tutorial-chat:

   mvn archetype:generate --define interactiveMode=n --define groupId=com.webpubsub.tutorial --define artifactId=webpubsub-tutorial-chat --define archetypeArtifactId=maven-archetype-quickstart --define archetypeVersion=1.4
   cd webpubsub-tutorial-chat
   

2. Agregue la dependencia del marco web javalin en el nodo dependencies de pom.xml:

   • javalin: marco web simple para Java
   • slf4j-simple: registrador para Java

   <!-- https://mvnrepository.com/artifact/io.javalin/javalin -->
   <dependency>
       <groupId>io.javalin</groupId>
       <artifactId>javalin</artifactId>
       <version>6.1.3</version>
   </dependency>
   
   <!-- https://mvnrepository.com/artifact/org.slf4j/slf4j-simple -->
   <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-simple</artifactId>
       <version>2.0.12</version>
   </dependency>
   

3. Vaya al directorio /src/main/java/com/webpubsub/tutorial. Abra el archivo App.java en el editor. Use Javalin.create para proporcionar archivos estáticos:

   package com.webpubsub.tutorial;
   
   import io.javalin.Javalin;
   
   public class App {
       public static void main(String[] args) {
           // start a server
           Javalin app = Javalin.create(config -> {
               config.staticFiles.add("public");
           }).start(8080);
       }
   }
   

   En función de la configuración, es posible que tenga que establecer explícitamente el nivel de lenguaje en Java 8. Este paso se puede hacer en pom.xml. Agregue el siguiente fragmento:

   <build>
       <plugins>
           <plugin>
             <artifactId>maven-compiler-plugin</artifactId>
             <version>3.8.0</version>
             <configuration>
               <source>1.8</source>
               <target>1.8</target>
             </configuration>
           </plugin>
       </plugins>
   </build>
   

4. Cree un archivo HTML y guárdelo en /src/main/resources/public/index.html. Lo usaremos para la interfaz de usuario de la aplicación de chat más adelante.

   <html>
   <body>
     <h1>Azure Web PubSub Chat</h1>
   </body>
   
   </html>
   

Puede probar el servidor ejecutando el siguiente comando en el directorio que contiene el archivo pom.xml y accediendo a http://localhost:8080 en el explorador.

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.tutorial.App" -Dexec.cleanupDaemonThreads=false

Python

Para este trabajo, usamos Flask, un marco web popular para Python.

En primer lugar, cree una carpeta de proyecto chatapp con Flask listo.

0. Creación y activación del entorno

   mkdir chatapp
   cd chatapp
   python3 -m venv .venv
   . .venv/bin/activate
   

1. En el entorno activado, instale Flask

   pip install Flask
   

2. A continuación, cree un servidor de Flask y guárdelo como server.py

   from flask import (
       Flask, 
       send_from_directory,
   )
   
   app = Flask(__name__)
   
   @app.route('/<path:filename>')
   def index(filename):
       return send_from_directory('public', filename)
   
   if __name__ == '__main__':
       app.run(port=8080)
   

3. Cree también un archivo HTML y guárdelo como public/index.html; lo usaremos para la interfaz de usuario de la aplicación de chat más adelante.

   <html>
   
   <body>
     <h1>Azure Web PubSub Chat</h1>
   </body>
   
   </html>
   

Ejecute python server.py para probar el servidor y acceda a http://127.0.0.1:8080/index.html en el explorador.

Adición de un punto de conexión negotiate

En el tutorial Publicar y suscribir un mensaje, el suscriptor consume directamente la cadena de conexión. En una aplicación real, no es seguro compartir la cadena de conexión con ningún cliente, ya que la cadena de conexión tiene privilegios elevados para realizar cualquier operación en el servicio. Ahora, vamos a hacer que el servidor consuma la cadena de conexión y exponga un punto de conexión negotiate para que el cliente obtenga la dirección URL completa con el token de acceso. De este modo, el servidor puede agregar un middleware de autenticación antes del punto de conexión negotiate para evitar el acceso no autorizado.

C#

En primer lugar, instale las dependencias.

dotnet add package Microsoft.Azure.WebPubSub.AspNetCore

Ahora vamos a agregar un punto de conexión /negotiate para que el cliente llame a para generar el token.

using Azure.Core;
using Microsoft.Azure.WebPubSub.AspNetCore;
using Microsoft.Azure.WebPubSub.Common;
using Microsoft.Extensions.Primitives;

// Read connection string from environment
var connectionString = Environment.GetEnvironmentVariable("WebPubSubConnectionString");
if (connectionString == null)
{
    throw new ArgumentNullException(nameof(connectionString));
}

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddWebPubSub(o => o.ServiceEndpoint = new WebPubSubServiceEndpoint(connectionString))
    .AddWebPubSubServiceClient<Sample_ChatApp>();
var app = builder.Build();

app.UseStaticFiles();

// return the Client Access URL with negotiate endpoint
app.MapGet("/negotiate", (WebPubSubServiceClient<Sample_ChatApp> service, HttpContext context) =>
{
    var id = context.Request.Query["id"];
    if (StringValues.IsNullOrEmpty(id))
    {
        context.Response.StatusCode = 400;
        return null;
    }
    return new
    {
        url = service.GetClientAccessUri(userId: id).AbsoluteUri
    };
});
app.Run();

sealed class Sample_ChatApp : WebPubSubHub
{
}

AddWebPubSubServiceClient<THub>() se usa para insertar el cliente de servicio WebPubSubServiceClient<THub>, que se puede usar en el paso de negociación para generar el token de conexión de cliente y en los métodos del centro para invocar las API REST del servicio cuando se desencadenan eventos del centro. Este código de generación de tokens es similar al que se usó en el tutorial de publicación de mensajes y suscripción a ellos, salvo que se pasa un argumento más (userId) al generar el token. El identificador de usuario se puede usar para obtener la identidad del cliente, de modo que, cuando reciba un mensaje, sabrá de dónde viene.

El código lee la cadena de conexión de la variable de entorno WebPubSubConnectionString que establecimos en el paso anterior.

Vuelva a ejecutar el servidor mediante dotnet run --urls http://localhost:8080.

JavaScript

En primer lugar, instale el SDK de Azure Web PubSub:

npm install --save @azure/web-pubsub

Ahora vamos a agregar una API de /negotiate para generar el token.

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

const app = express();
const hubName = 'Sample_ChatApp';

let serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hubName);

app.get('/negotiate', async (req, res) => {
    let id = req.query.id;
    if (!id) {
    res.status(400).send('missing user id');
    return;
    }
    let token = await serviceClient.getClientAccessToken({ userId: id });
    res.json({
    url: token.url
    });
});

app.use(express.static('public'));
app.listen(8080, () => console.log('server started'));

Este código de generación de tokens es similar al que se usó en el tutorial de publicación de mensajes y suscripción a ellos, salvo que se pasa un argumento más (userId) al generar el token. El identificador de usuario se puede usar para obtener la identidad del cliente, de modo que, cuando reciba un mensaje, sabrá de dónde viene.

El código lee la cadena de conexión de la variable de entorno WebPubSubConnectionString que establecimos en el paso anterior.

Vuelva a ejecutar el servidor ejecutando node server.

Java

En primer lugar, agregue la dependencia del SDK de Azure Web PubSub y gson al nodo dependencies de pom.xml:

<!-- https://mvnrepository.com/artifact/com.azure/azure-messaging-webpubsub -->
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.2.12</version>
</dependency>
<!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>

Ahora vamos a agregar una API de /negotiate al archivo App.java para generar el token:

package com.webpubsub.tutorial;
    
import com.azure.messaging.webpubsub.WebPubSubServiceClient;
import com.azure.messaging.webpubsub.WebPubSubServiceClientBuilder;
import com.azure.messaging.webpubsub.models.GetClientAccessTokenOptions;
import com.azure.messaging.webpubsub.models.WebPubSubClientAccessToken;
import com.azure.messaging.webpubsub.models.WebPubSubContentType;
import com.google.gson.Gson;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import io.javalin.Javalin;

public class App {
    public static void main(String[] args) {
        String connectionString = System.getenv("WebPubSubConnectionString");

        if (connectionString == null) {
            System.out.println("Please set the environment variable WebPubSubConnectionString");
            return;
        }

        // create the service client
        WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
                .connectionString(connectionString)
                .hub("Sample_ChatApp")
                .buildClient();

        // start a server
        Javalin app = Javalin.create(config -> {
            config.staticFiles.add("public");
        }).start(8080);
        
        // Handle the negotiate request and return the token to the client
        app.get("/negotiate", ctx -> {
            String id = ctx.queryParam("id");
            if (id == null) {
                ctx.status(400);
                ctx.result("missing user id");
                return;
            }
            GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
            option.setUserId(id);
            WebPubSubClientAccessToken token = service.getClientAccessToken(option);
            ctx.contentType("application/json");
            Gson gson = new Gson();
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("url", token.getUrl());
            String response = gson.toJson(jsonObject);
            ctx.result(response);
            return;
        });
    }
}

Este código de generación de tokens es similar al que se usó en el tutorial de publicación de mensajes y suscripción a ellos, salvo que se llama al método setUserId para establecer el ID de usuario al generar el token. El identificador de usuario se puede usar para obtener la identidad del cliente, de modo que, cuando reciba un mensaje, sabrá de dónde viene.

El código lee la cadena de conexión de la variable de entorno WebPubSubConnectionString que establecimos en el paso anterior.

Vuelva a ejecutar el servidor con los siguientes comandos:

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.tutorial.App" -Dexec.cleanupDaemonThreads=false

Python

En primer lugar, instale el SDK de Azure Web PubSub.

pip install azure-messaging-webpubsubservice

Ahora vamos a agregar una API de /negotiate al servidor para generar el token.

import os

from flask import (
    Flask, 
    request, 
    send_from_directory,
)

from azure.messaging.webpubsubservice import (
    WebPubSubServiceClient
)

hub_name = 'Sample_ChatApp'
connection_string = os.environ.get('WebPubSubConnectionString')

app = Flask(__name__)
service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)

@app.route('/<path:filename>')
def index(filename):
    return send_from_directory('public', filename)


@app.route('/negotiate')
def negotiate():
    id = request.args.get('id')
    if not id:
        return 'missing user id', 400

    token = service.get_client_access_token(user_id=id)
    return {
        'url': token['url']
    }, 200

if __name__ == '__main__':
    app.run(port=8080)

Este código de generación de tokens es similar al que se usó en el tutorial de publicación de mensajes y suscripción a ellos, salvo que se pasa un argumento más (user_id) al generar el token. El identificador de usuario se puede usar para obtener la identidad del cliente, de modo que, cuando reciba un mensaje, sabrá de dónde viene.

El código lee la cadena de conexión de la variable de entorno WebPubSubConnectionString que establecimos en el paso anterior.

Vuelva a ejecutar el servidor mediante python server.py.

Puede probar esta API accediendo a http://localhost:8080/negotiate?id=user1 y le proporcionará la dirección URL completa de Azure Web PubSub con un token de acceso.

Control de eventos

En Azure Web PubSub, cuando se producen determinadas actividades en el lado cliente (por ejemplo, un cliente está conectando, conectado, desconectado o enviando mensajes), el servicio envía notificaciones al servidor para que pueda reaccionar a estos eventos.

Los eventos se entregan al servidor en forma de webhook. El servidor de aplicaciones sirve y expone el webhook, que se registra en el lado del servicio Azure Web PubSub. El servicio invoca los webhooks cada vez que se produce un evento.

Azure Web PubSub sigue CloudEvents para describir los datos del evento.

A continuación se controlan los eventos del sistema connected cuando un cliente está conectado y se controlan los eventos de usuario message cuando un cliente envía mensajes para compilar la aplicación de chat.

C#

El SDK de Web PubSub para AspNetCore Microsoft.Azure.WebPubSub.AspNetCore que instalamos en el paso anterior también podría ayudar a analizar y procesar las solicitudes de CloudEvents.

En primer lugar, agregue controladores de eventos antes de app.Run(). Especifique la ruta de acceso del punto de conexión para los eventos; por ejemplo, /eventhandler.

app.MapWebPubSubHub<Sample_ChatApp>("/eventhandler/{*path}");
app.Run();

Ahora, dentro de la clase Sample_ChatApp que creamos en el paso anterior, agregue un constructor para trabajar con el WebPubSubServiceClient<Sample_ChatApp> que usamos para invocar el servicio Web PubSub. Y OnConnectedAsync() para responder cuando se desencadena el evento connected, OnMessageReceivedAsync() para controlar los mensajes del cliente.

sealed class Sample_ChatApp : WebPubSubHub
{
    private readonly WebPubSubServiceClient<Sample_ChatApp> _serviceClient;

    public Sample_ChatApp(WebPubSubServiceClient<Sample_ChatApp> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override async Task OnConnectedAsync(ConnectedEventRequest request)
    {
        Console.WriteLine($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
    }

    public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
    {
        await _serviceClient.SendToAllAsync(RequestContent.Create(
        new
        {
            from = request.ConnectionContext.UserId,
            message = request.Data.ToString()
        }),
        ContentType.ApplicationJson);

        return new UserEventResponse();
    }
}

En el código anterior, usamos el cliente de servicio para difundir un mensaje de notificación en formato JSON a todos los que se unen con SendToAllAsync.

JavaScript

El SDK de Web PubSub para @azure/web-pubsub-express express ayuda a analizar y procesar las solicitudes de CloudEvents.

npm install --save @azure/web-pubsub-express

Actualice server.js con el siguiente código para exponer una API de REST en /eventhandler (lo que se realiza mediante el middleware Express proporcionado por el SDK de Web PubSub) para controlar el evento de cliente conectado:

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

const app = express();
const hubName = "Sample_ChatApp";

let serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hubName);

let handler = new WebPubSubEventHandler(hubName, {
  path: "/eventhandler",
  onConnected: async (req) => {
    console.log(`${req.context.userId} connected`);
  },
  handleUserEvent: async (req, res) => {
    if (req.context.eventName === "message")
      await serviceClient.sendToAll({
        from: req.context.userId,
        message: req.data,
      });
    res.success();
  },
});
app.get("/negotiate", async (req, res) => {
  let id = req.query.id;
  if (!id) {
    res.status(400).send("missing user id");
    return;
  }
  let token = await serviceClient.getClientAccessToken({ userId: id });
  res.json({
    url: token.url,
  });
});

app.use(express.static("public"));
app.use(handler.getMiddleware());

app.listen(8080, () => console.log("server started"));

En el código anterior, onConnected simplemente imprime un mensaje en la consola cuando un cliente está conectado. Puede advertir que usamos req.context.userId para poder ver la identidad del cliente conectado. Y handleUserEvent se invoca cuando un cliente envía un mensaje. Usa WebPubSubServiceClient.sendToAll() para difundir el mensaje en un objeto JSON a todos los clientes. Puede ver que handleUserEvent también tiene un objeto res, donde puede devolver un mensaje al remitente del evento. Aquí simplemente llamaremos a res.success() para que el WebHook devuelva 200 (tenga en cuenta que esta llamada es necesaria incluso si no desea devolver nada al cliente; de lo contrario, el WebHook nunca vuelve y se cierra la conexión de cliente).

Java

Por ahora, debe implementar el controlador de eventos por su cuenta en Java. Los pasos son sencillos, siguiendo las especificaciones de protocolo y se ilustran en la siguiente lista:

1. Agregue el controlador HTTP para la ruta de acceso del controlador de eventos; por ejemplo, /eventhandler.

2. En primer lugar, nos gustaría administrar las solicitudes OPTIONS de protección contra abusos, comprobaremos si el encabezado contiene el encabezado WebHook-Request-Origin y devolveremos el encabezado WebHook-Allowed-Origin. Para simplificar con fines de demostración, devolveremos * para permitir todos los orígenes.

   
   // validation: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
   app.options("/eventhandler", ctx -> {
       ctx.header("WebHook-Allowed-Origin", "*");
   });
   

3. A continuación, nos gustaría comprobar si las solicitudes entrantes son los eventos que esperamos. Supongamos que ahora nos interesa el evento connected del sistema, que debe contener el encabezado ce-type como azure.webpubsub.sys.connected. Agregamos la lógica después de la protección contra abusos para difundir el evento conectado a todos los clientes para que puedan ver quién se unió a la sala de chat.

   // validation: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
   app.options("/eventhandler", ctx -> {
       ctx.header("WebHook-Allowed-Origin", "*");
   });
   
   // handle events: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#events
   app.post("/eventhandler", ctx -> {
       String event = ctx.header("ce-type");
       if ("azure.webpubsub.sys.connected".equals(event)) {
           String id = ctx.header("ce-userId");
           System.out.println(id + " connected.");
       }
       ctx.status(200);
   });
   
   

   En el código anterior, simplemente imprimimos un mensaje en la consola cuando se conecta un cliente. Puede advertir que usamos ctx.header("ce-userId") para poder ver la identidad del cliente conectado.

4. El ce-type del evento message siempre es azure.webpubsub.user.message. Para obtener más información, consulte el Mensaje de evento. Actualizamos la lógica de control de mensajes para que cuando llegue un mensaje lo difundamos en formato JSON a todos los clientes conectados.

   // handle events: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#events
   app.post("/eventhandler", ctx -> {
       String event = ctx.header("ce-type");
       if ("azure.webpubsub.sys.connected".equals(event)) {
           String id = ctx.header("ce-userId");
           System.out.println(id + " connected.");
       } else if ("azure.webpubsub.user.message".equals(event)) {
           String id = ctx.header("ce-userId");
           String message = ctx.body();
           Gson gson = new Gson();
           JsonObject jsonObject = new JsonObject();
           jsonObject.addProperty("from", id);
           jsonObject.addProperty("message", message);
           String messageToSend = gson.toJson(jsonObject);
           service.sendToAll(messageToSend, WebPubSubContentType.APPLICATION_JSON);
       }
       ctx.status(200);
   });
   

Python

Por ahora, debe implementar el controlador de eventos por su cuenta en Python. Los pasos son sencillos, siguiendo las especificaciones de protocolo y se ilustran en la siguiente lista:

1. Agregue el controlador HTTP para la ruta de acceso del controlador de eventos; por ejemplo, /eventhandler.

2. En primer lugar, nos gustaría administrar las solicitudes OPTIONS de protección contra abusos, comprobaremos si el encabezado contiene el encabezado WebHook-Request-Origin y devolveremos el encabezado WebHook-Allowed-Origin. Para simplificar con fines de demostración, devolveremos * para permitir todos los orígenes.

   # validation: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
   @app.route('/eventhandler', methods=['OPTIONS'])
   def handle_event():
       if request.method == 'OPTIONS':
           if request.headers.get('WebHook-Request-Origin'):
               res = Response()
               res.headers['WebHook-Allowed-Origin'] = '*'
               res.status_code = 200
               return res
   

3. A continuación, nos gustaría comprobar si las solicitudes entrantes son los eventos que esperamos. Supongamos que ahora nos interesa el evento connected del sistema, que debe contener el encabezado ce-type como azure.webpubsub.sys.connected. Agregamos la lógica para la protección contra abusos:

   # validation: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
   # handle events: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#events
   @app.route('/eventhandler', methods=['POST', 'OPTIONS'])
   def handle_event():
       if request.method == 'OPTIONS':
           if request.headers.get('WebHook-Request-Origin'):
               res = Response()
               res.headers['WebHook-Allowed-Origin'] = '*'
               res.status_code = 200
               return res
       elif request.method == 'POST':
           user_id = request.headers.get('ce-userid')
           if request.headers.get('ce-type') == 'azure.webpubsub.sys.connected':
               return user_id + ' connected', 200
           else:
               return 'Not found', 404
   

   En el código anterior, simplemente imprimimos un mensaje en la consola cuando se conecta un cliente. Puede advertir que usamos request.headers.get('ce-userid') para poder ver la identidad del cliente conectado.

4. El ce-type del evento message siempre es azure.webpubsub.user.message. Para obtener más información, consulte el Mensaje de evento. Actualizamos la lógica de control de mensajes para que cuando llegue un mensaje lo difundamos a todos los clientes conectados.

   @app.route('/eventhandler', methods=['POST', 'OPTIONS'])
   def handle_event():
       if request.method == 'OPTIONS':
           if request.headers.get('WebHook-Request-Origin'):
               res = Response()
               res.headers['WebHook-Allowed-Origin'] = '*'
               res.status_code = 200
               return res
       elif request.method == 'POST':
           user_id = request.headers.get('ce-userid')
           type = request.headers.get('ce-type')
           if type == 'azure.webpubsub.sys.connected':
               print(f"{user_id} connected")
               return '', 204
           elif type == 'azure.webpubsub.user.message':
               # default uses JSON
               service.send_to_all(message={
                   'from': user_id,
                   'message': request.data.decode('UTF-8')
               })
               # returned message is also received by the client
               return {
                   'from': "system",
                   'message': "message handled by server"
               }, 200
           else:
               return 'Bad Request', 400
   

Actualización de la página web

Ahora vamos a actualizar index.html para agregar la lógica para conectarse, enviar mensajes y mostrar mensajes recibidos en la página.

<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
    <input id="message" placeholder="Type to chat...">
    <div id="messages"></div>
    <script>
      (async function () {
        let id = prompt('Please input your user name');
        let res = await fetch(`/negotiate?id=${id}`);
        let data = await res.json();
        let ws = new WebSocket(data.url);
        ws.onopen = () => console.log('connected');

        let messages = document.querySelector('#messages');
        
        ws.onmessage = event => {
          let m = document.createElement('p');
          let data = JSON.parse(event.data);
          m.innerText = `[${data.type || ''}${data.from || ''}] ${data.message}`;
          messages.appendChild(m);
        };

        let message = document.querySelector('#message');
        message.addEventListener('keypress', e => {
          if (e.charCode !== 13) return;
          ws.send(message.value);
          message.value = '';
        });
      })();
    </script>
  </body>

</html>

Puede ver en el código anterior que conectamos mediante la API nativa de WebSocket en el explorador y usar WebSocket.send() para enviar mensajes y WebSocket.onmessage para escuchar los mensajes recibidos.

También puede usar el SDK de cliente para conectarse al servicio, lo que le permite volver a conectarse automáticamente, controlar errores y mucho más.

Ahora queda un paso para que el chat funcione. Vamos a configurar los eventos que nos importan y dónde enviar los eventos al servicio Web PubSub.

Configuración del controlador de eventos

Establecemos el controlador de eventos en el servicio Web PubSub para indicar al servicio dónde enviar los eventos.

Cuando el servidor web se ejecuta localmente, ¿cómo invoca el servicio Web PubSub el localhost si no tiene ningún punto de conexión accesible a Internet? Normalmente hay dos maneras. Una consiste en exponer localhost a público mediante alguna herramienta de túnel general y la otra es usar awps-tunnel para tunelizar el tráfico desde el servicio Web PubSub a través de la herramienta al servidor local.

En esta sección, usamos la CLI de Azure para establecer los controladores de eventos y usar awps-tunnel para enrutar el tráfico a localhost.

Configuración de las opciones del centro de conectividad

Establecemos la plantilla de dirección URL para usar el esquema tunnel para que Web PubSub enrute los mensajes a través de la conexión de túnel de awps-tunnel. Los controladores de eventos se pueden establecer desde el portal o la CLI, tal y como se describe en este artículo; aquí lo establecemos a través de la CLI. Dado que escuchamos eventos en la ruta de acceso /eventhandler como los conjuntos de pasos anteriores, establecemos la plantilla de dirección URL en tunnel:///eventhandler.

Use la CLI de Azure comando az webpubsub hub create para crear la configuración del controlador de eventos para el centro de Sample_ChatApp.

Importante

Reemplace <your-unique-resource-name> por el nombre del recurso de Web PubSub que creó en los pasos anteriores.

az webpubsub hub create -n "<your-unique-resource-name>" -g "myResourceGroup" --hub-name "Sample_ChatApp" --event-handler url-template="tunnel:///eventhandler" user-event-pattern="*" system-event="connected"

Ejecución local de awps-tunnel

Descarga e instalación de awps-tunnel

La herramienta se ejecuta en Node.js versión 16 o posterior.

npm install -g @azure/web-pubsub-tunnel-tool

Uso de la cadena de conexión de servicio y ejecución

export WebPubSubConnectionString="<your connection string>"
awps-tunnel run --hub Sample_ChatApp --upstream http://localhost:8080

Ejecución del servidor web

Ya está todo listo. Vamos a ejecutar el servidor web y jugar con la aplicación de chat en acción.

C#

Ejecute el servidor mediante dotnet run --urls http://localhost:8080.

El código de ejemplo completo de este tutorial se puede encontrar aquí.

JavaScript

Ejecute el servidor mediante node server.

El código de ejemplo completo de este tutorial se puede encontrar aquí.

Java

Ejecute el servidor mediante el siguiente comando:

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.tutorial.App" -Dexec.cleanupDaemonThreads=false

El código de ejemplo completo de este tutorial se puede encontrar aquí.

Python

Ejecute el servidor mediante python server.py.

El código de ejemplo completo de este tutorial se puede encontrar aquí.

Abra http://localhost:8080/index.html. Puede escribir el nombre de usuario y empezar a chatear.

Autenticación diferida con controlador de eventos connect

En las secciones anteriores, se muestra cómo usar negociar punto de conexión para devolver la dirección URL del servicio Web PubSub y el token de acceso JWT para que los clientes se conecten al servicio Web PubSub. En algunos casos, por ejemplo, los dispositivos perimetrales que tienen recursos limitados, los clientes pueden preferir la conexión directa a los recursos de Web PubSub. En tales casos, puede configurar el controlador de eventos connect para realizar autenticación diferida de los clientes, asignar ID de usuario a los clientes, especificar los grupos a los que se unen los clientes una vez que se conectan, configurar los permisos que tienen los clientes y el subprotocolo WebSocket como respuesta de WebSocket al cliente y mucho más. Para obtener más información, consulte las especificaciones del controlador de eventos de conexión.

Ahora usemos el controlador de eventos connect para lograr algo similar a lo que hace la sección de negociación.

Actualizar la configuración del centro de conectividad

En primer lugar, vamos a actualizar la configuración del centro para incluir también connect controlador de eventos, es necesario permitir también la conexión anónima para que los clientes sin token de acceso JWT puedan conectarse al servicio.

Use el comando az webpubsub hub update de la CLI de Azure para crear la configuración del controlador de eventos del centro de Sample_ChatApp.

Importante

Reemplace <your-unique-resource-name> por el nombre del recurso de Web PubSub que creó en los pasos anteriores.

az webpubsub hub update -n "<your-unique-resource-name>" -g "myResourceGroup" --hub-name "Sample_ChatApp" --allow-anonymous true --event-handler url-template="tunnel:///eventhandler" user-event-pattern="*" system-event="connected" system-event="connect"

Actualice la lógica ascendente para manejar el evento de conexión

Ahora vamos a actualizar la lógica ascendente para controlar el evento de conexión. También podríamos quitar el punto de conexión de negociación ahora.

De forma similar a lo que hacemos en el punto de conexión de negociación como propósito de demostración, también se lee el identificador de los parámetros de consulta. En el evento de conexión, la consulta del cliente original se conserva en el cuerpo de la solicitud del evento de conexión.

C#

Dentro de la clase Sample_ChatApp, invalide OnConnectAsync() para controlar el evento connect:

sealed class Sample_ChatApp : WebPubSubHub
{
    private readonly WebPubSubServiceClient<Sample_ChatApp> _serviceClient;

    public Sample_ChatApp(WebPubSubServiceClient<Sample_ChatApp> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override ValueTask<ConnectEventResponse> OnConnectAsync(ConnectEventRequest request, CancellationToken cancellationToken)
    {
        if (request.Query.TryGetValue("id", out var id))
        {
            return new ValueTask<ConnectEventResponse>(request.CreateResponse(userId: id.FirstOrDefault(), null, null, null));
        }

        // The SDK catches this exception and returns 401 to the caller
        throw new UnauthorizedAccessException("Request missing id");
    }

    public override async Task OnConnectedAsync(ConnectedEventRequest request)
    {
        Console.WriteLine($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
    }

    public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
    {
        await _serviceClient.SendToAllAsync(RequestContent.Create(
        new
        {
            from = request.ConnectionContext.UserId,
            message = request.Data.ToString()
        }),
        ContentType.ApplicationJson);

        return new UserEventResponse();
    }
}

JavaScript

Actualice server.js para controlar el evento de conexión de cliente:

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

const app = express();
const hubName = "Sample_ChatApp";

let serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hubName);

let handler = new WebPubSubEventHandler(hubName, {
  path: "/eventhandler",
  handleConnect: async (req, res) => {
    if (req.context.query.id){
      res.success({ userId: req.context.query.id });
    } else {
      res.fail(401, "missing user id");
    }
  },
  onConnected: async (req) => {
    console.log(`${req.context.userId} connected`);
  },
  handleUserEvent: async (req, res) => {
    if (req.context.eventName === "message")
      await serviceClient.sendToAll({
        from: req.context.userId,
        message: req.data,
      });
    res.success();
  },
});
app.use(express.static("public"));
app.use(handler.getMiddleware());

app.listen(8080, () => console.log("server started"));

Java

Ahora agreguemos la lógica para manejar el evento de conexión azure.webpubsub.sys.connect:

// validation: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
app.options("/eventhandler", ctx -> {
    ctx.header("WebHook-Allowed-Origin", "*");
});

// handle events: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#connect
app.post("/eventhandler", ctx -> {
    String event = ctx.header("ce-type");
    if ("azure.webpubsub.sys.connect".equals(event)) {
        String body = ctx.body();
        System.out.println("Reading from request body...");
        Gson gson = new Gson();
        JsonObject requestBody = gson.fromJson(body, JsonObject.class); // Parse JSON request body
        JsonObject query = requestBody.getAsJsonObject("query");
        if (query != null) {
            System.out.println("Reading from request body query:" + query.toString());
            JsonElement idElement = query.get("id");
            if (idElement != null) {
                JsonArray idInQuery = query.get("id").getAsJsonArray();
                if (idInQuery != null && idInQuery.size() > 0) {
                    String id = idInQuery.get(0).getAsString();
                    ctx.contentType("application/json");
                    Gson response = new Gson();
                    JsonObject jsonObject = new JsonObject();
                    jsonObject.addProperty("userId", id);
                    ctx.result(response.toJson(jsonObject));
                    return;
                }
            }
        } else {
            System.out.println("No query found from request body.");
        }
        ctx.status(401).result("missing user id");
    } else if ("azure.webpubsub.sys.connected".equals(event)) {
        String id = ctx.header("ce-userId");
        System.out.println(id + " connected.");
        ctx.status(200);
    } else if ("azure.webpubsub.user.message".equals(event)) {
        String id = ctx.header("ce-userId");
        String message = ctx.body();
        service.sendToAll(String.format("{\"from\":\"%s\",\"message\":\"%s\"}", id, message), WebPubSubContentType.APPLICATION_JSON);
        ctx.status(200);
    }
});

Python

Ahora vamos a controlar el evento del sistema connect, que debe contener el encabezado ce-type como azure.webpubsub.sys.connect. Agregamos la lógica para la protección contra abusos:

@app.route('/eventhandler', methods=['POST', 'OPTIONS'])
def handle_event():
    if request.method == 'OPTIONS' or request.method == 'GET':
        if request.headers.get('WebHook-Request-Origin'):
            res = Response()
            res.headers['WebHook-Allowed-Origin'] = '*'
            res.status_code = 200
            return res
    elif request.method == 'POST':
        user_id = request.headers.get('ce-userid')
        type = request.headers.get('ce-type')
        print("Received event of type:", type)
        # Sample connect logic if connect event handler is configured
        if type == 'azure.webpubsub.sys.connect':
            body = request.data.decode('utf-8')
            print("Reading from connect request body...")
            query = json.loads(body)['query']
            print("Reading from request body query:", query)
            id_element = query.get('id')
            user_id = id_element[0] if id_element else None
            if user_id:
                return {'userId': user_id}, 200
            return 'missing user id', 401
        elif type == 'azure.webpubsub.sys.connected':
            return user_id + ' connected', 200
        elif type == 'azure.webpubsub.user.message':
            service.send_to_all(content_type="application/json", message={
                'from': user_id,
                'message': request.data.decode('UTF-8')
            })
            return Response(status=204, content_type='text/plain')
        else:
            return 'Bad Request', 400

Actualizar index.html para conectar directamente

Ahora vamos a actualizar la página web para conectarse directamente al servicio Web PubSub. Lo que hay que mencionar es que ahora, para fines de demostración, el punto de conexión de servicio de Web PubSub está codificado de forma rígida en el código de cliente, actualice el nombre de host del servicio <the host name of your service> en el código html siguiente con el valor de su propio servicio. Es posible que siga siendo útil capturar el valor del punto de conexión de servicio de Web PubSub del servidor, lo que proporciona más flexibilidad y capacidad de control a la ubicación a la que se conecta el cliente.

<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
    <input id="message" placeholder="Type to chat...">
    <div id="messages"></div>
    <script>
      (async function () {
        // sample host: mock.webpubsub.azure.com
        let hostname = "<the host name of your service>";
        let id = prompt('Please input your user name');
        let ws = new WebSocket(`wss://${hostname}/client/hubs/Sample_ChatApp?id=${id}`);
        ws.onopen = () => console.log('connected');

        let messages = document.querySelector('#messages');
        
        ws.onmessage = event => {
          let m = document.createElement('p');
          let data = JSON.parse(event.data);
          m.innerText = `[${data.type || ''}${data.from || ''}] ${data.message}`;
          messages.appendChild(m);
        };

        let message = document.querySelector('#message');
        message.addEventListener('keypress', e => {
          if (e.charCode !== 13) return;
          ws.send(message.value);
          message.value = '';
        });
      })();
    </script>
  </body>

</html>

Volver a ejecutar el servidor

Ahora vuelva a ejecutar el servidor y viste la página web siguiendo las instrucciones anteriores. Si ha detenido awps-tunnel, también vuelva a ejecutar la herramienta de túnel.

Pasos siguientes

En este tutorial se proporciona una idea básica de cómo funciona el sistema de eventos en el servicio Azure Web PubSub.

En otros tutoriales podrá profundizar más en cómo usar el servicio.

Explore más ejemplos de Azure Web PubSub.