Tutorial: criar um aplicativo de chat com o serviço Azure Web PubSub

Artigo
04/17/2024

No Tutorial de mensagem de publicação e assinatura, você aprenderá os conceitos básicos de publicação e assinatura de mensagens com o Azure Web PubSub. Neste tutorial, você vai aprender sobre o sistema de eventos do Azure Web PubSub e usá-lo para criar um aplicativo web completo com funcionalidade de comunicação em tempo real.

Neste tutorial, você aprenderá a:

Criar uma instância do serviço Web PubSub
Configurar as definições do manipulador de eventos para o Azure Web PubSub
Lidar com eventos no servidor do aplicativo e criar um aplicativo de chat em tempo real

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Pré-requisitos

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
- Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Essa configuração requer a versão 2.22.0 ou superior da CLI do Azure. Se você está usando o Azure Cloud Shell, a versão mais recente já está instalada.

Criar uma instância do Azure Web PubSub

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

Criar uma instância do Web PubSub

Execute az extension add para instalar ou atualizar a extensão webpubsub para a versão atual.

az extension add --upgrade --name webpubsub

Use o comando az webpubsub create da CLI do Azure para criar um Web PubSub no grupo de recursos criado. O seguinte comando cria um recurso gratuito do Web PubSub no grupo de recursos myResourceGroup no EastUS:

Importante

Cada recurso Web PubSub precisa ter um nome exclusivo. Substitua <nome-de recurso-exclusivo> pelo nome do Web PubSub nos exemplos a seguir.

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

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

Nome do Recurso: o nome que você forneceu ao 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.

Obter o ConnectionString para uso posterior

Importante

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 tenha o cuidado de proteger as chaves de acesso. Utilize o Azure Key Vault para gerenciar e girar suas chaves com segurança. 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.

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.

Copie o ConnectionString buscado e defina-o na variável de ambiente WebPubSubConnectionString, que o tutorial lerá posteriormente. Substitua <connection-string> abaixo pelo ConnectionString buscado.

export WebPubSubConnectionString="<connection-string>"

SET WebPubSubConnectionString=<connection-string>

Configurar o projeto

Pré-requisitos

ASP.NET Core 8

Criar o aplicativo

Há duas funções no Azure Web PubSub, servidor e cliente. Esse conceito é semelhante às funções de servidor e cliente em um aplicativo Web. O servidor é responsável por gerenciar os clientes, escutar e responder às mensagens do cliente. O cliente é responsável por enviar e receber mensagens do usuário do servidor e visualizá-las para o usuário final.

Neste tutorial, vamos criar um aplicativo web de chat em tempo real. Em um aplicativo Web real, a responsabilidade do servidor também inclui a autenticação de clientes e o fornecimento de páginas da Web estáticas para a interface do usuário do aplicativo.

Usaremos o ASP.NET Core 8 para hospedar as páginas da web e lidar com as solicitações de entrada.

Primeiro, vamos criar um aplicativo web do ASP.NET Core em uma pasta chatapp.

Crie um novo aplicativo Web.

mkdir chatapp
cd chatapp
dotnet new web

Adicione app.UseStaticFiles() no Program.cs para dar suporte à hospedagem de páginas da web estáticas.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseStaticFiles();

app.Run();

Crie um arquivo HTML e salve-o como wwwroot/index.html. Vamos usá-lo mais tarde para a interface do usuário do aplicativo de chat.
```
<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
  </body>
</html>
```

Você pode testar o servidor executando dotnet run --urls http://localhost:8080 e acessando http://localhost:8080/index.html no navegador.

Usamos express.js, uma estrutura da web popular para Node.js hospedar as páginas da web e lidar com solicitações de entrada.

Primeiro, vamos criar um aplicativo web expresso em uma pasta chatapp.

Instale o express.js

mkdir chatapp
cd chatapp
npm init -y
npm install --save express

Crie um servidor expresso e salve-o como server.js

const express = require('express');

const app = express();
app.use(express.static('public'));
app.listen(8080, () => console.log('server started'));

Além disso, crie um arquivo HTML e salve-o como public/index.html. Vamos usá-lo mais tarde para a interface do usuário do aplicativo de chat.
```
<html>

<body>
  <h1>Azure Web PubSub Chat</h1>
</body>

</html>
```

Você pode testar o servidor executando node server e acessando http://localhost:8080 no navegador.

Usaremos a estrutura da web Javalin para hospedar as páginas da web e lidar com as solicitações de entrada.

Use o Maven para criar um aplicativo webpubsub-tutorial-chat e alternar para a pasta webpubsub-tutorial-chat:

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

Adicione a dependência da estrutura da web javalin ao nó dependencies do pom.xml:

javalin: estrutura da Web simples para Java
slf4j-simple: agente para Java

<!-- https://mvnrepository.com/artifact/io.javalin/javalin -->
<dependency>
    <groupId>io.javalin</groupId>
    <artifactId>javalin</artifactId>
    <version>6.1.3</version>
</dependency>

<!-- https://mvnrepository.com/artifact/org.slf4j/slf4j-simple -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.12</version>
</dependency>

