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

O serviço Azure Web PubSub é 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 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:

transbordar .

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

Detalhes sobre os termos usados aqui são descritos na seção Conceitos-chave .

Código-fonte | Pacote (NPM) | Documentação | Documentação do | produtoAmostras

Introdução

Ambientes com suporte no momento

Versões LTS do Node.js

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

import { WebPubSubServiceClient } from "@azure/web-pubsub";

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

Você também pode autenticar o WebPubSubServiceClient usando um endpoint e um AzureKeyCredential:

import { AzureKeyCredential, WebPubSubServiceClient } from "@azure/web-pubsub";

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

Ou autentique o usando o WebPubSubServiceClientAzure Active Directory

Instalar a @azure/identity dependência

npm install @azure/identity

Atualize o código-fonte para usar DefaultAzureCredential:

import { DefaultAzureCredential } from "@azure/identity";
import { WebPubSubServiceClient } from "@azure/web-pubsub";

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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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"] });

Transmitir mensagens para todas as conexões em um hub

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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 a sintaxe, consulte Sintaxe de filtro OData para o Azure Web PubSub.

import { WebPubSubServiceClient, odata } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

import { WebPubSubServiceClient } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

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

function onResponse(rawResponse) {
  console.log(rawResponse);
}

await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

Solucionando problemas

Habilitar logs

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info.

export AZURE_LOG_LEVEL=verbose

Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

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

Rastreamento dinâmico

Use o Rastreamento Dinâmico do portal de serviço Web PubSub para exibir o tráfego dinâmico.

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.

SDK do Microsoft Azure para Javascript

Comentários

Esta página foi útil?

Last updated on 2025-05-17