Клиентская библиотека Web PubSub для JavaScript

Статья
04/24/2024

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

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

Как показано на схеме ниже, клиенты устанавливают подключения WebSocket к ресурсу Web PubSub. Эта клиентская библиотека:

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

Переполнения

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

Эта библиотека размещается в NPM.

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

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

LTS версии Node.js

Предварительные требования

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

npm install @azure/web-pubsub-client

2. Подключение к ресурсу Web PubSub

Клиент использует URL-адрес клиентского доступа для подключения и проверки подлинности в службе, что соответствует шаблону wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. У клиента может быть несколько способов получения URL-адреса клиентского доступа. Для этого краткого руководства вы можете скопировать и вставить его на портале Azure, как показано ниже. (В рабочей среде клиенты обычно получают URL-адрес клиентского доступа на сервере приложений. См. подробные сведения ниже )

get_client_url

Как показано на схеме выше, клиент имеет разрешения на отправку сообщений в определенную группу с именем 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. Присоединение к группам

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

// ...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. Отправка сообщений в группу

// ...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.

Примеры

Добавление обратных вызовов для подключенных, отключенных и остановленных событий

Если клиент успешно подключен к ресурсу connected Web PubSub, событие активируется.

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

Если клиент отключен и не удается восстановить подключение, disconnected активируется событие .

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

Событие stopped активируется, когда клиент отключается и клиент перестает пытаться повторно подключиться. Обычно это происходит после client.stop() вызова или autoReconnect отключения или достижения указанного ограничения на попытку повторного подключения. Если вы хотите перезапустить клиент, можно вызвать client.start() в событии stopped.

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

Использование сервера согласования для программного создания URL-адреса клиентского доступа

В рабочей среде клиенты обычно получают URL-адрес клиентского доступа с сервера приложений. Сервер содержит строка подключения к ресурсу Web PubSub и создает URL-адрес клиентского доступа с помощью серверной библиотеки @azure/web-pubsub.

1. Сервер приложений

Приведенный ниже фрагмент кода является примером того, как сервер приложений предоставляет /negotiate путь и возвращает URL-адрес клиентского доступа.

// 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. На стороне клиента

Приведенный ниже фрагмент кода является примером клиентской стороны.

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

Полный код этого примера см. в разделе samples-browser.

Клиент использует сообщения с сервера приложений или присоединенных групп.

Клиент может добавлять обратные вызовы для использования сообщений с сервера приложений или групп. Обратите внимание, что для group-message события клиент может получать только групповые сообщения, к которым он присоединился.

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

Ошибка повторного заполнения

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

Однако следует помнить об autoRejoinGroupограничениях.

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

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

Операция и повторная попытка

По умолчанию операция, например client.joinGroup(), client.leaveGroup(), client.sendToGroup(), имеет client.sendEvent() три повторных попытки. Вы можете настроить с помощью messageRetryOptions. Если все повторные попытки завершились сбоем, будет выдана ошибка. Вы можете продолжить повторную попытку, передав то же ackId самое, что и предыдущие повторные попытки, чтобы служба Web PubSub удостоверяла операцию.

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

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

Подпротокол можно изменить для использования клиентом. По умолчанию клиент использует .json.reliable.webpubsub.azure.v1 Вы можете использовать json.reliable.webpubsub.azure.v1 или 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() });

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

Подключение

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

Восстановление

Если клиент, использующий надежные протоколы, отключается, новый WebSocket пытается установить, используя идентификатор потерянного подключения. Если новое подключение WebSocket успешно подключено, оно восстанавливается. На протяжении всего времени отключения клиента служба сохраняет контекст клиента, а также все сообщения, на которые подписан клиент, и при восстановлении клиента служба будет отправлять эти сообщения клиенту. Если служба возвращает код 1008 ошибки WebSocket или попытка восстановления длится более 30 секунд, восстановление завершается ошибкой.

Повтор соединения

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

Концентратор

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

Группа

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

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

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

Время существования клиента

Каждый из клиентов Web PubSub можно безопасно кэшировать и использовать в качестве отдельного клиента на протяжении всего времени существования приложения. Зарегистрированные обратные вызовы событий используют одно и то же время существования с клиентом. Это означает, что вы можете добавлять или удалять обратные вызовы в любое время, а состояние регистрации не изменится после повторного подключения или остановки клиента.

Пакет JavaScript

Чтобы использовать эту клиентную библиотеку в браузере, сначала необходимо использовать средство пакетной установки. Дополнительные сведения о том, как это сделать, см. в нашей документации по объединениям.

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

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

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

export AZURE_LOG_LEVEL=verbose

Более подробные инструкции по включению журналов см. в документации по пакету @azure и средству ведения журнала.

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

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

Дополнительные ресурсы

Дополнительные сведения о разрешениях клиента см. в разделе Разрешения.
Пакет SDK для сервера — документация по JavaScript
Документация по продукту
Примеры

Участие

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

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

Клиентская библиотека Web PubSub для JavaScript

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

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

Предварительные требования

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

2. Подключение к ресурсу Web PubSub

3. Присоединение к группам

4. Отправка сообщений в группу

Примеры

Добавление обратных вызовов для подключенных, отключенных и остановленных событий

Использование сервера согласования для программного создания URL-адреса клиентского доступа

1. Сервер приложений

2. На стороне клиента

Клиент использует сообщения с сервера приложений или присоединенных групп.

Ошибка повторного заполнения

Операция и повторная попытка

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

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

Подключение

Восстановление

Повтор соединения

Концентратор

Группа

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

Время существования клиента

Пакет JavaScript

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

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

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

Дополнительные ресурсы

Участие

Дополнительные ресурсы

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