Tutorial – publicar e assinar mensagens usando a API WebSocket e o SDK do serviço Azure Web PubSub

Artigo
09/03/2024

O serviço Azure Web PubSub ajuda você a criar facilmente aplicativos de mensagens da Web em tempo real. Neste tutorial, você aprenderá a assinar o serviço usando a API WebSocket e a publicar mensagens utilizando o SDK do serviço Web PubSub.

Neste tutorial, você aprenderá a:

Criar uma instância do serviço Web PubSub
Gerar a URL completa para estabelecer a conexão WebSocket
Crie um cliente assinante do Web PubSub para receber mensagens utilizando o protocolo WebSocket padrão
Criar um cliente publicador do Web PubSub para publicar mensagens usando o SDK do serviço Web PubSub

Pré-requisitos

Uma assinatura do Azure, crie uma conta gratuita.
Um shell de comando Bash. Use um shell local ou o ambiente Bash no Azure Cloud Shell.
Se estiver em execução no computador local, instale a CLI do Azure.

É possível usar o shell de comando cmd.exe do Windows em vez de um shell Bash para executar os comandos neste tutorial.

Se você estiver criando o projeto em um computador local, precisará instalar as dependências do idioma que estiver usando:

.NET Core

Importante

As cadeias de conexão brutas aparecem neste artigo apenas para fins de demonstração.

Uma cadeia de conexão inclui as informações de autorização necessárias para que o seu aplicativo acesse o serviço Azure Web PubSub. A chave de acesso dentro da cadeia de conexão é semelhante a uma senha raiz para o serviço. Em ambientes de produção, sempre proteja suas chaves de acesso. Use o Azure Key Vault para gerenciar e girar suas chaves com segurança e proteger sua conexão com WebPubSubServiceClient.

Evite distribuir chaves de acesso para outros usuários, fazer hard-coding com elas ou salvá-las em qualquer lugar em texto sem formatação que seja acessível a outras pessoas. Gire suas chaves se você acredita que elas podem ter sido comprometidas.

Configuração da CLI do Azure para o desenvolvimento local

Siga estas etapas para configurar a CLI do Azure e o ambiente do projeto.

Abra um shell de comando.
Atualize para a versão mais recente da CLI do Azure.
```
az upgrade
```
Instale a extensão da CLI do Azure para Web PubSub.
```
az extension add --name webpubsub
```
Entre na CLI do Azure. Após os prompts, insira suas credenciais do Azure.
```
az login
```

Criar um grupo de recursos

Um grupo de recursos é um contêiner lógico no qual os recursos do Azure são implantados e gerenciados. Use o comando az group create para criar um grupo de recursos chamado myResourceGroup no local eastus.

az group create --name myResourceGroup --location EastUS

1. Criar uma instância do Azure Web PubSub

Criar uma instância do Web PubSub

Para criar uma instância do Web PubSub no grupo de recursos que você criou, utilize o comando da CLI do Azure az webpubsub create. O seguinte comando cria um recurso gratuito do Web PubSub no grupo de recursos myResourceGroup no EastUS:

Cada recurso Web PubSub precisa ter um nome exclusivo. Substitua <your-unique-resource-name> pelo nome da instância do Web PubSub no comando a seguir.

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

A saída deste comando mostra as propriedades do recurso recém-criado. Anote as seguintes propriedades:

nome: o nome do Web PubSub fornecido no parâmetro --name acima.
hostName: no exemplo, o nome do host é <your-unique-resource-name>.webpubsub.azure.com/.

Nesse ponto, sua conta do Azure é a única autorizada a executar qualquer operação nesse novo recurso.

Obtenha a cadeia de conexão

Use o comando az webpubsub key da CLI do Azure para obter a ConnectionString do serviço. Substitua o espaço reservado <your-unique-resource-name> pelo nome da instância do Azure Web PubSub.

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

Copie a cadeia de conexão para usar mais tarde.

Criar um cliente assinante

Os clientes se conectam ao serviço do Azure Web PubSub por meio do protocolo WebSocket padrão usando a autenticação de Token Web JSON (JWT). O SDK do serviço fornece métodos auxiliares para gerar o token. Neste tutorial, o assinante gera diretamente o token a partir do ConnectionString. Em aplicativos reais, um aplicativo do lado do servidor geralmente lida com o fluxo de trabalho de autenticação/autorização. Para entender melhor o fluxo de trabalho, consulte o tutorial Compilar um aplicativo de chat.

As cadeias de conexão brutas aparecem neste artigo apenas para fins de demonstração. Em ambientes de produção, sempre proteja suas chaves de acesso. Use o Azure Key Vault para gerenciar e girar suas chaves com segurança e proteger sua conexão com WebPubSubServiceClient.

