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

Внутренние компоненты службы Azure Web PubSub

  • Статья

Служба Azure Web PubSub предоставляет простой способ публикации сообщений и подписки на них с помощью простых подключений WebSocket.

  • Клиенты могут быть написаны на любом языке с поддержкой Websocket.
  • Текстовые и двоичные сообщения поддерживаются в одном соединении.
  • Существует простой протокол для клиентов для прямого публикации сообщений между клиентами.
  • Служба управляет подключениями WebSocket для вас.

Условия

  • Служба: служба Azure Web PubSub.

  • Подключение: подключение, также известное как клиент или подключение клиента, это логическая связь между клиентом и службой Web PubSub. Через "подключение" клиент и служба участвуют в ряде взаимодействий с отслеживанием состояния. Подключения , использующие разные протоколы, могут вести себя по-разному, например, некоторые подключения ограничены длительностью сетевого подключения, а другие могут распространяться по нескольким последовательным сетевым подключениям между клиентом и службой.

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

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

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

  • Сообщение. Когда клиент подключен, он может отправлять сообщения в вышестоящее приложение или получать сообщения от него через подключение WebSocket. Сообщения могут находиться в формате обычного текста, двоичного файла или JSON и иметь максимальный размер 1 МБ.

  • Клиентские события: события создаются во время жизненного цикла клиентского подключения. Например, простое клиентское подключение WebSocket создает событие connect при попытке подключиться к службе, событие connected — при успешном подключении к службе, событие message — при отправке сообщений службе и событие disconnected — при отключении от службы. Сведения о событиях клиента показаны в разделе протокола клиента.

  • Обработчик событий: обработчик событий содержит логику для обработки событий клиента. Обработчики событий регистрируются и настраиваются в службе заранее с помощью портала или Azure CLI. Сведения описаны в разделе обработчика событий.

  • Прослушиватель событий(предварительная версия): прослушиватель событий просто прослушивает события клиента, но не может влиять на время существования клиентов через их ответ. Сведения описаны в разделе прослушивателя событий.

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

Рабочий процесс

Схема, на которой показан рабочий процесс службы Web PubSub.

Рабочий процесс, как показано на приведенном выше графике:

  1. Клиент подключается к конечной точке службы /client с помощью транспорта WebSocket. Служба пересылает каждый кадр WebSocket в настроенный вышестоящий сервер. Соединение WebSocket устанавливается с применением любого пользовательского подпротокола, обслуживаемого сервером, или с помощью поддерживаемого службой подпротокола json.webpubsub.azure.v1, что позволяет клиентам выполнять операции публикации и подписки напрямую. Подробности см. в разделе Протокол клиента.
  2. При различных событиях клиента служба вызывает сервер с помощью протокола CloudEvents. CloudEvents — это унифицированное и не зависящее от протокола определение структуры и метаданных для событий, размещенных в среде CNCF. Подробная реализация протокола CloudEvents зависит от роли сервера, описанной в протоколе сервера.
  3. Сервер Web PubSub может вызвать службу с помощью REST API для отправки сообщений клиентам или управления подключенными клиентами. Подробности см. в разделе Протокол сервера.

Протокол клиента

Клиентское соединение устанавливается с конечной точкой /client службы по протоколу WebSocket. Протокол WebSocket поддерживает полнодуплексные каналы связи через одно TCP-подключение и соответствует стандарту IETF RFC 6455 (2011 г.). Большинство языков обладают встроенной поддержкой подключений WebSocket.

Наша служба поддерживает два типа клиентов:

Простой клиент WebSocket

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

Например, в JS простой клиент WebSocket можно создать с помощью следующего кода.

// simple WebSocket client1
var client1 = new WebSocket("wss://test.webpubsub.azure.com/client/hubs/hub1");

// simple WebSocket client2 with some custom subprotocol
var client2 = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "custom.subprotocol"
);

Простой клиент WebSocket следует архитектуре сервера клиента<>, как показано на следующей схеме последовательности:Схема, показывающая последовательность для подключения клиента.

  1. Когда клиент запускает подтверждение WebSocket, служба пытается вызвать connect обработчик событий для подтверждения WebSocket. Разработчики могут использовать этот обработчик для обработки подтверждения WebSocket, определения подпротокола для использования, проверки подлинности клиента и присоединения клиента к группам.
  2. При успешном подключении клиента служба вызывает обработчик событий connected. Он работает как уведомление и не блокирует отправку сообщений клиентом. Разработчики могут использовать этот обработчик для хранения данных и ответить на сообщения клиенту. Служба также отправляет connected событие всем прослушивателям событий, если таковые существуют.
  3. Когда клиент отправляет сообщения, служба активирует message событие обработчику событий для обработки отправленных сообщений. Это событие является общим и содержит сообщения, отправленные в кадре WebSocket. Код должен отправлять сообщения внутри этого обработчика событий. Если обработчик событий возвращает код ответа без успешного выполнения, служба удаляет клиентское подключение. Служба также отправляет message событие всем прослушивателям событий, если таковые существуют. Если служба не может найти зарегистрированные серверы для получения сообщений, служба также удаляет подключение.
  4. При отключении клиента служба пытается активировать disconnected событие обработчику событий после обнаружения отключения. Служба также отправляет disconnected событие всем прослушивателям событий, если таковые существуют.

