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

No tutorial Publicar e assinar mensagem, você aprende as noções básicas de publicação e assinatura de mensagens com o Azure Web PubSub. Neste tutorial, você aprende o sistema de eventos do Azure Web PubSub e o usa para criar um aplicativo Web completo com funcionalidade de comunicação em tempo real.

Neste tutorial, irá aprender a:

Criar uma instância de serviço Web PubSub
Definir configurações do manipulador de eventos para o Azure Web PubSub
Manipule eventos no servidor de aplicativos e crie um aplicativo de bate-papo em tempo real

Se não tiver uma conta do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

Use o ambiente Bash no Azure Cloud Shell. Para mais informações, veja Get started with Azure Cloud Shell.
Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Autenticar no Azure usando a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre extensões, consulte Usar e gerenciar extensões com a CLI do Azure.
- Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

Esta configuração requer a versão 2.22.0 ou superior da CLI do Azure. Se estiver 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 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

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 CLI do Azure 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 de recursos myResourceGroup em EastUS:

Importante

Cada recurso Web PubSub deve ter um nome exclusivo. Substitua <your-unique-resource-name> pelo nome do seu 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. Tome nota das duas propriedades listadas abaixo:

Nome do recurso: O nome que você forneceu para o --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.

Obtenha o ConnectionString para uso futuro

Importante

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

Uma cadeia de ligação inclui a informação de autorização que a sua aplicação precisa para aceder ao serviço Azure Web PubSub. A chave de acesso na cadeia de ligação funciona como uma palavra-passe root para o seu serviço. Em ambientes de produção, proteja sempre as suas chaves de acesso. Utilize o Azure Key Vault para gerir e rodar as suas chaves com segurança e proteger a sua ligação com WebPubSubServiceClient.

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. Altere as suas chaves se suspeitar que possam ter sido comprometidas.

Use o comando CLI do Azure 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.

Copie o ConnectionString buscado e defina-o na variável WebPubSubConnectionStringde ambiente , que o tutorial lê posteriormente. Substitua <connection-string> abaixo por ConnectionString que obteve.

export WebPubSubConnectionString="<connection-string>"

SET WebPubSubConnectionString=<connection-string>

Configurar o projeto

Pré-requisitos

ASP.NET Núcleo 8

Criar a aplicação

No Azure Web PubSub, há duas funções, 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, ouvir 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, construímos uma aplicação 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 serviço de páginas da Web estáticas para a interface do usuário do aplicativo.

Usamos o ASP.NET Core 8 para hospedar as páginas da Web e lidar com solicitações recebidas.

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

Crie um novo aplicativo Web.

mkdir chatapp
cd chatapp
dotnet new web

Adicione app.UseStaticFiles() Program.cs para suportar a 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, nós o usamos para a interface do usuário do aplicativo de bate-papo mais tarde.
```
<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 o express.js, um framework web popular para Node.js hospedar as páginas da web e lidar com solicitações recebidas.

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

Instalar o express.js

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

Em seguida, 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, nós o usamos para a interface do usuário do aplicativo de bate-papo mais tarde.
```
<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.

Usamos o framework web Javalin para hospedar as páginas da web e lidar com solicitações recebidas.

Utilize o Maven para criar uma nova aplicação webpubsub-tutorial-chat e mude 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 de trabalho web javalin no nó dependencies de pom.xml:

javalin: framework web simples para Java
slf4j-simple: Registador 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>

Navegue até o diretório /src/main/java/com/webpubsub/tutorial . Abra o ficheiro App.java no editor. Utilize Javalin.create para servir ficheiros 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. Esta etapa pode ser feita no pom.xml. Adicione o seguinte trecho:

<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 salve-o em /src/main/resources/public/index.html. Nós o usamos para a interface do usuário do aplicativo de bate-papo mais tarde.
```
<html>
<body>
  <h1>Azure Web PubSub Chat</h1>
</body>

</html>
```

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

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

Usamos Flask, um framework web popular para Python para realizar este trabalho.

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

Criar e ativar o ambiente

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

