Partilhar via

Biblioteca de cliente do serviço Azure Web PubSub para JavaScript - versão 1.1.3

  • Artigo

de serviço Web PubSub do Azure é um serviço gerenciado pelo Azure que ajuda os desenvolvedores a criar facilmente aplicativos Web 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 os clientes pode usar o serviço Azure Web PubSub. Os recursos tradicionais em tempo real que geralmente exigem sondagem do servidor ou o 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:

transbordamento .

  • Envie mensagens para hubs e grupos.
  • Envie mensagens para usuários e conexões específicos.
  • Organize usuários e conexões em grupos.
  • Fechar ligaçõ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 conceitos-chave.

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

Primeiros passos

Ambientes atualmente suportados

Pré-requisitos

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

1. Instale 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 Azure Ative Directory

  1. Instalar a dependência @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>");

Conceitos-chave

Ligação

Uma conexão, também conhecida como uma conexão de cliente ou de cliente, representa uma conexão WebSocket individual conectada ao serviço Web PubSub. Quando conectado com êxito, um ID de conexão exclusivo é atribuído 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 sua vida útil, pertence a esse hub. Aplicativos diferentes podem compartilhar um 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 remover a conexão de cliente do grupo, sempre que quiser. 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, através 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

Para obter 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);

Verifique se o grupo tem alguma ligaçã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 });

Solução de problemas

Ativar logs

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

  • Obtendo logs de depuração da biblioteca de cliente do SignalR
export AZURE_LOG_LEVEL=verbose

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

Rastreio em tempo real

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

Próximos passos

Por favor, dê uma olhada no exemplos diretório para obter exemplos detalhados sobre como usar esta biblioteca.

Contribuição

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