Acesse o diretório /src/main/java/com/webpubsub/tutorial. Abra o arquivo App.java em seu editor. Use Javalin.create para fornecer arquivos estáticos:

package com.webpubsub.tutorial;

import io.javalin.Javalin;

public class App {
    public static void main(String[] args) {
        // start a server
        Javalin app = Javalin.create(config -> {
            config.staticFiles.add("public");
        }).start(8080);
    }
}

Dependendo da sua configuração, talvez seja necessário definir explicitamente o nível de linguagem como Java 8. Essa etapa pode ser feita no pom.xml. Adicione o seguinte snippet:

<build>
    <plugins>
        <plugin>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.8.0</version>
          <configuration>
            <source>1.8</source>
            <target>1.8</target>
          </configuration>
        </plugin>
    </plugins>
</build>

Crie um arquivo HTML e salvá-lo em /src/main/resources/public/index.html. Vamos usá-lo mais tarde para a interface do usuário do aplicativo de chat.
```
<html>
<body>
  <h1>Azure Web PubSub Chat</h1>
</body>

</html>
```

Você pode testar o servidor executando o comando a seguir no diretório que contém o arquivo pom.xml e acessando http://localhost:8080 no navegador.

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.tutorial.App" -Dexec.cleanupDaemonThreads=false

Usamos o Flask, uma estrutura da web popular para Python para alcançar esse trabalho.

Primeiro, crie uma pasta de projeto chatapp com o Flask pronto.

Criar e ativar o ambiente

mkdir chatapp
cd chatapp
python3 -m venv .venv
. .venv/bin/activate

No ambiente ativado, instale o Flask
```
pip install Flask
```

Depois, crie um servidor do Flask e salve-o como server.py

from flask import (
    Flask, 
    send_from_directory,
)

app = Flask(__name__)

@app.route('/<path:filename>')
def index(filename):
    return send_from_directory('public', filename)

if __name__ == '__main__':
    app.run(port=8080)

Além disso, crie um arquivo HTML e salve-o como public/index.html. Vamos usá-lo mais tarde para a interface do usuário do aplicativo de chat.
```
<html>

<body>
  <h1>Azure Web PubSub Chat</h1>
</body>

</html>
```

Você pode testar o servidor executando python server.py e acessando http://127.0.0.1:8080/index.html no navegador.

Adicionar o ponto de extremidade de negociação

No tutorial Publicar e assinar mensagem, o assinante consome a cadeia de conexão diretamente. Em um aplicativo real, não é seguro compartilhar a cadeia de conexão com nenhum cliente, pois a cadeia de conexão tem alto privilégio para realizar qualquer operação no serviço. Agora, vamos fazer com que o servidor consuma a cadeia de conexão e exponha um ponto de extremidade negotiate para o cliente obter a URL completa com o token de acesso. Dessa forma, o servidor pode adicionar o middleware de autenticação antes do ponto de extremidade negotiate para impedir o acesso não autorizado.

Primeiro, instale as dependências.

dotnet add package Microsoft.Azure.WebPubSub.AspNetCore

Agora, vamos adicionar um ponto de extremidade /negotiate para o cliente chamar para gerar o token.

using Azure.Core;
using Microsoft.Azure.WebPubSub.AspNetCore;
using Microsoft.Azure.WebPubSub.Common;
using Microsoft.Extensions.Primitives;

// Read connection string from environment
var connectionString = Environment.GetEnvironmentVariable("WebPubSubConnectionString");
if (connectionString == null)
{
    throw new ArgumentNullException(nameof(connectionString));
}

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddWebPubSub(o => o.ServiceEndpoint = new WebPubSubServiceEndpoint(connectionString))
    .AddWebPubSubServiceClient<Sample_ChatApp>();
var app = builder.Build();

app.UseStaticFiles();

// return the Client Access URL with negotiate endpoint
app.MapGet("/negotiate", (WebPubSubServiceClient<Sample_ChatApp> service, HttpContext context) =>
{
    var id = context.Request.Query["id"];
    if (StringValues.IsNullOrEmpty(id))
    {
        context.Response.StatusCode = 400;
        return null;
    }
    return new
    {
        url = service.GetClientAccessUri(userId: id).AbsoluteUri
    };
});
app.Run();

sealed class Sample_ChatApp : WebPubSubHub
{
}

AddWebPubSubServiceClient<THub>() é usado para injetar o cliente de serviço WebPubSubServiceClient<THub>, com o qual podemos usar na etapa de negociação para gerar token de conexão de cliente e em métodos de Hub para invocar APIs REST de serviço quando eventos de Hub são disparados. Esse código de geração de token é semelhante ao que usamos no tutorial de mensagem de publicação e assinatura, com a diferença de que passamos um argumento a mais (userId) ao gerar o token. A ID de usuário pode ser usada para identificar a identidade do cliente, para que, ao receber uma mensagem, você saiba de onde ela vem.

O código lê a cadeia de conexão da variável de ambiente WebPubSubConnectionString que definimos na etapa anterior.

Execute novamente o servidor usando dotnet run --urls http://localhost:8080.