Сценарии

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

Клиент WebSocket PubSub

Служба также поддерживает подпротокол json.webpubsub.azure.v1, который дает клиентам возможность публиковать данные и подписываться напрямую, без кругового пути к вышестоящему серверу. Подключение WebSocket с подпротоколом json.webpubsub.azure.v1 называется клиентом PubSub WebSocket. Дополнительные сведения см. в спецификации клиента Web PubSub на сайте GitHub.

Например, в JS клиент PubSub WebSocket можно создать с помощью следующего кода.

// PubSub WebSocket client
var pubsub = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);

Клиент WebSocket PubSub может выполнять указанные ниже задачи.

  • Присоединиться к группе, например:

    {
  "type": "joinGroup",
  "group": "<group_name>"
}

  • Покинуть группу, например:

    {
  "type": "leaveGroup",
  "group": "<group_name>"
}

  • Опубликовать сообщение в группе, например:

    {
  "type": "sendToGroup",
  "group": "<group_name>",
  "data": { "hello": "world" }
}

  • Отправить пользовательские события на вышестоящий сервер, например:

    {
  "type": "event",
  "event": "<event_name>",
  "data": { "hello": "world" }
}

Подпротокол WebSocket PubSub содержит подробные сведения о подпротоколе json.webpubsub.azure.v1.

Возможно, вы заметили, что для простого клиента WebSocket сервер должен иметь роль для получения message событий от клиентов. Простое подключение WebSocket всегда активирует событие message при отправке сообщений и всегда подразумевает, что обработка сообщений и другие операции выполняются на стороне сервера. Благодаря подпротоколу json.webpubsub.azure.v1 авторизованный клиент может непосредственно присоединиться к группе и публиковать в ней сообщения. Кроме того, он может направлять сообщения в различные обработчики событий или прослушиватели событий, настраивая событие , к которому относится сообщение.

Сценарии

Такие клиенты применяются, когда клиентам нужно взаимодействовать между собой. Сообщения отправляются службе от client2, а служба доставляет сообщения непосредственно в client1 в том случае, если клиенты имеет на это право.

Клиент1:

var client1 = new WebSocket(
  "wss://xxx.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);
client1.onmessage = (e) => {
  if (e.data) {
    var message = JSON.parse(e.data);
    if (message.type === "message" && message.group === "Group1") {
      // Only print messages from Group1
      console.log(message.data);
    }
  }
};

client1.onopen = (e) => {
  client1.send(
    JSON.stringify({
      type: "joinGroup",
      group: "Group1",
    })
  );
};

Клиент2:

var client2 = new WebSocket("wss://xxx.webpubsub.azure.com/client/hubs/hub1", "json.webpubsub.azure.v1");
client2.onopen = e => {
    client2.send(JSON.stringify({
        type: "sendToGroup",
        group: "Group1",
        data: "Hello Client1"
    });
};

Как показано в примере выше, client2 отправляет данные непосредственно в client1, публикуя сообщения в Group1, где находится client1.

Сводка событий клиента

События клиента делятся на две категории:

  • Синхронные события (блокирующие) блокируют рабочий процесс клиента.
    • connect: это событие предназначено только для обработчика событий. Когда клиент запускает подтверждение WebSocket, событие запускается, и разработчики могут использовать connect обработчик событий для обработки подтверждения WebSocket, определения подпротокола для использования, проверки подлинности клиента и присоединения клиента к группам.
    • message: это событие активируется при отправке клиентом сообщения.
  • Асинхронные события (неблокирующие) асинхронные события не блокируют рабочий процесс клиента, он выступает в качестве некоторого уведомления на сервере. При сбое такого триггера события служба регистрирует ошибку.
    • connected: это событие активируется при успешном подключении клиента к службе.
    • disconnected: это событие активируется при отключении клиента со службой.

Ограничение клиентского сообщения

Максимально допустимый размер сообщения для одного кадра WebSocket — 1 МБ.

Аутентификация клиента

Рабочий процесс проверки подлинности

Клиент использует для подключения к службе подписанный токен JWT. Вышестоящий клиент также может отклонить клиент, когда он является connect обработчиком событий входящего клиента. Обработчик событий проходит проверку подлинности клиента, указав и userId roles клиента в ответе веб-перехватчика или отклонив клиент с 401. Подробности см. в разделе Обработчик событий.

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

Схема, демонстрирующая рабочий процесс проверки подлинности клиента.

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

Роль Разрешение
Не указано Клиент может отправлять события.
webpubsub.joinLeaveGroup Клиент может присоединиться к любой группе или выйти из нее.
webpubsub.sendToGroup Клиент может публиковать сообщения в любой группе.
webpubsub.joinLeaveGroup.<group> Клиент может присоединиться к группе <group> или выйти из нее.
webpubsub.sendToGroup.<group> Клиент может публиковать сообщения в группе <group>.

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

Протокол сервера

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

Как правило, протокол сервера содержит три роли:

  1. Обработчик событий
  2. Connection manager
  3. Прослушиватель событий

Обработчик событий

Обработчик событий обрабатывает входящие события клиента. Обработчики событий регистрируются и настраиваются в службе через портал или Azure CLI. При активации события клиента служба может определить, следует ли обрабатывать событие или нет. Теперь мы используем PUSH режим для вызова обработчика событий. Обработчик событий на стороне сервера предоставляет общедоступную конечную точку службы для вызова при активации события. Он выступает в качестве веб-перехватчика.

Служба Web PubSub предоставляет клиентские события в вышестоящий веб-перехватчик с помощью протокола HTTP CloudEvents.

Для каждого события служба сформулирует HTTP-запрос POST в зарегистрированный вышестоящий и ожидает HTTP-ответ.

Данные, отправляемые из службы на сервер, всегда в формате CloudEvents binary .

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

Вышестоящий компонент и проверка

Перед первым использованием обработчики событий необходимо зарегистрировать и настроить в службе через портал или Azure CLI. При активации события клиента служба может определить, следует ли обрабатывать событие или нет. Для общедоступной предварительной версии мы используем PUSH режим вызова обработчика событий. Обработчик событий на стороне сервера предоставляет общедоступную конечную точку для вызова службы при активации события. Он выступает в качестве вышестоящего веб-перехватчика.

URL-адрес может использовать {event} параметр для определения шаблона URL-адреса для обработчика веб-перехватчика. Служба при получении запроса клиента вычисляет значение URL-адреса веб-перехватчика динамически. Например, при получении запроса /client/hubs/chat при заданном шаблоне URL обработчика событий http://host.com/api/{event} для концентратора chat при подключении клиента сначала будет выполнен запрос POST к этому URL-адресу: http://host.com/api/connect. Это поведение может быть полезно, если клиент PubSub WebSocket отправляет пользовательские события, что обработчик событий помогает отправлять различные события в другой вышестоящий. Параметр {event} не разрешен в доменном имени URL-адреса.

При настройке вышестоящего обработчика событий с помощью портала Azure или интерфейса командной строки для его проверки служба соблюдает правила защиты CloudEvents. В заголовке запроса WebHook-Request-Origin задается доменное имя службы xxx.webpubsub.azure.com, и в ответе доменное имя должно содержаться в заголовке WebHook-Allowed-Origin.

При выполнении проверки параметр {event} разрешается в validate. Например, при попытке задать URL-адрес http://host.com/api/{event}служба пытается настроить запрос и http://host.com/api/validate только в том случае, если ответ действителен, конфигурация может быть успешно задана.

Сейчас мы не поддерживаем webHook-Request-Rate и WebHook-Request-Callback.

Проверка подлинности и авторизация между службой и веб-перехватчиком

  • Анонимный режим
  • Простая проверка подлинности, code предоставляемая через настроенный URL-адрес веб-перехватчика.
  • Используйте авторизацию Microsoft Entra. Дополнительные сведения см. в статье об использовании управляемого удостоверения для получения дополнительных сведений.
    • Шаг 1. Включение удостоверения для службы Web PubSub
    • Шаг 2. Выбор из существующего приложения Microsoft Entra, которое обозначает веб-приложение веб-перехватчика

Диспетчер соединений

Сервер по своей природе является полномочным пользователем. Благодаря роли обработчика событий серверу известны метаданные клиентов, например connectionId и userId, поэтому он может выполнять следующие задачи:

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

Он также может предоставлять или отзывать разрешения на публикацию и присоединение для клиента PubSub:

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

Служба предоставляет REST API для сервера для управления подключениями.

Схема рабочего процесса диспетчера соединений службы Web PubSub.

Подробный протокол REST API описан здесь.

Прослушиватель событий

Примечание.

Функция прослушивателя событий доступна в предварительной версии.

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

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

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

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

Пример схемы потока потока данных прослушивателя событий

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

Служба Web PubSub предоставляет клиентские события прослушивателям событий с помощью расширения AMQP CloudEvents для Azure Web PubSub.

Итоги

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

Схема, показывающая двунаправленный рабочий процесс в службе Web PubSub.

Следующие шаги

Используйте эти ресурсы для начала создания собственного приложения:

Руководство. Публикация и подписка на сообщения в Azure Web PubSub

Руководство по созданию чат-комнаты с помощью Azure Web PubSub

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

Руководство по созданию бессерверного чата с помощью Функций Azure и Web PubSub

Руководство. Настройка прослушивателя событий

Играть с динамическими демонстрациями

Другие примеры Azure Web PubSub