Dentro do ambiente ativado, instale o Flask
```
pip install Flask
```

Em seguida, crie um servidor 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, nós o usamos para a interface do usuário do aplicativo de bate-papo mais tarde.
```
<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 ponto de extremidade de negociação

No tutorial Publicar e assinar mensagem, o assinante consome cadeia de conexão diretamente. Numa aplicação real, não é seguro partilhar a cadeia de ligação com nenhum cliente, porque a cadeia de ligação tem privilégios elevados para executar qualquer operação no serviço. Agora, vamos fazer com que o seu servidor consuma a cadeia de ligação e exponha um ponto de extremidade negotiate para que o cliente obtenha o URL completo com o token de acesso. Desta forma, o servidor pode adicionar middleware de autenticação antes do endpoint negotiate para impedir o acesso não autorizado.

Primeiro, instale as dependências.

dotnet add package Microsoft.Azure.WebPubSub.AspNetCore

Agora, vamos adicionar um endpoint /negotiate para o cliente invocar e 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 WebPubSubServiceClient<THub>de serviço , com o qual podemos usar na etapa de negociação para gerar token de conexão do cliente e nos métodos de hub para invocar APIs REST de serviço quando os eventos de hub são acionados. Este código de geração de token é semelhante ao que usamos no tutorial de publicar e assinar mensagem, exceto que passamos mais um argumento (userId) ao gerar o token. O ID de usuário pode ser usado para identificar a identidade do cliente para que, quando você receber uma mensagem, saiba de onde a mensagem está vindo.

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

Volte a executar o servidor com dotnet run --urls http://localhost:8080.

Primeiro instale o SDK do Azure Web PubSub:

npm install --save @azure/web-pubsub

Agora vamos adicionar uma /negotiate API 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'));

Este código de geração de token é semelhante ao que usamos no tutorial de publicar e assinar mensagem, exceto que passamos mais um argumento (userId) ao gerar o token. O ID de usuário pode ser usado para identificar a identidade do cliente para que, quando você receber uma mensagem, saiba de onde a mensagem está vindo.

O código lê a cadeia de conexão da variável WebPubSubConnectionString de ambiente 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 no 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 /negotiate API ao App.java arquivo 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;
        });
    }
}

Este código de geração de token é semelhante ao que usamos no tutorial de publicação e assinatura de mensagens, exceto que chamamos setUserId o método para definir o ID do usuário ao gerar o token. O ID de usuário pode ser usado para identificar a identidade do cliente para que, quando você receber uma mensagem, saiba de onde a mensagem está vindo.

O código lê a cadeia de conexão da variável WebPubSubConnectionString de ambiente 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 /negotiate API 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)

Este código de geração de token é semelhante ao que usamos no tutorial de publicar e assinar mensagem, exceto que passamos mais um argumento (user_id) ao gerar o token. O ID de usuário pode ser usado para identificar a identidade do cliente para que, quando você receber uma mensagem, saiba de onde a mensagem está vindo.

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

Volte a executar o servidor usando python server.py.

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

Processar eventos

No Azure Web PubSub, quando determinadas atividades acontecem no lado do cliente (por exemplo, um cliente está se conectando, 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 sob a forma de um webhook. O Webhook é disponibilizado e exposto pelo servidor da aplicação e registado no serviço 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 connected eventos do sistema quando um cliente está conectado e lidamos com message eventos do usuário quando um cliente está enviando mensagens para criar o aplicativo de bate-papo.

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 final 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> o qual usamos para invocar o serviço Web PubSub. E OnConnectedAsync() para responder quando connected o evento é acionado, 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 para todos os que estão associados ao SendToAllAsync.

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

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

Atualize o server.js com o código seguinte para expor uma API REST em /eventhandler (que é disponibilizada pelo middleware do Express fornecido pelo SDK do Web PubSub) para processar o evento de ligaçã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",
  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 basta imprimir uma mensagem para o console quando um cliente está conectado. Você pode ver que usamos req.context.userId para que possamos 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. Pode ver que handleUserEvent também tem um objeto res onde pode enviar uma mensagem ao remetente do evento. Aqui nós simplesmente chamamos res.success() para fazer o WebHook retornar 200 (note que esta chamada é necessária mesmo que você não queira retornar nada de volta ao cliente, caso contrário, o WebHook nunca retorna e a conexão do cliente fecha).

Por enquanto, você precisa implementar o manipulador de eventos por conta própria em Java. As etapas são diretas seguindo as especificações do protocolo e ilustradas na lista abaixo:

Adicione um manipulador HTTP para o caminho do manipulador de eventos, por exemplo, /eventhandler.
Primeiro, queremos tratar os pedidos OPTIONS de proteção contra abusos; verificamos se o cabeçalho contém o cabeçalho WebHook-Request-Origin e devolvemos o cabeçalho WebHook-Allowed-Origin. Para simplificar, para fins de demonstração, devolvemos * para permitir todas as origens.
```
// validation: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
app.options("/eventhandler", ctx -> {
    ctx.header("WebHook-Allowed-Origin", "*");
});
```
Em seguida, gostaríamos de verificar se as solicitações recebidas são os eventos que esperamos. Digamos que agora nos preocupamos com o evento system connected , 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 entrou na sala de chat.
```
// validation: https://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
app.options("/eventhandler", ctx -> {
    ctx.header("WebHook-Allowed-Origin", "*");
});