Primeiro, instale o SDK do Azure Web PubSub:

npm install --save @azure/web-pubsub

Agora, vamos adicionar uma API /negotiate para gerar o token.

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

const app = express();
const hubName = 'Sample_ChatApp';

let serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hubName);

app.get('/negotiate', async (req, res) => {
    let id = req.query.id;
    if (!id) {
    res.status(400).send('missing user id');
    return;
    }
    let token = await serviceClient.getClientAccessToken({ userId: id });
    res.json({
    url: token.url
    });
});

app.use(express.static('public'));
app.listen(8080, () => console.log('server started'));

Esse código de geração de token é semelhante ao que usamos no tutorial de mensagem de publicação e assinatura, com a diferença de que passamos um argumento a mais (userId) ao gerar o token. A ID de usuário pode ser usada para identificar a identidade do cliente, para que, ao receber uma mensagem, você saiba de onde ela vem.

O código lê a cadeia de conexão da variável de ambiente WebPubSubConnectionString que definimos na etapa anterior.

Execute novamente o servidor executando node server.

Primeiro, adicione a dependência do SDK do Azure Web PubSub e o gson ao nó dependencies de pom.xml:

<!-- https://mvnrepository.com/artifact/com.azure/azure-messaging-webpubsub -->
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.2.12</version>
</dependency>
<!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>

Agora, vamos adicionar uma API /negotiate ao arquivo App.java para gerar o token:

package com.webpubsub.tutorial;
    
import com.azure.messaging.webpubsub.WebPubSubServiceClient;
import com.azure.messaging.webpubsub.WebPubSubServiceClientBuilder;
import com.azure.messaging.webpubsub.models.GetClientAccessTokenOptions;
import com.azure.messaging.webpubsub.models.WebPubSubClientAccessToken;
import com.azure.messaging.webpubsub.models.WebPubSubContentType;
import com.google.gson.Gson;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import io.javalin.Javalin;

public class App {
    public static void main(String[] args) {
        String connectionString = System.getenv("WebPubSubConnectionString");

        if (connectionString == null) {
            System.out.println("Please set the environment variable WebPubSubConnectionString");
            return;
        }

        // create the service client
        WebPubSubServiceClient service = new WebPubSubServiceClientBuilder()
                .connectionString(connectionString)
                .hub("Sample_ChatApp")
                .buildClient();

        // start a server
        Javalin app = Javalin.create(config -> {
            config.staticFiles.add("public");
        }).start(8080);
        
        // Handle the negotiate request and return the token to the client
        app.get("/negotiate", ctx -> {
            String id = ctx.queryParam("id");
            if (id == null) {
                ctx.status(400);
                ctx.result("missing user id");
                return;
            }
            GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
            option.setUserId(id);
            WebPubSubClientAccessToken token = service.getClientAccessToken(option);
            ctx.contentType("application/json");
            Gson gson = new Gson();
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("url", token.getUrl());
            String response = gson.toJson(jsonObject);
            ctx.result(response);
            return;
        });
    }
}

Esse código de geração de token é semelhante ao que usamos no tutorial de mensagem de publicação e assinatura, com a diferença de que chamamos o método setUserId para definir a ID de usuário ao gerar o token. A ID de usuário pode ser usada para identificar a identidade do cliente, para que, ao receber uma mensagem, você saiba de onde ela vem.

O código lê a cadeia de conexão da variável de ambiente WebPubSubConnectionString que definimos na etapa anterior.

Execute novamente o servidor usando os seguintes comandos:

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.tutorial.App" -Dexec.cleanupDaemonThreads=false

Primeiro, instale o SDK do Azure Web PubSub.

pip install azure-messaging-webpubsubservice

Agora, vamos adicionar uma API /negotiate ao servidor para gerar o token.

import os

from flask import (
    Flask, 
    request, 
    send_from_directory,
)

from azure.messaging.webpubsubservice import (
    WebPubSubServiceClient
)

hub_name = 'Sample_ChatApp'
connection_string = os.environ.get('WebPubSubConnectionString')

app = Flask(__name__)
service = WebPubSubServiceClient.from_connection_string(connection_string, hub=hub_name)

@app.route('/<path:filename>')
def index(filename):
    return send_from_directory('public', filename)


@app.route('/negotiate')
def negotiate():
    id = request.args.get('id')
    if not id:
        return 'missing user id', 400

    token = service.get_client_access_token(user_id=id)
    return {
        'url': token['url']
    }, 200

if __name__ == '__main__':
    app.run(port=8080)

Esse código de geração de token é semelhante ao que usamos no tutorial de mensagem de publicação e assinatura, com a diferença de que passamos um argumento a mais (user_id) ao gerar o token. A ID de usuário pode ser usada para identificar a identidade do cliente, para que, ao receber uma mensagem, você saiba de onde ela vem.

O código lê a cadeia de conexão da variável de ambiente WebPubSubConnectionString que definimos na etapa anterior.

Execute novamente o servidor usando python server.py.

Você pode testar essa API acessando http://localhost:8080/negotiate?id=user1 e ele fornecerá a URL completa do Azure Web PubSub com um token de acesso.

