Enviar mensagens por push de um servidor

Artigo
12/13/2024

O conhecido modelo HTTP de solicitação/resposta foi projetado para ser escalonável e fácil de usar. No entanto, hoje em dia os usuários finais exigem muito mais do que as finalidades para as quais a web foi originalmente projetada. O protocolo HTTP requer que os usuários iniciem a solicitação para receber uma resposta. No entanto, os desenvolvedores precisam de uma maneira de enviar dados do servidor para os clientes sem que estes os solicitem; em outras palavras, precisam "empurrar" (push, em inglês) dados para os clientes, como o lance mais recente de um produto em um site de leilão ou os preços das ações em ritmo de rápida mudança em um aplicativo financeiro.

GIF de um servidor de aplicativos “empurrando” dados para um cliente conectado.

Este guia de início rápido demonstra como fazer para:

cadastrar-se para receber mensagens de um servidor de aplicativos
enviar dados por push de um servidor de aplicativos para todos os clientes conectados

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.

Pré-requisitos

Um recurso do Web PubSub. Se ainda não tiver criado um, você pode seguir as diretrizes em Criar um recurso do Web PubSub
Um editor de códigos, como o Visual Studio Code
Instale as dependências para a linguagem que você planeja usar

Node.js

Criar um cliente assinante

Para se cadastrar para receber mensagens enviadas por push do seu servidor de aplicativos, um cliente, seja um navegador, um aplicativo móvel ou um dispositivo IoT, precisa primeiro se conectar ao seu recurso do Web PubSub e escutar o evento de mensagem apropriado.

Crie um diretório de projeto chamado `subscriber` e instale as dependências necessárias

mkdir subscriber
cd subscriber
npm init -y
    
# The client SDK is available as a module on NPM
npm install @azure/web-pubsub-client

Conecte-se ao seu recurso do Web PubSub e registre um ouvinte para o evento do `server-message`

Um cliente usa uma URL de Acesso de Cliente para se conectar e se autenticar no seu recurso. Essa URL segue um padrão de wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Um cliente pode ter algumas maneiras de obter a URL de Acesso ao cliente. Neste início rápido, você pode copiar e colar uma URL do portal do Azure conforme mostrado no diagrama a seguir. É uma prática recomendada não codificar o URL de Acesso do Cliente no código. No mundo da produção, geralmente configuramos um servidor de aplicativos para retornar essa URL sob demanda. Gerar a URL de Acesso para o Cliente descreve a prática em detalhes.

O diagrama mostra como obter a URL de acesso do cliente.

Conforme mostrado no diagrama acima, o cliente ingressa no hub chamado myHub1.

Na pasta do projeto subscriber, crie um arquivo chamado subscribe.js com o conteúdo a seguir

const { WebPubSubClient } = require("@azure/web-pubsub-client");

// Instantiates the client object
// <client-access-url> is copied from Azure portal mentioned above
const client = new WebPubSubClient("<client-access-url>")

// Registers a handler for the "server-message" event
client.on("server-message", (e) => {
    console.log(`Received message ${e.message.data}`)
});

// Before a client can receive a message, 
// you must invoke start() on the client object.
client.start();

Executar o programa

node subscribe.js

Agora, esse cliente estabelece uma conexão com o seu recurso do Web PubSub e está pronto para receber mensagens enviadas por push do seu servidor de aplicativos.

Crie um diretório de projeto chamado `subscriber` e instale as dependências necessárias

mkdir subscriber
cd subscriber
# Create a .net console app
dotnet new console

# Add the client SDK
dotnet add package Azure.Messaging.WebPubSub.Client --prerelease

Conecte-se ao seu recurso do Web PubSub e registre um ouvinte para o evento do `ServerMessageReceived`

O diagrama mostra como obter a URL de acesso do cliente.

Conforme mostrado no diagrama acima, o cliente ingressa no hub chamado myHub1.

Substitua o código no `Program.cs` pelo código a seguir

using Azure.Messaging.WebPubSub.Clients;

