Tutorial: Publicación y suscripción de mensajes mediante la API de WebSocket y el SDK del servicio Azure Web PubSub

Artículo
09/03/2024

El servicio Azure Web PubSub le ayuda a crear fácilmente aplicaciones de mensajería web en tiempo real. En este tutorial, aprenderá a suscribirse al servicio utilizando la API WebSocket y a publicar mensajes utilizando el SDK del servicio Web PubSub.

En este tutorial, aprenderá a:

Crear una instancia del servicio Web PubSub
Generar la dirección URL completa para establecer la conexión de WebSocket.
Crear un cliente suscriptor Web PubSub para recibir mensajes mediante el protocolo estándar WebSocket
Crear un cliente editor Web PubSub para publicar mensajes utilizando el SDK del servicio Web PubSub

Requisitos previos

Una suscripción de Azure, cree una cuenta gratuita.
Un shell de comandos de Bash. Use un shell local o el entorno de Bash en Azure Cloud Shell.
Si se ejecuta en su máquina local, instale la CLI de Azure.

Puede usar el shell de comandos de Windows cmd.exe en lugar de un shell de Bash para ejecutar los comandos de este tutorial.

Si está creando el proyecto en una máquina local, necesita instalar las dependencias para el idioma que está utilizando:

.NET Core

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.

Configuración de la CLI de Azure para el desarrollo local

Siga estos pasos para configurar la CLI de Azure y el entorno del proyecto.

Abra un shell de comandos.
Actualice a la última versión de la CLI de Azure.
```
az upgrade
```
Instale la extensión para Web PubSub de la CLI de Azure.
```
az extension add --name webpubsub
```
Inicie sesión en la CLI de Azure. Siguiendo las indicaciones, escriba sus credenciales de Azure.
```
az login
```

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

1. Creación de una instancia de Azure Web PubSub

Creación de una instancia de Web PubSub

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

Cada recurso de Web PubSub debe tener un nombre único. Reemplace <su-nombre-de-recurso-único> por el nombre de la instancia de Web PubSub en el comando siguiente.

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

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

name: nombre de Web PubSub que proporcionó en el 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 la cadena de conexión

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.

Creación de un cliente de suscriptor

Los clientes se conectan al servicio Azure Web PubSub mediante el protocolo WebSocket estándar con el uso de la autenticación de JSON Web Token (JWT). El SDK del servicio proporciona métodos de asistencia para generar el token. En este tutorial, el suscriptor genera directamente el token de ConnectionString. En las aplicaciones reales, normalmente se usa una aplicación del lado del servidor para controlar el flujo de trabajo de autenticación o autorización. Para comprender mejor el flujo de trabajo, vea el tutorial Compilación de una aplicación de chat.

Las cadenas de conexión sin procesar solo aparecen en este artículo con fines de demostración. 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.

En primer lugar, cree un directorio denominado subscriber para este proyecto e instale las dependencias requeridas:
- El paquete Websocket.Client es un paquete de terceros que admite las conexiones de WebSocket. Puede usar cualquier API o biblioteca que admita WebSocket.
- El paquete del SDK Azure.Messaging.WebPubSub ayuda a generar el token JWT.
```
mkdir subscriber
cd subscriber
dotnet new console
dotnet add package Websocket.Client --version 4.3.30
dotnet add package Azure.Messaging.WebPubSub --version 1.0.0
```

Reemplace el código en el Program.cs con el siguiente código que se conecta al servicio:

using System;
using System.Threading.Tasks;

using Azure.Messaging.WebPubSub;

using Websocket.Client;

namespace subscriber
{
    class Program
    {
        static async Task Main(string[] args)
        {
            if (args.Length != 2)
            {
                Console.WriteLine("Usage: subscriber <connectionString> <hub>");
                return;
            }
            var connectionString = args[0];
            var hub = args[1];

            // Either generate the URL or fetch it from server or fetch a temp one from the portal
            var serviceClient = new WebPubSubServiceClient(connectionString, hub);
            var url = serviceClient.GetClientAccessUri();

            using (var client = new WebsocketClient(url))
            {
                // Disable the auto disconnect and reconnect because the sample would like the client to stay online even no data comes in
                client.ReconnectTimeout = null;
                client.MessageReceived.Subscribe(msg => Console.WriteLine($"Message received: {msg}"));
                await client.Start();
                Console.WriteLine("Connected.");
                Console.Read();
            }
        }
    }
}

El código crea una conexión de WebSocket que se conecta a un centro en Web PubSub. Un centro es una unidad lógica de Web PubSub donde puede publicar mensajes para un grupo de clientes. Los conceptos clave contienen una explicación detallada sobre los términos usados en Web PubSub.