Primeiro, crie um diretório de projeto chamado subscriber para este projeto e instale as dependências necessárias:
- O pacote Websocket.Client é um pacote de terceiros que dá suporte a conexões WebSocket. É possível usar qualquer API/biblioteca compatível com WebSocket.
- O pacote do SDK Azure.Messaging.WebPubSub ajuda a gerar o 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
```

Substitua o código em Program.cs pelo código a seguir que se conecta ao serviço:

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

O código cria uma conexão WebSocket que está conectada a um hub no Web PubSub. Um hub é uma unidade lógica no Web PubSub onde você pode publicar mensagens para um grupo de clientes. Os principais conceitos contêm a explicação detalhada sobre os termos usados no Web PubSub.

O serviço do Web PubSub usa a autenticação JWT (Token Web JSON). O código de exemplo usa WebPubSubServiceClient.GetClientAccessUri() no SDK do Web PubSub para gerar uma URL para o serviço que contém a URL completa com um token de acesso válido.

Após a conexão ser estabelecida, seu cliente recebe mensagens pela conexão WebSocket. O cliente usa client.MessageReceived.Subscribe(msg => ...)); para escutar mensagens de entrada.

Para iniciar o assinante, execute o seguinte comando substituindo <Web-PubSub-connection-string> pela cadeia de conexão copiada anteriormente:
```
dotnet run <Web-PubSub-connection-string> "myHub1"
```

Primeiro, crie um diretório de projeto chamado subscriber e instale as dependências necessárias:

mkdir subscriber
cd subscriber
npm init -y
npm install --save ws
npm install --save @azure/web-pubsub

Use a API do WebSocket para se conectar ao serviço do Web PubSub. Crie um arquivo subscribe.js com o código a seguir:
```
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();
```
O código cria uma conexão WebSocket que está conectada a um hub no Web PubSub. Um hub é uma unidade lógica no Web PubSub onde você pode publicar mensagens para um grupo de clientes. Os principais conceitos contêm a explicação detalhada sobre os termos usados no Web PubSub.

O serviço do Web PubSub usa a autenticação JWT (Token Web JSON). O código de exemplo usa WebPubSubServiceClient.GetClientAccessUri() no SDK do Web PubSub para gerar uma URL para o serviço que contém a URL completa com um token de acesso válido.

Após a conexão ser estabelecida, seu cliente recebe mensagens pela conexão WebSocket. O cliente usa client.MessageReceived.Subscribe(msg => ...)); para escutar mensagens de entrada.
Execute o comando a seguir substituindo <Web-PubSub-connection-string> pela cadeia de conexão copiada anteriormente. Se estiver usando o shell de comando do Windows, poderá usar set em vez de export.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node subscribe.js
```

Primeiro, crie um diretório de projeto chamado subscriber e instale as dependências necessárias:

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 a API do WebSocket para se conectar ao serviço do Web PubSub. Crie um arquivo subscribe.py com o código a seguir:
```
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
```
O código cria uma conexão WebSocket que está conectada a um hub no Web PubSub. Um hub é uma unidade lógica no Web PubSub onde você pode publicar mensagens para um grupo de clientes. Os principais conceitos contêm a explicação detalhada sobre os termos usados no Web PubSub.

O serviço do Web PubSub usa a autenticação JWT (Token Web JSON). O código de exemplo usa WebPubSubServiceClient.GetClientAccessUri() no SDK do Web PubSub para gerar uma URL para o serviço que contém a URL completa com um token de acesso válido.

Após a conexão ser estabelecida, seu cliente receberá mensagens pela conexão WebSocket. Use await ws.recv() para escutar mensagens de entrada.
Execute o seguinte comando substituindo <Web-PubSub-connection-string> pela cadeia de conexão copiada anteriormente:
```
python subscribe.py <Web-PubSub-connection-string> "myHub1"
```

Primeiro, crie um diretório de projeto chamado pubsub para este tutorial.
```
mkdir pubsub
cd pubsub
```

Dentro do diretório pubsub, use o Maven para criar um novo aplicativo de console chamado webpubsub-quickstart-subscriber, em seguida, acesse o diretório 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