Tratar eventos

No Azure Web PubSub, quando houver determinadas atividades acontecendo no lado do cliente (por exemplo, um cliente está se conectando, está conectado, desconectado ou um cliente está enviando mensagens), o serviço envia notificações ao servidor para que ele possa reagir a esses eventos.

Os eventos são entregues ao servidor na forma de webhook. O webhook é servido e exposto pelo servidor de aplicativos e registrado no lado do serviço do Azure Web PubSub. O serviço invoca os webhooks sempre que um evento acontece.

O Azure Web PubSub segue o CloudEvents para descrever os dados do evento.

Abaixo, lidamos com eventos do sistema connected quando um cliente está conectado e lida com eventos de usuário message quando um cliente está enviando mensagens para criar o aplicativo de chat.

O SDK do Web PubSub para AspNetCore Microsoft.Azure.WebPubSub.AspNetCore que instalamos na etapa anterior também pode ajudar a analisar e processar as solicitações do CloudEvents.

Primeiro, adicione manipuladores de eventos antes de app.Run(). Especifique o caminho do ponto de extremidade para os eventos, por exemplo /eventhandler.

app.MapWebPubSubHub<Sample_ChatApp>("/eventhandler/{*path}");
app.Run();

Agora, dentro da classe Sample_ChatApp que criamos na etapa anterior, adicione um construtor para trabalhar com WebPubSubServiceClient<Sample_ChatApp> que usamos para invocar o serviço Web PubSub. E OnConnectedAsync() para responder quando o evento connected é disparado, OnMessageReceivedAsync() para lidar com mensagens do cliente.

sealed class Sample_ChatApp : WebPubSubHub
{
    private readonly WebPubSubServiceClient<Sample_ChatApp> _serviceClient;

