Manipuladores de CloudEvents para Expresso do Azure Web PubSub

  • Artigo

O serviço Azure Web PubSub é um serviço gerenciado do Azure que ajuda os desenvolvedores a criar aplicativos Web de forma fácil com recursos em tempo real e padrão de publicação/assinatura. Qualquer cenário que exija mensagens de publicação/assinatura em tempo real entre o servidor e os clientes ou entre clientes pode usar o serviço Azure Web PubSub. Os recursos tradicionais em tempo real que geralmente exigem a sondagem do servidor ou o envio de solicitações HTTP também podem usar o serviço Azure Web PubSub.

Quando uma conexão WebSocket se conecta, o serviço Web PubSub transforma o ciclo de vida de conexão e as mensagens em eventos no formato CloudEvents. Essa biblioteca fornece um middleware expresso para lidar com eventos que representam o ciclo de vida e as mensagens da conexão WebSocket, conforme mostrado no diagrama abaixo:

cloudevents

Os detalhes sobre os termos usados aqui são descritos na seção Principais conceitos.

Pacote de | Código-fonte (NPM) | Documentação de referência da API | Documentação do produto | Exemplos

Introdução

Ambientes com suporte no momento

Pré-requisitos

1. Instalar o pacote @azure/web-pubsub-express

npm install @azure/web-pubsub-express

2. Criar uma WebPubSubEventHandler

const express = require("express");

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

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Principais conceitos

Conexão

Uma conexão, também conhecida como cliente ou conexão cliente, representa uma conexão do WebSocket individual ao serviço Web PubSub. Quando conectado com sucesso, uma ID de conexão exclusiva é atribuída a essa conexão pelo serviço Web PubSub.

Hub

Um hub é um conceito lógico para um conjunto de conexões de cliente. Normalmente, você usa um hub para cada finalidade específica, por exemplo, o hub de chat ou o hub de notificações. Quando uma conexão de cliente é criada, ela se conecta a um hub e, durante seu tempo de vida, pertence a esse hub. Aplicativos diferentes podem compartilhar o mesmo serviço Azure Web PubSub usando nomes de hub diferentes.

Grupo

Um grupo é um subconjunto de conexões com o hub. Você pode adicionar uma conexão de cliente a um grupo ou removê-la do grupo sempre que desejar. Por exemplo, quando um cliente entra em uma sala de chat ou quando um cliente sai da sala de chat, essa sala de chat pode ser considerada um grupo. Um cliente pode ingressar em vários grupos e um grupo pode conter vários clientes.

Usuário

As conexões com o Web PubSub podem pertencer a um usuário. Um usuário pode ter várias conexões, por exemplo, quando apenas um usuário está conectado a vários dispositivos ou a várias guias do navegador.

Eventos do Cliente

Os eventos são criados durante o ciclo de vida de uma conexão de cliente. Por exemplo, uma conexão de cliente WebSocket simples cria um evento connect quando ele tenta se conectar ao serviço, um evento connected quando ele se conectou com êxito ao serviço, um evento message quando ele envia mensagens para o serviço e um evento disconnected quando ele se desconecta do serviço.

Manipulador de Eventos

O manipulador de eventos contém a lógica para manipular os eventos do cliente. O manipulador de eventos precisa ser registrado e configurado no serviço por meio do portal ou CLI do Azure antecipadamente. Em geral, o local para hospedar a lógica do manipulador de eventos é considerado como o lado do servidor.

Exemplos

Manipular a solicitação connect e atribuir <userId>

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      userId: "<userId>"
    });
  },
  allowedEndpoints: ["https://<yourAllowedService>.webpubsub.azure.com"]
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Permitir somente pontos de extremidade especificados

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  allowedEndpoints: [
    "https://<yourAllowedService1>.webpubsub.azure.com",
    "https://<yourAllowedService2>.webpubsub.azure.com"
  ]
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Definir o caminho do manipulador de eventos personalizado

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  path: "customPath1"
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  // Azure WebPubSub Upstream ready at http://localhost:3000/customPath1
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Definir e ler o estado da conexão

const express = require("express");

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

const handler = new WebPubSubEventHandler("chat", {
  handleConnect(req, res) {
    // You can set the state for the connection, it lasts throughout the lifetime of the connection
    res.setState("calledTime", 1);
    res.success();
  },
  handleUserEvent(req, res) {
    var calledTime = req.context.states.calledTime++;
    console.log(calledTime);
    // You can also set the state here
    res.setState("calledTime", calledTime);
    res.success();
  }
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Solução de problemas

Habilitar logs

Você pode definir a variável de ambiente a seguir para obter os logs de depuração ao usar essa biblioteca.

  • Obter logs de depuração da biblioteca de clientes do SignalR
export AZURE_LOG_LEVEL=verbose

Para obter instruções mais detalhadas sobre como habilitar logs, veja os documentos do pacote @azure/logger.

Rastreamento ao vivo

Use o Rastreamento ao Vivo no portal de serviço do Web PubSub para exibir o tráfego ao vivo.

Próximas etapas

Dê uma olhada no diretório de exemplos para obter exemplos detalhados sobre como usar essa biblioteca.

Contribuição

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.