Partilhar via

Processadores do Azure Web PubSub CloudEvents para Express

  • Artigo

O serviço Azure Web PubSub é um serviço gerido pelo Azure que ajuda os programadores a criar facilmente aplicações Web com funcionalidades em tempo real e padrão de publicação-subscrição. Qualquer cenário que exija mensagens de publicação e subscrição em tempo real entre o servidor e os clientes ou entre clientes pode utilizar o serviço PubSub do Azure Web. As funcionalidades tradicionais em tempo real que muitas vezes requerem consultas a partir do servidor ou a submissão de pedidos HTTP também podem utilizar o serviço PubSub web do Azure.

Quando uma ligação WebSocket se liga, o serviço Web PubSub transforma o ciclo de vida da ligação e as mensagens em eventos no formato CloudEvents. Esta biblioteca fornece um middleware express para processar eventos que representam o ciclo de vida e as mensagens da ligação WebSocket, conforme mostrado no diagrama abaixo:

cloudevents

Os detalhes sobre os termos aqui utilizados estão descritos na secção Principais conceitos .

Código fonte | Pacote (NPM) | Documentação | de referência da APIDocumentação do | produtoExemplos

Introdução

Ambientes atualmente suportados

Pré-requisitos

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

npm install @azure/web-pubsub-express

2. Criar um 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}`)
);

Conceitos-chave

Ligação

Uma ligação, também conhecida como cliente ou ligação de cliente, representa uma ligação WebSocket individual ligada ao serviço Web PubSub. Quando ligado com êxito, é atribuído um ID de ligação exclusivo a esta ligação pelo serviço Web PubSub.

Hub

Um hub é um conceito lógico para um conjunto de ligações de cliente. Normalmente, utiliza um hub para uma finalidade, por exemplo, um hub de chat ou um hub de notificação. Quando uma ligação de cliente é criada, liga-se a um hub e, durante a sua duração, pertence a esse hub. Diferentes aplicações podem partilhar um serviço PubSub web do Azure com nomes de hub diferentes.

Group

Um grupo é um subconjunto de ligações ao hub. Pode adicionar uma ligação de cliente a um grupo ou remover a ligação de cliente do grupo sempre que quiser. Por exemplo, quando um cliente entra numa sala de chat ou quando um cliente sai da sala de chat, esta sala de chat pode ser considerada um grupo. Um cliente pode aderir a vários grupos e um grupo pode conter vários clientes.

Utilizador

As ligações ao Web PubSub podem pertencer a um utilizador. Um utilizador pode ter várias ligações, por exemplo, quando um único utilizador está ligado a vários dispositivos ou a vários separadores do browser.

Eventos do Cliente

Os eventos são criados durante o ciclo de vida de uma ligação de cliente. Por exemplo, uma ligação de cliente WebSocket simples cria um connect evento quando tenta ligar ao serviço, um connected evento quando está ligado com êxito ao serviço, um message evento quando envia mensagens para o serviço e um disconnected evento quando este se desliga do serviço.

Processador de Eventos

O processador de eventos contém a lógica para processar os eventos do cliente. O processador de eventos tem de ser registado e configurado no serviço através do portal ou da CLI do Azure previamente. Geralmente, o local para alojar a lógica do processador de eventos é considerado do lado do servidor.

Exemplos

Processar o connect pedido 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 apenas pontos finais 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 processador 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 ligaçã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}`)
);

Resolução de problemas

Ativar registos

Pode definir a seguinte variável de ambiente para obter os registos de depuração ao utilizar esta biblioteca.

  • Obter registos de depuração a partir da biblioteca de cliente signalR
export AZURE_LOG_LEVEL=verbose

Para obter instruções mais detalhadas sobre como ativar registos, pode ver os documentos do pacote de @azure/logger.

Rastreio Dinâmico

Utilize o Live Trace a partir do portal do serviço Web PubSub para ver o tráfego em direto.

Passos seguintes

Veja o diretório de exemplos para obter exemplos detalhados sobre como utilizar esta biblioteca.

Contribuir

Se quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.