    public Sample_ChatApp(WebPubSubServiceClient<Sample_ChatApp> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override async Task OnConnectedAsync(ConnectedEventRequest request)
    {
        Console.WriteLine($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
    }

    public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
    {
        await _serviceClient.SendToAllAsync(RequestContent.Create(
        new
        {
            from = request.ConnectionContext.UserId,
            message = request.Data.ToString()
        }),
        ContentType.ApplicationJson);

        return new UserEventResponse();
    }
}

No código acima, usamos o cliente de serviço para transmitir uma mensagem de notificação no formato JSON a todos os quais está ingressado com SendToAllAsync.

O SDK do Web PubSub para @azure/web-pubsub-express expresso ajuda a analisar e processar as solicitações do CloudEvents.

npm install --save @azure/web-pubsub-express

Atualize server.js com o seguinte código para expor uma API REST em /eventhandler (que é feito pelo middleware expresso fornecido pelo SDK do Web PubSub) para manipular o evento conectado do cliente:

const express = require("express");
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");

const app = express();
const hubName = "Sample_ChatApp";

let serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hubName);

let handler = new WebPubSubEventHandler(hubName, {
  path: "/eventhandler",
  onConnected: async (req) => {
    console.log(`${req.context.userId} connected`);
  },
  handleUserEvent: async (req, res) => {
    if (req.context.eventName === "message")
      await serviceClient.sendToAll({
        from: req.context.userId,
        message: req.data,
      });
    res.success();
  },
});
app.get("/negotiate", async (req, res) => {
  let id = req.query.id;
  if (!id) {
    res.status(400).send("missing user id");
    return;
  }
  let token = await serviceClient.getClientAccessToken({ userId: id });
  res.json({
    url: token.url,
  });
});

app.use(express.static("public"));
app.use(handler.getMiddleware());

app.listen(8080, () => console.log("server started"));

No código acima, onConnected simplesmente imprime uma mensagem no console quando um cliente está conectado. Observe que usamos req.context.userId para que poder ver a identidade do cliente conectado. E handleUserEvent é invocado quando um cliente envia uma mensagem. Ele usa WebPubSubServiceClient.sendToAll() para transmitir a mensagem em um objeto JSON para todos os clientes. Você pode ver que handleUserEvent também tem um objeto res que pode enviar a mensagem de volta para o remetente do evento. Aqui, simplesmente chamamos res.success() para fazer com que o WebHook retorne 200 (observe que essa chamada é obrigatória, mesmo que você não queira retornar nada ao cliente, caso contrário, o WebHook nunca retorna e a conexão do cliente é encerrada).

Por enquanto, você precisa implementar o manipulador de eventos por conta própria em Java. As etapas estão após a especificação de protocolo e ilustradas na lista abaixo:

Adicione o manipulador HTTP para o caminho do manipulador de eventos, por exemplo /eventhandler.
Primeiro, vamos lidar com as solicitações de OPÇÕES de proteção contra abuso. Verifique se o cabeçalho contém o WebHook-Request-Origin e retorne o cabeçalho WebHook-Allowed-Origin. Para simplificar a demonstração, retornamos * para permitir todas as origens.
```
// validation: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#protection
app.options("/eventhandler", ctx -> {
    ctx.header("WebHook-Allowed-Origin", "*");
});
```
Em seguida, queremos verificar se as solicitações de entrada são os eventos desejados. Digamos que agora nos preocupamos com o evento connected do sistema, que deve conter o cabeçalho ce-type como azure.webpubsub.sys.connected. Adicionamos a lógica após a proteção contra abuso para transmitir o evento conectado a todos os clientes para que eles possam ver quem ingressou na sala de chat.
```
// validation: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#protection
app.options("/eventhandler", ctx -> {
    ctx.header("WebHook-Allowed-Origin", "*");
});

// handle events: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#events
app.post("/eventhandler", ctx -> {
    String event = ctx.header("ce-type");
    if ("azure.webpubsub.sys.connected".equals(event)) {
        String id = ctx.header("ce-userId");
        System.out.println(id + " connected.");
    }
    ctx.status(200);
});
```
No código acima, simplesmente imprimimos uma mensagem no console quando um cliente está conectado. Observe que usamos ctx.header("ce-userId") para que poder ver a identidade do cliente conectado.

O ce-type do evento message é sempre azure.webpubsub.user.message. Acesse Mensagem de evento para consultar os detalhes. Atualizamos a lógica para lidar com mensagens para, quando uma mensagem chegar, transmitirmos a mensagem no formato JSON para todos os clientes conectados.

// handle events: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#events
app.post("/eventhandler", ctx -> {
    String event = ctx.header("ce-type");
    if ("azure.webpubsub.sys.connected".equals(event)) {
        String id = ctx.header("ce-userId");
        System.out.println(id + " connected.");
    } else if ("azure.webpubsub.user.message".equals(event)) {
        String id = ctx.header("ce-userId");
        String message = ctx.body();
        Gson gson = new Gson();
        JsonObject jsonObject = new JsonObject();
        jsonObject.addProperty("from", id);
        jsonObject.addProperty("message", message);
        String messageToSend = gson.toJson(jsonObject);
        service.sendToAll(messageToSend, WebPubSubContentType.APPLICATION_JSON);
    }
    ctx.status(200);
});

Por enquanto, você precisa implementar o manipulador de eventos por conta própria em Python. As etapas estão após a especificação de protocolo e estão ilustradas na lista abaixo:

Adicione o manipulador HTTP para o caminho do manipulador de eventos, por exemplo /eventhandler.

Primeiro, vamos lidar com as solicitações de OPÇÕES de proteção contra abuso. Verifique se o cabeçalho contém o WebHook-Request-Origin e retorne o cabeçalho WebHook-Allowed-Origin. Para simplificar a demonstração, retornamos * para permitir todas as origens.

# validation: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#protection
@app.route('/eventhandler', methods=['OPTIONS'])
def handle_event():
    if request.method == 'OPTIONS':
        if request.headers.get('WebHook-Request-Origin'):
            res = Response()
            res.headers['WebHook-Allowed-Origin'] = '*'
            res.status_code = 200
            return res

Em seguida, queremos verificar se as solicitações de entrada são os eventos desejados. Digamos que agora nos preocupamos com o evento connected do sistema, que deve conter o cabeçalho ce-type como azure.webpubsub.sys.connected. Adicionamos a lógica após a proteção contra abuso:

# validation: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#protection
# handle events: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#events
@app.route('/eventhandler', methods=['POST', 'OPTIONS'])
def handle_event():
    if request.method == 'OPTIONS':
        if request.headers.get('WebHook-Request-Origin'):
            res = Response()
            res.headers['WebHook-Allowed-Origin'] = '*'
            res.status_code = 200
            return res
    elif request.method == 'POST':
        user_id = request.headers.get('ce-userid')
        if request.headers.get('ce-type') == 'azure.webpubsub.sys.connected':
            return user_id + ' connected', 200
        else:
            return 'Not found', 404

No código acima, simplesmente imprimimos uma mensagem no console quando um cliente está conectado. Observe que usamos request.headers.get('ce-userid') para que poder ver a identidade do cliente conectado.

@app.route('/eventhandler', methods=['POST', 'OPTIONS'])
def handle_event():
    if request.method == 'OPTIONS':
        if request.headers.get('WebHook-Request-Origin'):
            res = Response()
            res.headers['WebHook-Allowed-Origin'] = '*'
            res.status_code = 200
            return res
    elif request.method == 'POST':
        user_id = request.headers.get('ce-userid')
        type = request.headers.get('ce-type')
        if type == 'azure.webpubsub.sys.connected':
            print(f"{user_id} connected")
            return '', 204
        elif type == 'azure.webpubsub.user.message':
            # default uses JSON
            service.send_to_all(message={
                'from': user_id,
                'message': request.data.decode('UTF-8')
            })
            # returned message is also received by the client
            return {
                'from': "system",
                'message': "message handled by server"
            }, 200
        else:
            return 'Bad Request', 400

Atualizar a página da web

Agora, vamos atualizar index.html para adicionar a lógica para conectar, enviar mensagem e exibir mensagens recebidas na página.

<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
    <input id="message" placeholder="Type to chat...">
    <div id="messages"></div>
    <script>
      (async function () {
        let id = prompt('Please input your user name');
        let res = await fetch(`/negotiate?id=${id}`);
        let data = await res.json();
        let ws = new WebSocket(data.url);
        ws.onopen = () => console.log('connected');

        let messages = document.querySelector('#messages');
        
        ws.onmessage = event => {
          let m = document.createElement('p');
          let data = JSON.parse(event.data);
          m.innerText = `[${data.type || ''}${data.from || ''}] ${data.message}`;
          messages.appendChild(m);
        };

        let message = document.querySelector('#message');
        message.addEventListener('keypress', e => {
          if (e.charCode !== 13) return;
          ws.send(message.value);
          message.value = '';
        });
      })();
    </script>
  </body>

</html>

Você pode ver no código acima que nos conectamos usamos a API WebSocket nativa no navegador e usamos WebSocket.send() para enviar mensagens e WebSocket.onmessage para ouvir as mensagens recebidas.

Você também pode usar SDKs do cliente para se conectar ao serviço, possibilitando que você use a reconexão automática, tratamento de erros e muito mais.

Falta apenas uma etapa para o chat funcionar. Vamos configurar quais eventos são relevantes para nós e para onde enviar os eventos no serviço do Web PubSub.

Configurar o manipulador de eventos

Definimos o manipulador de eventos no serviço do Web PubSub para informar ao serviço para onde enviar os eventos.

Quando o servidor Web é executado localmente, como o serviço do Web PubSub invoca o localhost se ele não tem nenhum ponto de extremidade acessível pela Internet? Geralmente há duas maneiras. Uma é expor o localhost ao público usando alguma ferramenta de túnel geral. A outra forma é usar awps-tunnel para enviar por túnel o tráfego do serviço do Web PubSub por meio da ferramenta para o servidor local.

Nesta seção, usamos a CLI do Azure para definir os manipuladores de eventos e usar awps-tunnel para rotear o tráfego para localhost.

Definir as configurações do hub

Definimos o modelo de URL para usar o esquema tunnel para que o Web PubSub encaminhe mensagens por meio da conexão de túnel do awps-tunnel. Os manipuladores de eventos podem ser definidos no portal ou na CLI, conforme descrito neste artigo; definimos aqui por meio da CLI. Como ouvimos eventos no caminho /eventhandler como conjuntos de etapas anteriores, definimos o modelo de URL como tunnel:///eventhandler.

Use o comando az webpubsub hub create da CLI do Azure para criar as configurações do manipulador de eventos para o hub Sample_ChatApp.

Importante

Substitua <your-unique-resource-name> pelo nome do recurso Web PubSub criado nas etapas anteriores.

az webpubsub hub create -n "<your-unique-resource-name>" -g "myResourceGroup" --hub-name "Sample_ChatApp" --event-handler url-template="tunnel:///eventhandler" user-event-pattern="*" system-event="connected"

Executar o awps-tunnel localmente

Baixar e instalar awps-tunnel

A ferramenta é executada no Node.js, versão 16 ou superior.

npm install -g @azure/web-pubsub-tunnel-tool

Usar a cadeia de conexão de serviço executar

export WebPubSubConnectionString="<your connection string>"
awps-tunnel run --hub Sample_ChatApp --upstream http://localhost:8080

Executar o servidor Web

Tudo está configurado. Vamos executar o servidor Web e testar o aplicativo de chat na prática.

Agora, execute o servidor usando dotnet run --urls http://localhost:8080.

O exemplo de código completo deste tutorial pode ser encontrado aqui.

Agora, execute o servidor usando o comando abaixo:

mvn compile & mvn package & mvn exec:java -Dexec.mainClass="com.webpubsub.tutorial.App" -Dexec.cleanupDaemonThreads=false

O exemplo de código completo deste tutorial pode ser encontrado aqui.

Abra o http://localhost:8080/index.html. Você pode inserir seu nome de usuário e começar a conversar.

Autenticação lenta com o manipulador de eventos `connect`

Nas seções anteriores, demonstramos como usar o ponto de extremidade negotiate para retornar a URL de serviço do Web PubSub e o token de acesso JWT para que os clientes se conectem ao serviço Web PubSub. Em alguns casos, por exemplo, dispositivos de borda com recursos limitados, os clientes podem preferir se conectar diretamente aos recursos do Web PubSub. Nesses casos, você pode configurar o manipulador de eventos connect para autenticar lentamente os clientes, atribuir ID de usuário aos clientes, especificar os grupos que os clientes ingressarem depois de se conectarem, configurar as permissões que os clientes têm e o subprotocolo WebSocket como a resposta WebSocket ao cliente, etc. Para detalhes, confira especificação do manipulador de eventos de conexão.

Agora, vamos usar o manipulador de eventos connect para obter o semelhante ao que a seção negotiate faz.

Atualizar configurações do hub

Primeiro, vamos atualizar as configurações do hub para incluir também o manipulador de eventos connect, precisamos também permitir a conexão anônima para que os clientes sem o token de acesso JWT possam se conectar ao serviço.

Use o comando az webpubsub hub update da CLI do Azure para criar as configurações do manipulador de eventos para o hub Sample_ChatApp.

Importante

Substitua <your-unique-resource-name> pelo nome do recurso Web PubSub criado nas etapas anteriores.

az webpubsub hub update -n "<your-unique-resource-name>" -g "myResourceGroup" --hub-name "Sample_ChatApp" --allow-anonymous true --event-handler url-template="tunnel:///eventhandler" user-event-pattern="*" system-event="connected" system-event="connect"

Atualizar a lógica upstream para lidar com o evento de conexão

Agora, vamos atualizar a lógica upstream para lidar com o evento de conexão. Podemos também remover o ponto de extremidade negotiate agora.

Como semelhante ao que fazemos no ponto de extremidade negotiate como finalidade de demonstração, também lemos a ID dos parâmetros de consulta. No evento de conexão, a consulta de cliente original é preservada no corpo da solicitação de evento de conexão.

Dentro da classe Sample_ChatApp, substitua OnConnectAsync() para manipular o evento connect:

sealed class Sample_ChatApp : WebPubSubHub
{
    private readonly WebPubSubServiceClient<Sample_ChatApp> _serviceClient;