// Instantiates the client object
// <client-access-uri> is copied from Azure portal mentioned above
var client = new WebPubSubClient(new Uri("<client-access-uri>"));
client.ServerMessageReceived += eventArgs =>
{
    Console.WriteLine($"Receive message: {eventArgs.Message.Data}");
    return Task.CompletedTask;
};

client.Connected += eventArgs =>
{
    Console.WriteLine("Connected");
    return Task.CompletedTask;
};

await client.StartAsync();


// This keeps the subscriber active until the user closes the stream by pressing Ctrl+C
var streaming = Console.ReadLine();
while (streaming != null)
{
    if (!string.IsNullOrEmpty(streaming))
    {
        await client.SendToGroupAsync("stream", BinaryData.FromString(streaming + Environment.NewLine), WebPubSubDataType.Text);
    }

    streaming = Console.ReadLine();
}

await client.StopAsync();

Executar o seguinte comando

dotnet run

Agora, esse cliente estabelece uma conexão com o seu recurso do Web PubSub e está pronto para receber mensagens enviadas por push do seu servidor de aplicativos.

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/activ

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.

Executar o seguinte comando

python subscribe.py $connection_string "myHub1"

Crie um diretório de projeto chamado `pubsub`

mkdir pubsub
cd pubsub

Use o Maven para criar um novo aplicativo de console chamado `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.

Execute o aplicativo com o comando a seguir

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="$connection_string 'myHub1'"

Enviar mensagens por push do seu servidor de aplicativos

Agora que já tem um cliente conectado ao seu recurso do Web PubSub, você pode enviar mensagens por push de um servidor de aplicativos a qualquer momento usando o SDK do servidor fornecido pelo Web PubSub.

Crie um diretório de projeto novo chamado `publisher` e instale as dependências necessárias

mkdir publisher
cd publisher

npm init

# This command installs the server SDK from NPM, 
# which is different from the client SDK you used in subscribe.js
npm install --save @azure/web-pubsub

Crie um arquivo `publish.js` com o código a seguir

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

// This is the hub name we used on Azure portal when generating the Client Access URL. 
// It ensures this server can push messages to clients in the hub named "myHub1".
const hub = "myHub1";
    
let server = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);

// By default, the content type is `application/json`. 
// Specify contentType as `text/plain` for this demo.
server.sendToAll(process.argv[2], { contentType: "text/plain" });

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

Obtenha a cadeia de conexão

Importante

Uma cadeia de conexão inclui as informações de autorização necessárias para que o seu aplicativo acesse o serviço Web PubSub. A chave de acesso dentro da cadeia de conexão é semelhante a uma senha raiz para o serviço.

Para este guia de início rápido, vamos obtê-la no portal do Azure conforme mostrado abaixo. Um diagrama mostra como obter a URL de acesso do cliente.

Executar o programa do servidor

Execute os seguintes comandos em um novo shell de comando.

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.

# Set the environment variable for your connection string.
export WebPubSubConnectionString="<Put your connection string here>" 

node publish.js "Hello World"

Observe as mensagens recebidas no lado do cliente

GIF demonstrando como um servidor de aplicativos envia dados por push para o cliente conectado.

Tente executar o mesmo programa de "cadastramento" em diversos shells de comando para incitar mais do que apenas clientes. Assim que o programa "publicar" for executado, você deverá ver mensagens sendo entregues em tempo real para todos esses clientes.

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

Substitua o arquivo `Program.cs` pelo código a seguir

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() envia uma mensagem a todos os clientes conectados no hub.

Executar o programa de servidor para enviar mensagens por push a todos os clientes conectados

$connection_string="<connection-string>"
dotnet run $connection_string "myHub1" "Hello World"

Observe as mensagens recebidas no lado do cliente

# On the command shell used for running the "subscribe" program, you should see the received the messaged logged there. 
# Try running the same "subscribe" program in multiple command shells, which simulates more than clients. 
# Try running the "publish" program several times and you see messages being delivered in real-time to all these clients.   
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 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() envia uma mensagem a todos os clientes conectados em um hub.

Execute o seguinte comando:

python publish.py $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.

Acesse o diretório webpubsub-quickstart-publisher e execute o projeto usando o seguinte comando:

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.quickstart.App" -Dexec.cleanupDaemonThreads=false -Dexec.args="$connection_string 'myHub1' 'Hello World'"

É possível visualizar que o assinante anterior recebeu a mensagem:
```
Message received: Hello World
```

Resumo

Este guia de início rápido demonstra como é fácil enviar mensagens por push de um servidor de aplicativos para todos os clientes conectados em um hub. Além disso, o Web PubSub permite que você envie mensagens por push para:

um subconjunto dos clientes em um hub
um grupo específico em um hub
um subconjunto de clientes em um grupo

Essas APIs permitem uma grande variedade de casos de uso, permitindo que os desenvolvedores se concentrem em uma lógica de negócios exclusiva e, ao mesmo tempo, tenham certeza de que o Web PubSub oferece baixa latência (<100 ms), alta disponibilidade e uma escala gigantesca (+milhões de conexões simultâneas).

Próximas etapas

Na próxima etapa, vamos explorar como trabalhar com o sistema de eventos do Web PubSub necessário para desenvolver aplicativos web completos.

Notificações de eventos de clientes

Compartilhar via

Enviar mensagens por push de um servidor

Pré-requisitos

Criar um cliente assinante

Crie um diretório de projeto chamado `subscriber` e instale as dependências necessárias

Conecte-se ao seu recurso do Web PubSub e registre um ouvinte para o evento do `server-message`

Executar o programa

Crie um diretório de projeto chamado `subscriber` e instale as dependências necessárias

Conecte-se ao seu recurso do Web PubSub e registre um ouvinte para o evento do `ServerMessageReceived`

Substitua o código no `Program.cs` pelo código a seguir

Executar o seguinte comando

Crie um diretório de projeto chamado `subscriber` e instale as dependências necessárias:

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

Executar o seguinte comando

Crie um diretório de projeto chamado `pubsub`

Use o Maven para criar um novo aplicativo de console chamado `webpubsub-quickstart-subscriber`;

Adicione o WebSocket e o SDK do Azure Web PubSub ao nó `dependencies` em `pom.xml`:

Execute o aplicativo com o comando a seguir

Enviar mensagens por push do seu servidor de aplicativos

Crie um diretório de projeto novo chamado `publisher` e instale as dependências necessárias

Crie um arquivo `publish.js` com o código a seguir

Obtenha a cadeia de conexão

Executar o programa do servidor

Observe as mensagens recebidas no lado do cliente

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

Substitua o arquivo `Program.cs` pelo código a seguir

Executar o programa de servidor para enviar mensagens por push a todos os clientes conectados

Observe as mensagens recebidas no lado do cliente

Resumo

Próximas etapas

Comentários

Recursos adicionais

Compartilhar via

Enviar mensagens por push de um servidor

Pré-requisitos

Criar um cliente assinante

Crie um diretório de projeto chamado subscriber e instale as dependências necessárias

Conecte-se ao seu recurso do Web PubSub e registre um ouvinte para o evento do server-message

Executar o programa

Enviar mensagens por push do seu servidor de aplicativos

Crie um diretório de projeto novo chamado publisher e instale as dependências necessárias

Crie um arquivo publish.js com o código a seguir

Obtenha a cadeia de conexão

Executar o programa do servidor

Observe as mensagens recebidas no lado do cliente

Resumo

Próximas etapas

Comentários

Recursos adicionais

Crie um diretório de projeto chamado `subscriber` e instale as dependências necessárias

Conecte-se ao seu recurso do Web PubSub e registre um ouvinte para o evento do `server-message`

Crie um diretório de projeto novo chamado `publisher` e instale as dependências necessárias

Crie um arquivo `publish.js` com o código a seguir