// handle events: https://learn.microsoft.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. Você pode ver que usamos ctx.header("ce-userId") para que possamos ver a identidade do cliente conectado.

O ce-type do message evento é sempre azure.webpubsub.user.message. Detalhes, consulte Mensagem do evento. Atualizamos a lógica para lidar com mensagens que, quando uma mensagem chega, transmitimos a mensagem no formato JSON para todos os clientes conectados.

// handle events: https://learn.microsoft.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 são diretas seguindo as especificações do protocolo e são ilustradas na lista abaixo:

Adicione um manipulador HTTP para o caminho /eventhandler do manipulador de eventos.

Primeiro, tratamos os pedidos OPTIONS de proteção contra abusos, verificamos se o cabeçalho contém o cabeçalho WebHook-Request-Origin e devolvemos o cabeçalho WebHook-Allowed-Origin. Para simplificar, para fins de demonstração, devolvemos * para permitir todas as origens.

# validation: https://learn.microsoft.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, gostaríamos de verificar se as solicitações recebidas são os eventos que esperamos. Digamos que agora nos preocupamos com o evento system connected , 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://learn.microsoft.com/azure/azure-web-pubsub/reference-cloud-events#protection
# handle events: https://learn.microsoft.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. Você pode ver que usamos request.headers.get('ce-userid') para que possamos ver a identidade do cliente conectado.

O evento message de ce-type é sempre azure.webpubsub.user.message. Detalhes, consulte Mensagem do evento. Atualizamos a lógica para lidar com mensagens que, quando uma mensagem chega, transmitimos a mensagem para todos os clientes conectados.

@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 Web

Agora vamos atualizar index.html para adicionar a lógica para conectar, enviar mensagens 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>

Pode ver no código acima que usamos a API WebSocket nativa no navegador e WebSocket.send() para enviar mensagens e WebSocket.onmessage para escutar as mensagens recebidas.

Você também pode usar SDKs de cliente para se conectar ao serviço, o que permite que você reconecte automaticamente, tratamento de erros e muito mais.

Agora falta um passo para o bate-papo funcionar. Vamos configurar quais eventos nos interessam e para onde enviá-los no serviço Web PubSub.

Configurar o manipulador de eventos

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

Quando o servidor Web é executado localmente, como o serviço Web PubSub invoca o localhost se ele não tiver um ponto de extremidade acessível pela Internet? Geralmente, há dois caminhos. Uma opção é expor o localhost publicamente usando uma ferramenta genérica de tunelização, e a outra é usar awps-tunnel para encaminhar o tráfego do serviço Web PubSub através dessa ferramenta até ao seu 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 configurações de hub

