Biblioteca de cliente Web PubSub para JavaScript

O Azure Web PubSub é um serviço cloud que ajuda os programadores a criar facilmente funcionalidades em tempo real em aplicações Web com padrões de publicação-subscrição em escala.

Qualquer cenário que exija mensagens em tempo real entre o servidor e os clientes ou entre clientes que sigam padrões de publicação-subscrição pode beneficiar da utilização do Web PubSub. Os programadores já não precisam de consultar o servidor enviando pedidos HTTP repetidos em intervalos, o que é desperdiçador e difícil de dimensionar.

Conforme mostrado no diagrama abaixo, os seus clientes estabelecem ligações WebSocket com o recurso Web PubSub. Esta biblioteca de cliente:

• simplifica a gestão de ligações de cliente
• simplifica o envio de mensagens entre clientes
• repetições automáticas após quedas não intencionais da ligação do cliente
• entrega mensagens de forma fiável em número e por ordem após a recuperação de falhas de ligação

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

Esta biblioteca está alojada no NPM.

Introdução

Ambientes atualmente suportados

• Versões LTS do Node.js

Pré-requisitos

• Uma subscrição do Azure
• Um recurso Web PubSub

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

npm install @azure/web-pubsub-client

2. Ligue-se ao recurso Web PubSub

Um cliente utiliza um URL de Acesso de Cliente para se ligar e autenticar com o serviço, que segue um padrão de wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Um cliente pode ter algumas formas de obter o URL de Acesso do Cliente. Para este guia de introdução, pode copiar e colar um no Portal do Azure apresentado abaixo. (Para produção, os seus clientes geralmente obtêm o URL de Acesso do Cliente genegrado no servidor da aplicação. Veja os detalhes abaixo )

Conforme mostrado no diagrama acima, o cliente tem as permissões para enviar mensagens e aderir a um grupo específico com o nome "group1".

// Imports the client libray
const { WebPubSubClient } = require("@azure/web-pubsub-client");

// Instantiates the client object
const client = new WebPubSubClient("<client-access-url>");

// Starts the client connection with your Web PubSub resource
await client.start();

// ...
// The client can join/leave groups, send/receive messages to and from those groups all in real-time

3. Associar grupos

Tenha em atenção que um cliente só pode receber mensagens de grupos a que tenha aderido e tem de adicionar uma chamada de retorno para especificar a lógica ao receber mensagens.

// ...continues the code snippet from above

// Specifies the group to join
let groupName = "group1";

// Registers a listener for the event 'group-message' early before joining a group to not miss messages
client.on("group-message", (e) => {
  console.log(`Received message: ${e.message.data}`);
});

// A client needs to join the group it wishes to receive messages from
await client.joinGroup(groupName);

4. Enviar mensagens para um grupo

// ...continues the code snippet from above

// Send a message to a joined group
await client.sendToGroup(groupName, "hello world", "text");

// In the Console tab of your developer tools found in your browser, you should see the message printed there.

Exemplos

Adicionar chamadas de retorno para eventos ligados, desligados e parados

1. Quando um cliente é ligado com êxito ao recurso Web PubSub, o evento é acionado connected .

client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});

2. Quando um cliente está desligado e não consegue recuperar a ligação, o evento é acionado disconnected .

client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});

3. O stopped evento será acionado quando o cliente estiver desligado e o cliente deixar de tentar restabelecer a ligação. Normalmente, isto acontece depois de ser client.stop() chamado, ou autoReconnect está desativado ou foi atingido um limite especificado para tentar restabelecer a ligação. Se quiser reiniciar o cliente, pode ligar client.start() no evento parado.

// Registers a listener for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Utilizar um servidor de negociação para gerar o URL de Acesso de Cliente programaticamente

Na produção, os clientes obtêm normalmente o URL de Acesso do Cliente a partir de um servidor de aplicações. O servidor contém o cadeia de ligação para o recurso Web PubSub e gera o URL de Acesso do Cliente com a ajuda da biblioteca @azure/web-pubsubde servidores .

1. Servidor de aplicações

O fragmento de código abaixo é um exemplo de que um servidor de aplicações expõe um /negotiate caminho e devolve o URL de Acesso ao Cliente.

// This code snippet uses the popular Express framework
const express = require('express');
const app = express();
const port = 8080;

// Imports the server library, which is different from the client library
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
const hubName = 'sample_chat';

const serviceClient = new WebPubSubServiceClient("<web-pubsub-connectionstring>", hubName);

// Note that the token allows the client to join and send messages to any groups. It is specified with the "roles" option.
app.get('/negotiate', async (req, res) => {
  let token = await serviceClient.getClientAccessToken({roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
  res.json({
    url: token.url
  });
});

app.listen(port, () => console.log(`Application server listening at http://localhost:${port}/negotiate`));

2. Lado do cliente

O fragmento de código abaixo é um exemplo do lado do cliente.

const { WebPubSubClient } = require("@azure/web-pubsub-client")

const client = new WebPubSubClient({
  getClientAccessUrl: async () => {
    let value = await (await fetch(`/negotiate`)).json();
    return value.url;
  }
});

await client.start();

Para ver o código completo deste exemplo, veja samples-browser.

Um cliente consome mensagens do servidor da aplicação ou grupos associados

Um cliente pode adicionar chamadas de retorno para consumir mensagens do servidor ou grupos da aplicação. Tenha em atenção que, para group-message o evento, o cliente só pode receber mensagens de grupo que tenha aderido.

// Registers a listener for the "server-message". The callback will be invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.on("server-message", (e) => {
  console.log(`Received message ${e.message.data}`);
});

