Notificações de eventos de clientes
Nos três primeiros artigos de "inícios rápidos", aprendemos dois padrões de comunicação úteis usando o Web PubSub para mensagens em tempo real em escala (milhão+).
- Pub/Sub entre clientes que liberam seu servidor de aplicativos da complexidade de gerenciar conexões persistentes
- Enviar mensagens por push para clientes do servidor de aplicativos assim que novos dados estiverem disponíveis
Neste guia de início rápido, aprenderemos sobre o sistema de eventos do Web PubSub para que o servidor de aplicativos possa reagir a eventos como quando
- um cliente é
connected - um cliente envia um
message, que requer processamento adicional
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
Criar o aplicativo
O Web PubSub é um serviço autônomo para seu servidor de aplicativos. Embora seu aplicativo mantenha sua função como um servidor HTTP tradicional, o Web PubSub cuida da passagem de mensagens em tempo real entre o servidor de aplicativos e os clientes. Primeiro, criamos o programa cliente e, em seguida, o programa de servidor.
Crie o cliente
1. Criar um diretório para o aplicativo cliente
mkdir eventHandlerDemo
cd eventHandlerDemo
# The SDK is available as an NPM module.
npm install @azure/web-pubsub-client
2. Conectar-se ao Web PubSub
Um cliente, seja ele um navegador, um aplicativo móvel ou um dispositivo IoT, usa uma URL de Acesso ao Cliente para se conectar e autenticar com 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.
Crie um arquivo com o nome client.js e adicione o seguinte código
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 to the "connected" event
client.on("connected", (e) => {
console.log(`Connection ${e.connectionId} is connected.`);
});
// You must invoke start() on the client object
// to establish connection with your Web PubSub resource
client.start();
Criar o servidor de aplicativos
1. Instalar express.js e o SDK do servidor Web PubSub
npm init -y
npm install --save express
# Installs the middleware from Web PubSub. This middleware will set up an endpoint for you.
npm install --save @azure/web-pubsub-express
2. Criar um novo arquivo chamado "server.js" que configure um aplicativo expresso vazio
const express = require("express");
const app = express();
app.listen(8080, () => console.log('Server started, listening on port 8080'));
3. Manipular eventos
Com o Web PubSub, quando certas atividades acontecem no lado do cliente (por exemplo, quando um cliente está connected ou disconnected com o recurso do Web PubSub), o servidor de aplicativos pode configurar manipuladores para reagir a esses eventos.
Aqui estão dois casos de uso notáveis:
- quando um cliente está conectado, você pode transmitir essa status para todos os clientes conectados
- quando um cliente envia uma mensagem para o recurso Web PubSub, você pode persistir a mensagem em um banco de dados de sua escolha
const express = require("express");
const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const app = express();
const HUB_NAME = "myHub1";
let handler = new WebPubSubEventHandler(HUB_NAME, {
path: '/eventhandler', // Exposes an endpoint
onConnected: async (req) => {
console.log(`${req.context.userId} connected`);
},
});
// Registers the middleware with the express app
app.use(handler.getMiddleware());
app.listen(8080, () => console.log('Server started, listening on port 8080'));
Conforme configurado no código acima, quando um cliente se conecta com o recurso Web PubSub, o Web PubSub invoca o Webhook servido pelo seu servidor de aplicativos no caminho /eventhandler. Aqui, simplesmente imprimimos o userId no console quando um usuário está conectado.
Expor o localhost
Execute o programa, ele deve estar em execução em localhost na porta 8080. Para nossa finalidade, isso significa que seu aplicativo expresso local não pode ser acessado na internet. Portanto, o Web PubSub não pode invocar o Webhook servido no caminho /eventhandler.
Há duas maneiras de rotear o tráfego para seu localhost, uma é expor localhost para ser acessível na internet usando ferramentas como ngrok e TunnelRelay. Outra maneira, e também a maneira recomendada é usar o túnel awps para encapsular o tráfego do serviço Web PubSub através da ferramenta para o servidor local.
1. Baixe e instale o awps-tunnel
A ferramenta é executada no Node.js versão 16 ou superior.
npm install -g @azure/web-pubsub-tunnel-tool
2. Use a cadeia de conexão de serviço e execute
export WebPubSubConnectionString="<your connection string>"
awps-tunnel run --hub myHub1 --upstream http://localhost:8080
Defina o manipulador de eventos em seu recurso do Web PubSub
Agora, precisamos informar o recurso Web PubSub sobre essa URL do Webhook. Você pode definir os manipuladores de eventos no portal do Azure ou na CLI do Azure.
Selecione "Configurações" no menu e selecione "Adicionar"
Insira um nome para o hub. Para nossa finalidade, insira "myHub1" e selecione "Adicionar"
Na página do manipulador de eventos, configure os seguintes campos, ao usar
awps-tunnela ferramenta, o modelo de URL usatunnelo esquema seguido pelo caminho:tunnel:///eventhandler
Salve a configuração
Execute os programas
Inicie o servidor de aplicativos
node server.js
Iniciar o programa cliente
node client.js
Observe o resultado
Você deverá ver userId impresso no console.
Manipular eventos de mensagem
Além de eventos do sistema como connect, connected, disconnected, um cliente também pode enviar eventos personalizados .
Modifique o programa cliente
Interrompa o programa cliente e adicione o código a seguir em client.js
// ...code from before
client.start();
// The name of the event is message and the content is in text format.
client.sendEvent("message", "sending custom event!", "text");
Modifique o programa do servidor
Interrompa o programa cliente e adicione o código a seguir em server.js
// ... code from before
let handler = new WebPubSubEventHandler(HUB_NAME, {
path: "/eventhandler",
onConnected: async (req) => {
console.log(`"${req.context.userId}" is connected.`);
},
// This handler function will handle user system
handleUserEvent: async (req, res) => {
if (req.context.eventName === "message") {
console.log(`Received message: ${req.data}`);
// Additional logic to process the data,
// e.g save message content to database
// or broadcast the message to selected clients.
}
},
});
//... code from before
Inicie o programa cliente e o programa de servidor novamente
Você deve ver userId e Received message: sending custom event! impresso no console.
Resumo
Este tutorial proporciona uma ideia básica de como o sistema de eventos funciona no Web PubSub. Em aplicativos do mundo real, o sistema de eventos pode ajudá-lo a implementar mais lógica para processar eventos gerados pelo sistema e pelo usuário.