Adicione o WebSocket e o SDK do Azure Web PubSub ao nó dependencies em pom.xml:
- azure-messaging-webpubsub: SDK do serviço do Web PubSub para Java
- Java-WebSocket: SDK de cliente do 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>
```
No Web PubSub, é possível se conectar ao serviço e assinar mensagens por meio de conexões WebSocket. O WebSocket é um canal de comunicação full duplex, que permite ao serviço enviar mensagens por push para o cliente em tempo real. Use qualquer API ou biblioteca com suporte ao WebSocket. Para este exemplo, usamos o pacote Java-WebSocket.
Acesse o diretório /src/main/java/com/webpubsub/quickstart.

Edite, substituindo o conteúdo do arquivo App.java pelo código a seguir:

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

Esse código cria uma conexão WebSocket que está conectada a um hub no Azure Web PubSub. Um hub é uma unidade lógica no Azure Web PubSub onde é possível publicar mensagens para um grupo de clientes. Os principais conceitos contêm a explicação detalhada sobre os termos usados no Azure Web PubSub.

Após a conexão ser estabelecida, seu cliente receberá mensagens pela conexão WebSocket. Use onMessage(String message) para escutar mensagens de entrada.

Para iniciar o aplicativo do assinante, acesse o diretório webpubsub-quickstart-subscriber e execute o comando a seguir. Substitua <Web-PubSub-connection-string> pela cadeia de conexão copiada 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. Publicar mensagens usando o SDK de serviço

Crie um publicador usando o SDK do Azure Web PubSub para publicar uma mensagem para o cliente conectado. Para esse projeto, você precisará abrir outro shell de comando.

Primeiro, crie um diretório de projeto chamado publisher e instale as dependências necessárias:
```
mkdir publisher
cd publisher
dotnet new console
dotnet add package Azure.Messaging.WebPubSub
```

Atualize o arquivo Program.cs para usar a classe WebPubSubServiceClient e enviar mensagens para os 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);
        }
    }
}

A chamada SendToAllAsync() simplesmente envia uma mensagem a todos os clientes conectados no hub.

Envie uma mensagem executando o comando a seguir. Substitua <Web-PubSub-connection-string> pela cadeia de conexão copiada anteriormente.
```
dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Verifique se o shell de comando do assinante recebe a mensagem:
```
Message received: Hello World
```

Primeiro, crie um diretório de projeto chamado publisher e instale as dependências necessárias:
```
mkdir publisher
cd publisher
npm init -y
npm install --save @azure/web-pubsub
```

Use o SDK do Azure Web PubSub para publicar uma mensagem no serviço. Crie um arquivo publish.js com o código a seguir:

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

A chamada service.sendToAll() simplesmente envia uma mensagem a todos os clientes conectados em um hub.

Para enviar uma mensagem, execute o comando a seguir substituindo <Web-PubSub-connection-string> pela cadeia de conexão copiada anteriormente. Se você estiver usando o shell de comando do Windows, poderá usar set em vez de export.
```
export WebPubSubConnectionString=<Web-PubSub-connection-string>
node publish "Hello World"
```
É possível ver que o assinante recebeu a mensagem:
```
Message received: Hello World
```

Primeiro, crie um diretório de projeto chamado publisher e instale as dependências necessárias:

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

pip install azure-messaging-webpubsubservice

Use o SDK do Azure Web PubSub para publicar uma mensagem para o serviço. Crie um arquivo publish.py com o código a seguir:

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)

O send_to_all() envia uma mensagem a todos os clientes conectados em um hub.

Para enviar uma mensagem, execute o comando a seguir substituindo <Web-PubSub-connection-string> pela cadeia de conexão copiada anteriormente.
```
python publish.py <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Verifique o shell de comando anterior se o assinante recebeu a mensagem:
```
Received message: Hello World
```

Acesse o diretório pubsub. Use o Maven para criar um aplicativo de console publicador webpubsub-quickstart-publisher e acesse o diretório 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

Adicione a dependência do SDK do Azure Web PubSub ao nó dependencies de pom.xml:

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

Use o SDK do Azure Web PubSub para publicar uma mensagem para o serviço. Acesse o diretório /src/main/java/com/webpubsub/quickstart, abra o arquivo App.java no editor e substitua o conteúdo pelo código a seguir:


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

A chamada sendToAll() envia uma mensagem a todos os clientes conectados em um hub.

Para enviar uma mensagem, acesse o diretório webpubsub-quickstart-publisher e execute o projeto usando o comando a seguir. Substitua <Web-PubSub-connection-string> pela cadeia de conexão copiada 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'"
```
É possível ver que o assinante recebeu a mensagem:
```
Message received: Hello World
```

Limpeza

Remova os recursos criados neste início rápido ao excluir o grupo de recursos que os contém.

az group delete --name myResourceGroup --yes

Caso não esteja planejando continuar usando o Azure Cloud Shell, evite acumular custos ao excluir o grupo de recursos que contém a conta de armazenamento associada. O grupo de recursos é chamado cloud-shell-storage-<your-region>. Execute o comando a seguir, substituindo <CloudShellResourceGroup> pelo nome do grupo Cloud Shell.

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

Cuidado

Remover grupos de recursos excluirá todos os recursos, incluindo recursos criados fora do escopo deste tutorial.

Próximas etapas

Este tutorial explica de maneira básica como se conectar ao serviço Web PubSub e publicar mensagens para os clientes conectados.

Confira outros tutoriais para saber mais sobre como usar o serviço.

Tutorial: criar uma sala de chat com o Azure Web PubSub

Explorar mais exemplos do Azure Web PubSub

Compartilhar via