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

справочник по REST API уровня данных Служба Azure SignalR

  • Статья

Помимо классического шаблона клиента или сервера, Служба Azure SignalR предоставляет набор интерфейсов REST API, которые помогут интегрировать функции реального времени в бессерверную архитектуру.

Примечание.

Служба Azure SignalR поддерживает использование REST API только для управления клиентами, подключенными через ASP.NET Core SignalR. Клиенты, подключенные через ASP.NET SignalR, используют другой протокол данных, который в настоящее время не поддерживается.

Типичная бессерверная архитектура с Функции Azure

На следующей схеме показана стандартная бессерверная архитектура, использующая Служба Azure SignalR с Функции Azure.

Diagram of a typical serverless architecture for Azure SignalR Service.

  • Функция negotiate возвращает ответ на согласование и перенаправляет всех клиентов на Служба Azure SignalR.
  • Функция broadcast вызывает REST API для Служба Azure SignalR. Служба Azure SignalR передает сообщение всем подключенным клиентам.

В бессерверной архитектуре клиенты имеют постоянные подключения к Служба Azure SignalR. Так как для обработки трафика нет сервера приложений, клиенты находятся в LISTEN режиме. В этом режиме клиенты могут получать сообщения, но не могут отправлять сообщения. Служба Azure SignalR отключает любой клиент, который отправляет сообщения, так как это недопустимая операция.

Полный пример использования Служба Azure SignalR с Функции Azure можно найти в этом репозитории GitHub.

Реализация конечной точки согласования

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

Типичный ответ на переговоры имеет следующий формат:

{
  "url": "https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
  "accessToken": "<a typical JWT token>"
}

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

Вы должны разместить API переговоров, https://<hub_url>/negotiate чтобы вы по-прежнему могли использовать клиент SignalR для подключения к URL-адресу концентратора. Дополнительные сведения о перенаправлении клиентов на Служба Azure SignalR в клиентских подключениях.

Версии REST API

В следующей таблице показаны все поддерживаемые версии REST API. Он также предоставляет файл Swagger для каждой версии API.

Версия API Состояние Порт Документация Спецификация
20220601 Latest Standard Статья Файл Swagger
1.0 Стабильный Standard Статья Файл Swagger
1.0-preview Устарело Standard Статья Файл Swagger

В следующей таблице перечислены доступные API.

API Путь
Трансляция сообщения всем клиентам, подключенным к целевому концентратору POST /api/v1/hubs/{hub}
Трансляция сообщения всем клиентам принадлежит целевому пользователю POST /api/v1/hubs/{hub}/users/{id}
Отправка сообщения в определенное подключение POST /api/v1/hubs/{hub}/connections/{connectionId}
Проверьте, существует ли подключение с заданным идентификатором подключения. GET /api/v1/hubs/{hub}/connections/{connectionId}
Закрытие подключения клиента DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Трансляция сообщения всем клиентам в целевой группе POST /api/v1/hubs/{hub}/groups/{group}
Проверьте наличие клиентских подключений в данной группе GET /api/v1/hubs/{hub}/groups/{group}
Проверьте, подключены ли клиентские подключения для данного пользователя GET /api/v1/hubs/{hub}/users/{user}
Добавление подключения к целевой группе PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Удаление подключения из целевой группы DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Проверьте, существует ли пользователь в целевой группе GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Добавление пользователя в целевую группу PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Удаление пользователя из целевой группы DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Удаление пользователя из всех групп DELETE /api/v1/hubs/{hub}/users/{user}/groups

Использование REST API

Проверка подлинности с помощью AccessKey в Служба Azure SignalR

В каждом HTTP-запросе для проверки подлинности с помощью Служба Azure SignalR требуется заголовок авторизации с веб-маркером JSON (JWT).

Алгоритм подписи и подпись

HS256, а именно HMAC-SHA256, используется в качестве алгоритма подписи.

AccessKey Используйте значение в строка подключения экземпляра Служба Azure SignalR, чтобы подписать созданный JWT.

Претензии

Следующие утверждения должны быть включены в JWT.

Тип утверждения Требуется Description
aud true Необходимо совпадать с URL-адресом HTTP-запроса, а не включать в себя параметры косой черты и запроса. Например, аудитория широковещательного запроса должна выглядеть следующим образом: https://example.service.signalr.net/api/v1/hubs/myhub
exp true Время эпохи, когда срок действия этого маркера истекает.

Проверка подлинности с помощью токена Microsoft Entra

Аналогично проверке подлинности через AccessKey, JWT требуется для проверки подлинности HTTP-запроса с помощью токена Microsoft Entra.

Разница заключается в том, что в этом сценарии идентификатор Microsoft Entra создает JWT. Дополнительные сведения см. в статье "Создание токенов Microsoft Entra".

Вы также можете использовать управление доступом на основе ролей (RBAC) для авторизации запроса с клиента или сервера на Служба Azure SignalR. Дополнительные сведения см. в разделе "Авторизация доступа с помощью идентификатора Microsoft Entra" для Служба Azure SignalR.

Для вызова REST API, связанного с пользователем, каждый из клиентов должен идентифицировать себя в Служба Azure SignalR. В противном случае Служба Azure SignalR не удается найти целевые подключения из идентификатора пользователя.

Вы можете добиться идентификации клиента, включив nameid утверждение в JWT каждого клиента при подключении к Служба Azure SignalR. Служба Azure SignalR затем использует значение nameid утверждения в качестве идентификатора пользователя для каждого подключения клиента.

Пример

В этом репозитории GitHub можно найти полное консольное приложение, чтобы продемонстрировать, как вручную создать HTTP-запрос REST API в Служба Azure SignalR.

Вы также можете использовать Microsoft.Azure.SignalR.Management для публикации сообщений в Служба Azure SignalR с помощью аналогичных интерфейсовIHubContext. Примеры можно найти в этом репозитории GitHub. Дополнительные сведения см. в статье Служба Azure SignalR SDK для управления.

Ограничения

В настоящее время запросы REST API имеют следующие ограничения:

  • Размер заголовка составляет не более 16 КБ.
  • Размер тела составляет не более 1 МБ.

Если вы хотите отправлять сообщения размером более 1 МБ, используйте пакет SDK для управления службами с persistent режимом.