Definimos o modelo de URL para utilizar o esquema tunnel, para que o Web PubSub encaminhe mensagens através da ligação de túnel do awps-tunnel. Os manipuladores de eventos podem ser definidos a partir do portal ou da CLI, conforme descrito neste artigo, aqui nós o definimos por meio da CLI. Como escutamos os eventos no caminho /eventhandler, conforme definido na etapa anterior, definimos o modelo de URL como tunnel:///eventhandler.

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

Importante

Substitua <your-unique-resource-name> pelo nome do recurso Web PubSub criado a partir das 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 awps-tunnel localmente

Baixe e instale o awps-tunnel

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

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

Utilize a cadeia de ligação ao serviço e execute

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

Executar o servidor Web

Agora está tudo definido. Vamos executar o servidor web e jogar com o aplicativo de bate-papo em ação.

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 http://localhost:8080/index.html. Você pode inserir seu nome de usuário e começar a conversar.

Lazy Auth com o manipulador de eventos `connect`

Nas secções anteriores, mostrámos como usar o ponto final negotiate para devolver o URL do serviço Web PubSub e o token de acesso JWT para os clientes se ligarem ao serviço Web PubSub. Em alguns casos, por exemplo no caso de dispositivos de borda com recursos limitados, os clientes podem preferir uma ligação direta aos recursos do Web PubSub. Nestes casos, é possível configurar o connect manipulador de eventos para efetuar a autenticação diferida dos clientes, atribuir um ID de utilizador aos clientes, especificar os grupos a que os clientes se juntam assim que se ligam, configurar as permissões de que os clientes dispõem e o subprotocolo WebSocket na resposta WebSocket ao cliente, etc. Para mais detalhes, consulte a especificação do manipulador de eventos de ligação.

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

Atualizar configurações do hub

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

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

Importante

Substitua <your-unique-resource-name> pelo nome do recurso Web PubSub criado a partir das 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 a montante para processar o evento de ligação

Agora, vamos atualizar a lógica a montante para processar o evento de ligação. Também poderíamos remover o ponto final de negociação agora.

À semelhança do que fazemos na negociação do ponto final como objetivo de demonstração, também lemos id dos parâmetros de consulta. No evento connect, a consulta do cliente original é preservada no corpo da solicitação de evento connect.

Na classe Sample_ChatApp, redefina OnConnectAsync() para tratar 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 o server.js para tratar o evento de ligaçã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 tratar o evento de ligação azure.webpubsub.sys.connect:


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

// handle events: https://learn.microsoft.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 lidar com o evento system connect , 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 conexão direta

Agora vamos atualizar a página da Web para conexão direta com o serviço Web PubSub. Convém mencionar que, neste momento, para efeitos de demonstração, o ponto final do serviço Web PubSub está definido de forma fixa no código do cliente. Atualize o nome do host do serviço <the host name of your service> no HTML abaixo pelo valor do seu próprio serviço. Pode ainda ser útil obter do seu servidor o valor do ponto final do serviço Web PubSub, pois isso dá-lhe mais flexibilidade e controlo sobre o local ao qual o cliente se liga.

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

Execute novamente o servidor

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

Próximos passos

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

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

Explore mais exemplos do Azure Web PubSub

Comentários

Esta página foi útil?

Last updated on 2026-08-31

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

Obtenha o ConnectionString para uso futuro

Configurar o projeto

Pré-requisitos

Criar a aplicação

Adicionar ponto de extremidade de negociação

Processar eventos

Atualizar a página Web

Configurar o manipulador de eventos

Definir configurações de hub

Executar awps-tunnel localmente

Baixe e instale o awps-tunnel

Utilize a cadeia de ligação ao serviço e execute

Executar o servidor Web

Lazy Auth com o manipulador de eventos connect

Atualizar configurações do hub

Atualizar a lógica a montante para processar o evento de ligação

Atualizar index.html para conexão direta

Execute novamente o servidor

Próximos passos

Comentários

Recursos adicionais

Lazy Auth com o manipulador de eventos `connect`