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

Клиентский пакет SDK на стороне Web PubSub для JavaScript

  • Статья

Примечание.

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

Клиентский пакет SDK направлен на ускорение рабочего процесса разработчика; в частности,

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

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

Screenshot showing clients establishing WebSocket connection with a Web PubSub resource

Приступая к работе

Необходимые компоненты

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

npm install @azure/web-pubsub-client

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

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

Screenshot showing how to get Client Access Url on Azure portal

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

Azure Web PubSub запускает такие системные события, disconnected как connectedи stopped. Вы можете зарегистрировать обработчики событий, чтобы решить, что должно делать программа при запуске событий.

  1. Когда клиент успешно подключен к ресурсу Web PubSub, connected событие активируется. Этот фрагмент просто выводит идентификатор подключения.
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. Если клиент отключен и не сможет восстановить подключение, disconnected событие активируется. Этот фрагмент просто выводит сообщение.
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
  1. Событие stopped активируется при отключении клиента, и клиент перестает пытаться повторно подключиться. Обычно это происходит после client.stop() вызова или autoReconnect отключения или указанного ограничения на попытку повторного подключения. Если вы хотите перезапустить клиент, можно вызвать client.start() в остановленном событии.
// Registers an event handler for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Использование сервера приложений для создания Client Access URL программных способов

В рабочей среде клиенты обычно извлекают Client Access URL данные с сервера приложений. Сервер хранит connection string ресурс Web PubSub и создает Client Access URL справку из серверной библиотеки @azure/web-pubsub.

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

Фрагмент кода является примером сервера приложений, предоставляющего конечную точку и возвращаемую /negotiate Client Access 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();

Примечание.

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

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

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

// Registers a listener for the "server-message". The callback is 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 is 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}`);
});

Примечание.

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

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

При отключении клиента и сбое восстановления все контексты группы удаляются в ресурсе 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});
}

Пакет JavaScript

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

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

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

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

export AZURE_LOG_LEVEL=verbose

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

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

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