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

Artigo
03/08/2024

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

Neste tutorial, irá aprender a:

Criar uma instância de serviço Web PubSub
Gere a URL completa para estabelecer a conexão WebSocket
Criar um cliente de assinante Web PubSub para receber mensagens usando o protocolo WebSocket padrão
Criar um cliente de editor 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 na sua máquina local, instale a CLI do Azure.

Você pode usar o shell de comando do Windows cmd.exe em vez de um shell Bash para executar os comandos neste tutorial.

Se estiver criando o projeto em uma máquina local, você precisará instalar as dependências para o idioma que está usando:

.NET Core

Configuração da CLI do Azure para desenvolvimento local

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

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

Criar um grupo de recursos

Um grupo de recursos é um contentor lógico no qual os recursos do Azure são implementados e geridos. Use o comando az group create para criar um grupo de recursos nomeado myResourceGroup no eastus local.

az group create --name myResourceGroup --location EastUS

1. Criar uma instância do Azure Web PubSub

Criar uma instância do Web PubSub

Use o comando Azure CLI az webpubsub create para criar um Web PubSub no grupo de recursos que você criou. O comando a seguir cria um recurso Free Web PubSub no grupo myResourceGroup de recursos em EastUS:

Cada recurso Web PubSub deve 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. Tome nota das duas propriedades listadas abaixo:

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

Neste ponto, sua conta do Azure é a única autorizada a executar quaisquer operações neste novo recurso.

Obter a cadeia de ligação

Importante

Uma cadeia de conexão inclui as informações de autorização necessárias para seu aplicativo acessar o serviço Azure Web PubSub. A chave de acesso dentro da cadeia de conexão é semelhante a uma senha de root para o seu serviço. Em ambientes de produção, tenha sempre o cuidado de proteger as suas chaves de acesso. Use o Azure Key Vault para gerenciar e girar suas chaves com segurança. Evite distribuir chaves de acesso para outros usuários, codificá-las ou salvá-las em qualquer lugar em texto simples acessível a outras pessoas. Rode as chaves se acreditar que podem ter sido comprometidas.

Use o comando Azure CLI az webpubsub key para obter o ConnectionString do serviço. Substitua o espaço reservado <your-unique-resource-name> pelo nome da sua 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 Azure Web PubSub por meio do protocolo WebSocket padrão usando a autenticação JSON Web Token (JWT). O SDK de serviço fornece métodos auxiliares para gerar o token. Neste tutorial, o assinante gera diretamente o token de 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 Criar um aplicativo de bate-papo.

Primeiro, crie um diretório de projeto nomeado subscriber para este projeto e instale as dependências necessárias:
- O pacote Websocket.Client é um pacote de terceiros que suporta conexões WebSocket. Você pode usar qualquer API/biblioteca que suporte WebSocket.
- O pacote Azure.Messaging.WebPubSub SDK 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 no Program.cs com o seguinte código que se conectará 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 conceitos-chave contêm a explicação detalhada sobre os termos usados no Web PubSub.

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

Depois que a conexão é estabelecida, seu cliente recebe mensagens através da conexão WebSocket. O cliente usa client.MessageReceived.Subscribe(msg => ...)); para ouvir as mensagens recebidas.

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 WebSocket para se conectar ao serviço Web PubSub. Crie um subscribe.js arquivo com o seguinte código:
```
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 conceitos-chave contêm a explicação detalhada sobre os termos usados no Web PubSub.

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

Depois que a conexão é estabelecida, seu cliente recebe mensagens através da conexão WebSocket. O cliente usa client.MessageReceived.Subscribe(msg => ...)); para ouvir as mensagens recebidas.
Execute o seguinte comando 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 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 WebSocket para se conectar ao serviço Web PubSub. Crie um subscribe.py arquivo com o seguinte código:
```
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 conceitos-chave contêm a explicação detalhada sobre os termos usados no Web PubSub.

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

Depois que a conexão for estabelecida, seu cliente receberá mensagens através da conexão WebSocket. Use await ws.recv() para ouvir as mensagens recebidas.
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 nomeado pubsub para este tutorial.
```
mkdir pubsub
cd pubsub
```