// Registers a listener for the "group-message". The callback will be invoked when the client receives a message from the groups it has joined.
client.on("group-message", (e) => {
    console.log(`Received message from ${e.message.group}: ${e.message.data}`);
});

Falha ao lidar com a associação

Quando um cliente está desligado e não consegue recuperar, todos os contextos de grupo serão limpos no recurso Web PubSub. Isto significa que, quando o cliente se volta a ligar, tem de voltar a juntar-se a grupos. Por predefinição, o cliente tem autoRejoinGroup a opção ativada.

No entanto, deve estar ciente das autoRejoinGrouplimitações.

• O cliente só pode voltar a associar grupos aos quais está originalmente associado pelo código de cliente e não pelo código do lado do servidor.
• As operações de "voltar a aderir ao grupo" podem falhar devido a vários motivos, por exemplo, o cliente não tem permissão para aderir aos grupos. Nestes casos, tem de adicionar uma chamada de retorno para lidar com esta falha.

// By default autoRejoinGroups=true. You can disable it by setting to false.
const client = new WebPubSubClient("<client-access-url>", { autoRejoinGroups: true });

// Registers a listener to handle "rejoin-group-failed" event
client.on("rejoin-group-failed", e => {
  console.log(`Rejoin group ${e.group} failed: ${e.error}`);
})

Operação e repetição

Por predefinição, a operação, como client.joinGroup(), client.leaveGroup(), client.sendToGroup()client.sendEvent() tem três repetições. Pode configurar através do messageRetryOptions. Se todas as tentativas tiverem falhado, será emitido um erro. Pode continuar a repetir ao transmitir as mesmas ackId repetições anteriores para que o serviço Web PubSub possa deduplicar a operação.

try {
  await client.joinGroup(groupName);
} catch (err) {
  let id = null;
  if (err instanceof SendMessageError) {
    id = err.ackId;
  }
  await client.joinGroup(groupName, {ackId: id});
}

Especificar subprotocol

Pode alterar a subprotocol para ser utilizada pelo cliente. Por predefinição, o cliente utiliza json.reliable.webpubsub.azure.v1. Pode optar por utilizar json.reliable.webpubsub.azure.v1 ou json.webpubsub.azure.v1.

// Change to use json.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonProtocol() });

// Change to use json.reliable.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonReliableProtocol() });

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 Web PubSub. Quando ligado com êxito, é atribuído um ID de ligação exclusivo a esta ligação pelo Web PubSub. Cada um WebPubSubClient cria a sua própria ligação exclusiva.

Recuperação

Se um cliente que utiliza protocolos fiáveis se desligar, um novo WebSocket tenta estabelecer com o ID de ligação da ligação perdida. Se a nova ligação WebSocket estiver ligada com êxito, a ligação será recuperada. Ao longo do tempo em que um cliente é desligado, o serviço mantém o contexto do cliente, bem como todas as mensagens às quais o cliente foi subscrito e, quando o cliente recuperar, o serviço enviará estas mensagens para o cliente. Se o serviço devolver o código 1008 de erro WebSocket ou a tentativa de recuperação durar mais de 30 segundos, a recuperação falhará.

Restabelecer ligação

A reconexão ocorre quando a ligação do cliente é perdida e falha na recuperação. A ligação de ligação inicia uma nova ligação e a nova ligação tem um novo ID de ligação. Ao contrário da recuperação, o serviço trata o cliente reconectado como uma nova ligação de cliente. A ligação de cliente tem de voltar a juntar-se a grupos. Por predefinição, a biblioteca de cliente volta a juntar-se a grupos após a nova ligação.

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

Connections ao Web PubSub pode 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.

Duração do Cliente

Cada um dos clientes Web PubSub é seguro para colocar em cache e ser utilizado como singleton durante a duração da aplicação. As chamadas de retorno de eventos registadas partilham a mesma duração com o cliente. Isto significa que pode adicionar ou remover chamadas de retorno em qualquer altura e o estado de registo não será alterado após a nova ligação ou o cliente ser parado.

Pacote JavaScript

Para utilizar esta biblioteca de cliente no browser, primeiro tem de utilizar um bundler. Para obter detalhes sobre como fazê-lo, veja a nossa documentação de agrupamento.

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.

export AZURE_LOG_LEVEL=verbose

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

• Rastreio Dinâmico

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

Recursos adicionais

• Saiba mais sobre a permissão do cliente, veja permissões

• SDK do Servidor - Documentação do JavaScript

• Documentação do produto

• Amostras

Contribuir

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