El servicio Web PubSub usa la autenticación JSON Web Token (JWT). El código de ejemplo usa WebPubSubServiceClient.GetClientAccessUri() en el SDK de Web PubSub para generar una dirección URL al servicio que contiene la dirección URL completa con un token de acceso válido.

Una vez establecida la conexión, el cliente recibe mensajes a través de la conexión de WebSocket. El cliente usa client.MessageReceived.Subscribe(msg => ...)); para escuchar los mensajes entrantes.

Para iniciar el suscriptor, ejecute el comando siguiente después de reemplazar <Web-PubSub-connection-string> por la cadena de conexión que copió anteriormente:
```
dotnet run <Web-PubSub-connection-string> "myHub1"
```

En primer lugar, cree un directorio del proyecto denominado subscriber e instale las dependencias requeridas:
```
mkdir subscriber
cd subscriber
npm init -y
npm install --save ws
npm install --save @azure/web-pubsub
```
Use la API de WebSocket para conectarse al servicio Web PubSub. Cree un archivo subscribe.js con el código siguiente:
```
const WebSocket = require('ws');
const { WebPubSubServiceClient } = require('@azure/web-pubsub');

async function main() {
  const hub = "pubsub";
  let service = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);
  let token = await service.getClientAccessToken();
  let ws = new WebSocket(token.url);
  ws.on('open', () => console.log('connected'));
  ws.on('message', data => console.log('Message received: %s', data));
}

main();
```
El código crea una conexión de WebSocket que se conecta a un centro en Web PubSub. Un centro es una unidad lógica de Web PubSub donde puede publicar mensajes para un grupo de clientes. Los conceptos clave contienen una explicación detallada sobre los términos usados en Web PubSub.

El servicio Web PubSub usa la autenticación JSON Web Token (JWT). El código de ejemplo usa WebPubSubServiceClient.GetClientAccessUri() en el SDK de Web PubSub para generar una dirección URL al servicio que contiene la dirección URL completa con un token de acceso válido.

Una vez establecida la conexión, el cliente recibe mensajes a través de la conexión de WebSocket. El cliente usa client.MessageReceived.Subscribe(msg => ...)); para escuchar los mensajes entrantes.
Ejecute el siguiente comando reemplazando <Web-PubSub-connection-string> por la cadena de conexión que copió anteriormente. Si utiliza el intérprete de comandos de Windows, puede utilizar set en lugar de export.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node subscribe.js
```

En primer lugar, cree un directorio del proyecto denominado subscriber e instale las dependencias requeridas:

mkdir subscriber
cd subscriber
# Create venv
python -m venv env
# Activate venv
source ./env/bin/activate

pip install azure-messaging-webpubsubservice
pip install websockets

Use la API de WebSocket para conectarse al servicio Web PubSub. Cree un archivo subscribe.py con el código siguiente:
```
import asyncio
import sys
import websockets

from azure.messaging.webpubsubservice import WebPubSubServiceClient


async def connect(url):
    async with websockets.connect(url) as ws:
        print('connected')
        while True:
            print('Received message: ' + await ws.recv())

if __name__ == '__main__':

    if len(sys.argv) != 3:
        print('Usage: python subscribe.py <connection-string> <hub-name>')
        exit(1)

    connection_string = sys.argv[1]
    hub_name = sys.argv[2]

    service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
    token = service.get_client_access_token()

    try:
        asyncio.get_event_loop().run_until_complete(connect(token['url']))
    except KeyboardInterrupt:
        pass
```
El código crea una conexión de WebSocket que se conecta a un centro en Web PubSub. Un centro es una unidad lógica de Web PubSub donde puede publicar mensajes para un grupo de clientes. Los conceptos clave contienen una explicación detallada sobre los términos usados en Web PubSub.

El servicio Web PubSub usa la autenticación JSON Web Token (JWT). El código de ejemplo usa WebPubSubServiceClient.GetClientAccessUri() en el SDK de Web PubSub para generar una dirección URL al servicio que contiene la dirección URL completa con un token de acceso válido.

Una vez establecida la conexión, el cliente recibirá mensajes a través de la conexión de WebSocket. Use await ws.recv() para escuchar los mensajes entrantes.
Ejecute el siguiente comando reemplazando <Web-PubSub-connection-string> por la cadena de conexión que copió anteriormente:
```
python subscribe.py <Web-PubSub-connection-string> "myHub1"
```

En primer lugar, cree un directorio de proyecto denominado pubsub para este tutorial.
```
mkdir pubsub
cd pubsub
```

En el directorio pubsub, use Maven para crear una aplicación de consola denominada webpubsub-quickstart-subscriber y, a continuación, vaya al directorio webpubsub-quickstart-subscriber:

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

Agregue el SDK de Azure Web PubSub y WebSocket al nodo dependencies en pom.xml:
- azure-messaging-webpubsub: SDK del servicio Web PubSub para Java
- Java-WebSocket: SDK del cliente WebSocket para Java
```
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.0.0</version>
</dependency>