    public Sample_ChatApp(WebPubSubServiceClient<Sample_ChatApp> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override ValueTask<ConnectEventResponse> OnConnectAsync(ConnectEventRequest request, CancellationToken cancellationToken)
    {
        if (request.Query.TryGetValue("id", out var id))
        {
            return new ValueTask<ConnectEventResponse>(request.CreateResponse(userId: id.FirstOrDefault(), null, null, null));
        }

        // The SDK catches this exception and returns 401 to the caller
        throw new UnauthorizedAccessException("Request missing id");
    }

    public override async Task OnConnectedAsync(ConnectedEventRequest request)
    {
        Console.WriteLine($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
    }

    public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
    {
        await _serviceClient.SendToAllAsync(RequestContent.Create(
        new
        {
            from = request.ConnectionContext.UserId,
            message = request.Data.ToString()
        }),
        ContentType.ApplicationJson);

        return new UserEventResponse();
    }
}

Atualize server.js para lidar com o evento de conexão do cliente:

const express = require("express");
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");

const app = express();
const hubName = "Sample_ChatApp";

let serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hubName);

let handler = new WebPubSubEventHandler(hubName, {
  path: "/eventhandler",
  handleConnect: async (req, res) => {
    if (req.context.query.id){
      res.success({ userId: req.context.query.id });
    } else {
      res.fail(401, "missing user id");
    }
  },
  onConnected: async (req) => {
    console.log(`${req.context.userId} connected`);
  },
  handleUserEvent: async (req, res) => {
    if (req.context.eventName === "message")
      await serviceClient.sendToAll({
        from: req.context.userId,
        message: req.data,
      });
    res.success();
  },
});
app.use(express.static("public"));
app.use(handler.getMiddleware());

app.listen(8080, () => console.log("server started"));

Agora, vamos adicionar a lógica para lidar com o evento de conexão azure.webpubsub.sys.connect:


// validation: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#protection
app.options("/eventhandler", ctx -> {
    ctx.header("WebHook-Allowed-Origin", "*");
});

// handle events: https://video2.skills-academy.com/azure/azure-web-pubsub/reference-cloud-events#connect
app.post("/eventhandler", ctx -> {
    String event = ctx.header("ce-type");
    if ("azure.webpubsub.sys.connect".equals(event)) {
        String body = ctx.body();
        System.out.println("Reading from request body...");
        Gson gson = new Gson();
        JsonObject requestBody = gson.fromJson(body, JsonObject.class); // Parse JSON request body
        JsonObject query = requestBody.getAsJsonObject("query");
        if (query != null) {
            System.out.println("Reading from request body query:" + query.toString());
            JsonElement idElement = query.get("id");
            if (idElement != null) {
                JsonArray idInQuery = query.get("id").getAsJsonArray();
                if (idInQuery != null && idInQuery.size() > 0) {
                    String id = idInQuery.get(0).getAsString();
                    ctx.contentType("application/json");
                    Gson response = new Gson();
                    JsonObject jsonObject = new JsonObject();
                    jsonObject.addProperty("userId", id);
                    ctx.result(response.toJson(jsonObject));
                    return;
                }
            }
        } else {
            System.out.println("No query found from request body.");
        }
        ctx.status(401).result("missing user id");
    } else if ("azure.webpubsub.sys.connected".equals(event)) {
        String id = ctx.header("ce-userId");
        System.out.println(id + " connected.");
        ctx.status(200);
    } else if ("azure.webpubsub.user.message".equals(event)) {
        String id = ctx.header("ce-userId");
        String message = ctx.body();
        service.sendToAll(String.format("{\"from\":\"%s\",\"message\":\"%s\"}", id, message), WebPubSubContentType.APPLICATION_JSON);
        ctx.status(200);
    }
});

Agora, vamos manipular o evento connect do sistema, que deve conter o cabeçalho ce-type como azure.webpubsub.sys.connect. Adicionamos a lógica após a proteção contra abuso:

@app.route('/eventhandler', methods=['POST', 'OPTIONS'])
def handle_event():
    if request.method == 'OPTIONS' or request.method == 'GET':
        if request.headers.get('WebHook-Request-Origin'):
            res = Response()
            res.headers['WebHook-Allowed-Origin'] = '*'
            res.status_code = 200
            return res
    elif request.method == 'POST':
        user_id = request.headers.get('ce-userid')
        type = request.headers.get('ce-type')
        print("Received event of type:", type)
        # Sample connect logic if connect event handler is configured
        if type == 'azure.webpubsub.sys.connect':
            body = request.data.decode('utf-8')
            print("Reading from connect request body...")
            query = json.loads(body)['query']
            print("Reading from request body query:", query)
            id_element = query.get('id')
            user_id = id_element[0] if id_element else None
            if user_id:
                return {'userId': user_id}, 200
            return 'missing user id', 401
        elif type == 'azure.webpubsub.sys.connected':
            return user_id + ' connected', 200
        elif type == 'azure.webpubsub.user.message':
            service.send_to_all(content_type="application/json", message={
                'from': user_id,
                'message': request.data.decode('UTF-8')
            })
            return Response(status=204, content_type='text/plain')
        else:
            return 'Bad Request', 400

Atualizar index.html para conectar-se diretamente

Agora, vamos atualizar a página da Web para conectar-se diretamente ao serviço Web PubSub. Uma coisa a mencionar é que, agora, para fins de demonstração, o ponto de extremidade de serviço do Web PubSub é codificado no código do cliente, atualize o nome do host <the host name of your service> do serviço no html abaixo com o valor de seu próprio serviço. Pode ainda ser útil buscar o valor do ponto de extremidade de serviço do Web PubSub do servidor, oferecendo mais flexibilidade e controlabilidade para onde o cliente se conecta.

<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
    <input id="message" placeholder="Type to chat...">
    <div id="messages"></div>
    <script>
      (async function () {
        // sample host: mock.webpubsub.azure.com
        let hostname = "<the host name of your service>";
        let id = prompt('Please input your user name');
        let ws = new WebSocket(`wss://${hostname}/client/hubs/Sample_ChatApp?id=${id}`);
        ws.onopen = () => console.log('connected');

        let messages = document.querySelector('#messages');
        
        ws.onmessage = event => {
          let m = document.createElement('p');
          let data = JSON.parse(event.data);
          m.innerText = `[${data.type || ''}${data.from || ''}] ${data.message}`;
          messages.appendChild(m);
        };

        let message = document.querySelector('#message');
        message.addEventListener('keypress', e => {
          if (e.charCode !== 13) return;
          ws.send(message.value);
          message.value = '';
        });
      })();
    </script>
  </body>

</html>

Executar novamente o servidor

Agora execute novamente o servidor e visite a página da Web seguindo as instruções anteriores. Se você tiver parado awps-tunnel, execute novamente a ferramenta de túnel.

Próximas etapas

Este tutorial oferece uma ideia básica de como o sistema de eventos funciona no serviço do Azure Web PubSub.

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

Explorar mais exemplos do Azure Web PubSub

Compartilhar via

Tutorial: criar um aplicativo de chat com o serviço Azure Web PubSub

Pré-requisitos

Criar uma instância do Azure Web PubSub

Criar um grupo de recursos

Criar uma instância do Web PubSub

Obter o ConnectionString para uso posterior

Configurar o projeto

Pré-requisitos

Criar o aplicativo

Adicionar o ponto de extremidade de negociação

Tratar eventos

Atualizar a página da web

Configurar o manipulador de eventos

Definir as configurações do hub

Executar o awps-tunnel localmente

Baixar e instalar awps-tunnel

Usar a cadeia de conexão de serviço executar

Executar o servidor Web

Autenticação lenta com o manipulador de eventos `connect`

Atualizar configurações do hub

Atualizar a lógica upstream para lidar com o evento de conexão

Atualizar index.html para conectar-se diretamente

Executar novamente o servidor

Próximas etapas

Comentários

Recursos adicionais

Compartilhar via

Tutorial: criar um aplicativo de chat com o serviço Azure Web PubSub

Pré-requisitos

Criar uma instância do Azure Web PubSub

Criar um grupo de recursos

Criar uma instância do Web PubSub

Obter o ConnectionString para uso posterior

Configurar o projeto

Pré-requisitos

Criar o aplicativo

Adicionar o ponto de extremidade de negociação

Tratar eventos

Atualizar a página da web

Configurar o manipulador de eventos

Definir as configurações do hub

Executar o awps-tunnel localmente

Baixar e instalar awps-tunnel

Usar a cadeia de conexão de serviço executar

Executar o servidor Web

Autenticação lenta com o manipulador de eventos connect

Atualizar configurações do hub

Atualizar a lógica upstream para lidar com o evento de conexão

Atualizar index.html para conectar-se diretamente

Executar novamente o servidor

Próximas etapas

Comentários

Recursos adicionais

Autenticação lenta com o manipulador de eventos `connect`