Biblioteca de clientes de serviço do Azure Web PubSub para JavaScript – versão 1.1.3

  • Artigo

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

Você pode usar essa biblioteca no lado do servidor de aplicativos para gerenciar as conexões do cliente WebSocket, conforme mostrado no diagrama abaixo:

de estouro.

  • Enviar mensagens para hubs e grupos.
  • Enviar mensagens para determinados usuários e conexões.
  • Organize usuários e conexões em grupos.
  • Fechar conexões
  • Conceder, revogar e verificar permissões para uma conexão existente

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

documentação de referência da API do NPM (pacote dede código-fonte)

Introdução

Ambientes com suporte no momento

Pré-requisitos

  • Uma assinatura do Azure.
  • Uma instância de serviço do Azure Web PubSub existente.

1. Instalar o pacote @azure/web-pubsub

npm install @azure/web-pubsub

2. Criar e autenticar um WebPubSubServiceClient

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

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

Você também pode autenticar o WebPubSubServiceClient usando um ponto de extremidade e um AzureKeyCredential:

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

const key = new AzureKeyCredential("<Key>");
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

Ou autentique o WebPubSubServiceClient usando do Azure Active Directory

  1. Instalar a dependência de @azure/identity
npm install @azure/identity
  1. Atualize o código-fonte para usar DefaultAzureCredential:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const { DefaultAzureCredential } = require("@azure/identity");

const key = new DefaultAzureCredential();
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

Principais conceitos

Conexão

Uma conexão, também conhecida como um cliente ou uma conexão de cliente, representa uma conexão WebSocket individual conectada ao serviço Web PubSub. Quando conectado com êxito, 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 uma finalidade, por exemplo, um hub de chat ou um hub de notificação. 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 um serviço do 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 remover a conexão do cliente 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.

Utilizador

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 um único usuário está conectado em vários dispositivos ou várias guias do navegador.

Mensagem

Quando o cliente está conectado, ele pode enviar mensagens para o aplicativo upstream ou receber mensagens do aplicativo upstream por meio da conexão WebSocket.

Exemplos

Obter o token de acesso para um cliente iniciar a conexão WebSocket

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

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Get the access token for the WebSocket client connection to use
let token = await serviceClient.getClientAccessToken();

// Or get the access token and assign the client a userId
token = await serviceClient.getClientAccessToken({ userId: "user1" });

// Or get the access token that the client will join group GroupA when it connects using the access token
token = await serviceClient.getClientAccessToken({ userId: "user1", groups: [ "GroupA" ] });

// return the token to the WebSocket client

Transmitir mensagens para todas as conexões em um hub

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

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Send a JSON message
await serviceClient.sendToAll({ message: "Hello world!" });

// Send a plain text message
await serviceClient.sendToAll("Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToAll(payload.buffer);

Enviar mensagens para todas as conexões em um hub com sintaxe de filtro OData

Detalhes sobre filter sintaxe, consulte sintaxe de filtro OData para o Azure Web PubSub.

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

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Send a JSON message to anonymous connections
await serviceClient.sendToAll(
  { message: "Hello world!" },
  { filter: "userId eq null" }
  );

// Send a text message to connections in groupA but not in groupB
const groupA = 'groupA';
const groupB = 'groupB';
await serviceClient.sendToAll(
  "Hello world!",
  { 
    contentType: "text/plain",
    // use plain text "'groupA' in groups and not('groupB' in groups)"
    // or use the odata helper method
    filter: odata`${groupA} in groups and not(${groupB} in groups)` 
  });

Enviar mensagens para todas as conexões em um grupo

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

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

const groupClient = serviceClient.group("<groupName>");

// Add user to the group
await groupClient.addUser("user1");

// Send a JSON message
await groupClient.sendToAll({ message: "Hello world!" });

// Send a plain text message
await groupClient.sendToAll("Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await groupClient.sendToAll(payload.buffer);

Enviar mensagens para todas as conexões de um usuário

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

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Send a JSON message
await serviceClient.sendToUser("user1", { message: "Hello world!" });

// Send a plain text message
await serviceClient.sendToUser("user1", "Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToUser("user1", payload.buffer);

Verificar se o grupo tem alguma conexão

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

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

const groupClient = serviceClient.group("<groupName>");

// close all the connections in the group
await groupClient.closeAllConnections({ reason: "<closeReason>" });

// check if the group has any connections
const hasConnections = await serviceClient.groupExists("<groupName>");

Acessar a resposta HTTP bruta para uma operação

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

function onResponse(rawResponse) {
  console.log(rawResponse);
}
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

Solucionando problemas

Habilitar logs

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

  • Obtendo 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, você pode examinar os documentos do pacote @azure/agente.

Rastreamento dinâmico

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

Próximas etapas

Examine os exemplos de diretório para obter exemplos detalhados sobre como usar essa biblioteca.

Contribuindo

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