<dependency>
    <groupId>org.java-websocket</groupId>
    <artifactId>Java-WebSocket</artifactId>
    <version>1.5.1</version>
</dependency>
```
En Web PubSub, puede conectarse al servicio y suscribirse a los mensajes a través de conexiones de WebSocket. WebSocket es un canal de comunicación dúplex completo que permite que el servicio pueda insertar mensajes en el cliente en tiempo real. Puede usar cualquier API o biblioteca que admita WebSocket. Para este ejemplo, usamos el v Java-WebSocket.
Vaya al directorio /src/main/java/com/webpubsub/quickstart.

Edite y reemplace el contenido del archivo App.java por el código siguiente:

package com.webpubsub.quickstart;

import com.azure.messaging.webpubsub.*;
import com.azure.messaging.webpubsub.models.*;

import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;

/**
* Connect to Azure Web PubSub service using WebSocket protocol
*/
public class App 
{
    public static void main( String[] args ) throws IOException, URISyntaxException
    {
        if (args.length != 2) {
            System.out.println("Expecting 2 arguments: <connection-string> <hub-name>");
            return;
        }

        WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
            .connectionString(args[0])
            .hub(args[1])
            .buildClient();

        WebPubSubClientAccessToken token = service.getClientAccessToken(new GetClientAccessTokenOptions());

        WebSocketClient webSocketClient = new WebSocketClient(new URI(token.getUrl())) {
            @Override
            public void onMessage(String message) {
                System.out.println(String.format("Message received: %s", message));
            }

            @Override
            public void onClose(int arg0, String arg1, boolean arg2) {
                // TODO Auto-generated method stub
            }

            @Override
            public void onError(Exception arg0) {
                // TODO Auto-generated method stub
            }

            @Override
            public void onOpen(ServerHandshake arg0) {
                // TODO Auto-generated method stub
            }

        };

        webSocketClient.connect();
        System.in.read();
    }
}

Este código crea una conexión de WebSocket que se conecta a un centro en Azure Web PubSub. Un centro es una unidad lógica de Azure Web PubSub donde puede publicar mensajes para un grupo de clientes. Los conceptos clave contienen la explicación detallada sobre los términos usados en Azure Web PubSub.

Una vez establecida la conexión, el cliente recibirá mensajes a través de la conexión de WebSocket. Use onMessage(String message) para escuchar los mensajes entrantes.

Para iniciar la aplicación de suscriptor, vaya al directorio webpubsub-quickstart-subscriber y ejecute el siguiente comando. Reemplace <Web-PubSub-connection-string> por la cadena de conexión que copió anteriormente.
```
mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1'"
```

2. Publicación de mensajes mediante el SDK del servicio

Cree un publicador con el SDK de Azure Web PubSub para publicar un mensaje para el cliente conectado. Para este proyecto, es necesario abrir otro shell de comandos.

En primer lugar, cree un directorio del proyecto denominado publisher e instale las dependencias requeridas:
```
mkdir publisher
cd publisher
dotnet new console
dotnet add package Azure.Messaging.WebPubSub
```

Actualice el archivo Program.cs para usar la clase WebPubSubServiceClient y enviar mensajes a los clientes.

using System;
using System.Threading.Tasks;
using Azure.Messaging.WebPubSub;

namespace publisher
{
    class Program
    {
        static async Task Main(string[] args)
        {
            if (args.Length != 3) {
                Console.WriteLine("Usage: publisher <connectionString> <hub> <message>");
                return;
            }
            var connectionString = args[0];
            var hub = args[1];
            var message = args[2];

            // Either generate the token or fetch it from server or fetch a temp one from the portal
            var serviceClient = new WebPubSubServiceClient(connectionString, hub);
            await serviceClient.SendToAllAsync(message);
        }
    }
}

La llamada SendToAllAsync() simplemente envía un mensaje a todos los clientes conectados en el centro.

Envíe un mensaje mediante la ejecución del siguiente comando. Reemplace <Web-PubSub-connection-string> por la cadena de conexión que copió anteriormente.
```
dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Compruebe que el intérprete de comandos del abonado recibe el mensaje:
```
Message received: Hello World
```

En primer lugar, cree un directorio del proyecto denominado publisher e instale las dependencias requeridas:
```
mkdir publisher
cd publisher
npm init -y
npm install --save @azure/web-pubsub
```

