Поделиться через

Клиентская библиотека службы Azure Web PubSub для JavaScript версии 1.1.3

  • Статья

служба Azure Web PubSub — это управляемая Azure служба, которая помогает разработчикам легко создавать веб-приложения с функциями реального времени и шаблоном подписки на публикацию. Любой сценарий, требующий обмена сообщениями публикации и подписки в режиме реального времени между сервером и клиентами или среди клиентов, может использовать службу Azure Web PubSub. Традиционные функции реального времени, которые часто требуют опроса с сервера или отправки HTTP-запросов, также могут использовать службу Azure Web PubSub.

Эту библиотеку можно использовать на стороне сервера приложений для управления клиентскими подключениями WebSocket, как показано на схеме ниже.

переполнение .

  • Отправка сообщений в центры и группы.
  • Отправка сообщений определенным пользователям и подключениям.
  • Упорядочение пользователей и подключений в группы.
  • Закрытие подключений
  • Предоставление, отмена и проверка разрешений для существующего подключения

Сведения об используемых здесь терминах описаны в разделе Основные понятия.

справочная документация по API исходного кода | пакета (NPM) | | документации по продуктам | примеры

Начало работы

Поддерживаемые в настоящее время среды

Необходимые условия

1. Установка пакета @azure/web-pubsub

npm install @azure/web-pubsub

2. Создание и проверка подлинности WebPubSubServiceClient

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

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

Кроме того, можно пройти проверку подлинности WebPubSubServiceClient с помощью конечной точки и AzureKeyCredential:

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

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

Или проверка подлинности WebPubSubServiceClient с помощью Azure Active Directory

  1. Установка зависимости @azure/identity
npm install @azure/identity
  1. Обновите исходный код, чтобы использовать DefaultAzureCredential:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const { DefaultAzureCredential } = require("@azure/identity");

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

Основные понятия

Связь

Подключение, также известное как клиент или подключение клиента, представляет отдельное подключение WebSocket, подключенное к службе Web PubSub. При успешном подключении уникальный идентификатор подключения назначается службе Web PubSub.

Втулка

Концентратор — это логическая концепция для набора клиентских подключений. Обычно используется один концентратор для одной цели, например концентратор чата или концентратор уведомлений. При создании подключения клиента он подключается к концентратору и во время его существования принадлежит к нему. Разные приложения могут совместно использовать одну службу Azure Web PubSub с помощью разных имен концентраторов.

Группа

Группа — это подмножество подключений к концентратору. Вы можете добавить клиентское подключение к группе или удалить клиентское подключение из группы в любое время. Например, когда клиент присоединяется к комнате чата или когда клиент покидает комнату чата, этот номер чата можно рассматривать как группу. Клиент может присоединиться к нескольким группам, а группа может содержать несколько клиентов.

Пользователь

Подключения к Web PubSub могут принадлежать одному пользователю. У пользователя может быть несколько подключений, например при подключении одного пользователя на нескольких устройствах или на нескольких вкладках браузера.

Сообщение

Когда клиент подключен, он может отправлять сообщения в вышестоящее приложение или получать сообщения из вышестоящего приложения через подключение WebSocket.

Примеры

Получение маркера доступа для клиента для запуска подключения 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

Широковещательные сообщения для всех подключений в концентраторе

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

Отправка сообщений во все подключения в концентраторе с помощью синтаксиса фильтра OData

Дополнительные сведения о синтаксисе filter см. в синтаксисе фильтра OData для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)` 
  });

Отправка сообщений всем подключениям в группе

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

Отправка сообщений всем подключениям для пользователя

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

Проверка наличия подключения к группе

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>");

Доступ к необработанным HTTP-ответу для операции

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 });

Устранение неполадок

Включение журналов

Чтобы получить журналы отладки при использовании этой библиотеки, можно задать следующую переменную среды.

  • Получение журналов отладки из клиентской библиотеки SignalR
export AZURE_LOG_LEVEL=verbose

Дополнительные инструкции по включению журналов см. в документации по пакету @azure/loger.

Динамическая трассировка

Используйте live Trace на портале службы Web PubSub для просмотра динамического трафика.

Дальнейшие действия

Ознакомьтесь с примерами каталога, чтобы получить подробные примеры использования этой библиотеки.

Способствует

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по вкладу, чтобы узнать больше о том, как создавать и тестировать код.