Dentro do diretório, use o pubsub Maven para criar um novo aplicativo de console chamado webpubsub-quickstart-subscriber, em seguida, vá para 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 dependencies SDK do Azure Web PubSub ao nó em pom.xml:
- azure-messaging-webpubsub: SDK do serviço Web PubSub para Java
- Java-WebSocket: SDK do 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>
```
No Web PubSub, você pode se conectar ao serviço e assinar mensagens por meio de conexões WebSocket. WebSocket é um canal de comunicação full-duplex que permite ao serviço enviar mensagens para o seu cliente em tempo real. Você pode usar qualquer API ou biblioteca que ofereça suporte a WebSocket. Para este exemplo, usamos o pacote Java-WebSocket.
Vá para o diretório /src/main/java/com/webpubsub/quickstart .

Editar substitua o conteúdo do arquivo App.java com o seguinte código:

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 conectada a um hub no Azure Web PubSub. Um hub é uma unidade lógica no Azure 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 Azure Web PubSub.

Depois que a conexão for estabelecida, seu cliente receberá mensagens através da conexão WebSocket. Use onMessage(String message) para ouvir as mensagens recebidas.

Para iniciar o aplicativo de assinante, vá para o diretório webpubsub-quickstart-subscriber e execute o seguinte comando. 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 do serviço

Crie um editor usando o SDK do Azure Web PubSub para publicar uma mensagem no cliente conectado. Para este 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 Program.cs arquivo para usar a WebPubSubServiceClient classe 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 SendToAllAsync() chamada simplesmente envia uma mensagem para todos os clientes conectados no hub.

Envie uma mensagem executando o seguinte comando. Substitua <Web-PubSub-connection-string> pela cadeia de conexão copiada anteriormente.
```
dotnet run <Web-PubSub-connection-string> "myHub1" "Hello World"
```
Verifique o shell de comando do assinante para ver se ele 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
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 publish.js arquivo com o código abaixo:

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 service.sendToAll() chamada simplesmente envia uma mensagem para todos os clientes conectados em um hub.

Para enviar uma mensagem, execute o seguinte comando 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"
```
Você pode 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 no serviço. Crie um publish.py arquivo com o código abaixo:

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() enviar a mensagem para todos os clientes conectados em um hub.

Para enviar uma mensagem, execute o seguinte comando 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 para que o assinante recebeu a mensagem:
```
Received message: Hello World
```

Vá para o pubsub diretório. Use o Maven para criar um aplicativo webpubsub-quickstart-publisher de console do publisher e vá para 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 dependencies nó 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 no serviço. Vá para o diretório /src/main/java/com/webpubsub/quickstart , abra o arquivo App.java no editor e substitua o conteúdo pelo seguinte código:


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 sendToAll() chamada envia uma mensagem para todos os clientes conectados em um hub.

Para enviar uma mensagem, vá para o diretório webpubsub-quickstart-publisher e execute o projeto usando o seguinte comando. Substitua o <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'"
```
Você pode ver que o assinante recebeu a mensagem:
```
Message received: Hello World
```

Limpeza

Você pode excluir os recursos criados neste início rápido excluindo o grupo de recursos que os contém.

az group delete --name myResourceGroup --yes

Se você não estiver planejando continuar usando o Azure Cloud Shell, poderá evitar o acúmulo de custos excluindo o grupo de recursos que contém a conta de armazenamento associada. O grupo de recursos é denominado cloud-shell-storage-<your-region>. Execute o seguinte comando, substituindo <CloudShellResourceGroup> pelo nome do grupo do Cloud Shell.

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

Atenção

A exclusão de grupos de recursos excluirá todos os recursos, incluindo recursos criados fora do escopo deste tutorial.

Próximos passos

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

Confira outros tutoriais para se aprofundar em como usar o serviço.

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

Explore mais exemplos do Azure Web PubSub

Share via

Pré-requisitos

Preparar o ambiente

Configuração da CLI do Azure para desenvolvimento local

Criar um grupo de recursos

1. Criar uma instância do Azure Web PubSub

Criar uma instância do Web PubSub

Obter a cadeia de ligação

Criar um cliente assinante

2. Publicar mensagens usando o SDK do serviço

Limpeza

Próximos passos

Recursos adicionais

Share via

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

Pré-requisitos

Preparar o ambiente

Configuração da CLI do Azure para desenvolvimento local

Criar um grupo de recursos

1. Criar uma instância do Azure Web PubSub

Criar uma instância do Web PubSub

Obter a cadeia de ligação

Criar um cliente assinante

2. Publicar mensagens usando o SDK do serviço

Limpeza

Próximos passos

Recursos adicionais