Use el SDK de Azure Web PubSub para publicar un mensaje en el servicio. Cree un archivo publish.js con el código siguiente:

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

const hub = "pubsub";
let service = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);

// by default it uses `application/json`, specify contentType as `text/plain` if you want plain-text
service.sendToAll(process.argv[2], { contentType: "text/plain" });

La llamada service.sendToAll() simplemente envía un mensaje a todos los clientes conectados en un centro.

Para enviar un mensaje, ejecute el siguiente comando reemplazando <Web-PubSub-connection-string> por la cadena de conexión que copió anteriormente. Si utiliza el intérprete de comandos de Windows, puede utilizar set en lugar de export.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node publish "Hello World"
```
Puede ver que el suscriptor ha recibido el mensaje:
```
Message received: Hello World
```

En primer lugar, cree un directorio del proyecto denominado publisher e instale las dependencias requeridas:

mkdir publisher
cd publisher
# Create venv
python -m venv env
# Active venv
source ./env/bin/activate

pip install azure-messaging-webpubsubservice

Use el SDK de Azure Web PubSub para publicar un mensaje en el servicio. Cree un archivo publish.py con el código siguiente:

import sys
from azure.messaging.webpubsubservice import WebPubSubServiceClient

if __name__ == '__main__':

    if len(sys.argv) != 4:
        print('Usage: python publish.py <connection-string> <hub-name> <message>')
        exit(1)

    connection_string = sys.argv[1]
    hub_name = sys.argv[2]
    message = sys.argv[3]

    service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)
    res = service.send_to_all(message, content_type='text/plain')
    print(res)

send_to_all() envía un mensaje a todos los clientes conectados en un centro de conectividad.

Para enviar un mensaje, ejecute el siguiente comando reemplazando <Web-PubSub-connection-string> por la cadena de conexión que copió anteriormente.
```
python publish.py <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Compruebe el shell de comandos anterior con el que el suscriptor recibió el mensaje:
```
Received message: Hello World
```

Vaya al directorio pubsub. Use Maven para crear una aplicación webpubsub-quickstart-publisher de consola de publicador y vaya al directorio webpubsub-quickstart-publisher:

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

Agregue la dependencia del SDK de Azure Web PubSub en el nodo dependencies de pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.0.0</version>
</dependency>

Use el SDK de Azure Web PubSub para publicar un mensaje en el servicio. Vaya al directorio /src/main/java/com/webpubsub/quickstart, abra el archivo App.java en el editor y reemplace el contenido por el código siguiente:


package com.webpubsub.quickstart;

import com.azure.messaging.webpubsub.*;
import com.azure.messaging.webpubsub.models.*;

/**
* Publish messages using Azure Web PubSub service SDK
*
*/
public class App 
{
    public static void main( String[] args )
    {
        if (args.length != 3) {
            System.out.println("Expecting 3 arguments: <connection-string> <hub-name> <message>");
            return;
        }

        WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
            .connectionString(args[0])
            .hub(args[1])
            .buildClient();
        service.sendToAll(args[2], WebPubSubContentType.TEXT_PLAIN);
    }
}

La llamada sendToAll() envía un mensaje a todos los clientes conectados en un centro.

Para enviar un mensaje, vaya al directorio webpubsub-quickstart-publisher y ejecute el proyecto con el siguiente comando. Reemplace <Web-PubSub-connection-string> por la cadena de conexión que copió anteriormente.
```
mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="<Web-PubSub-connection-string> 'myHub1' 'Hello World'"
```
Puede ver que el suscriptor ha recibido el mensaje:
```
Message received: Hello World
```

Limpieza

Puede eliminar los recursos que creó en este inicio rápido mediante la eliminación del grupo de recursos que los contiene.

az group delete --name myResourceGroup --yes

Si no tiene previsto seguir usando Azure Cloud Shell, puede eliminar el grupo de recursos que contiene la cuenta de almacenamiento asociada para evitar acumular costos. El grupo de recursos se denomina cloud-shell-storage-<your-region>. Ejecute el comando siguiente y reemplace <CloudShellResourceGroup> por el nombre del grupo de Cloud Shell.

az group delete --name <CloudShellResourceGroup> --yes

Precaución

Al eliminarse los grupos de recursos se eliminarán todos los recursos, incluidos aquellos creados fuera del ámbito de este tutorial.

Pasos siguientes

En este tutorial se proporciona una idea básica de cómo conectarse al servicio Web PubSub y cómo publicar mensajes en los clientes conectados.

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

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

Explore más ejemplos de Azure Web PubSub.

Compartir vía