Импортировать интерфейс WebSocket API

2025-04-07

С помощью решения WebSocket API в Управлении API издатели API могут быстро добавить WebSocket API в Управление API, используя портал Azure, Azure CLI, Azure PowerShell и другие средства Azure.

API WebSocket можно защитить, применяя политики управления доступом управления API на начальном этапе рукопожатия. Также вы можете тестировать API WebSocket с помощью консолей тестирования API как на портале Azure, так и на портале разработчика. На основе существующих возможностей наблюдения Управление API предоставляет метрики и журналы для мониторинга и устранения неполадок с API WebSocket.

В этой статье описано следующее:

Поймите транзитный поток WebSocket.
Добавьте WebSocket API в экземпляр службы управления API.
Тестирование API WebSocket.
Просмотр метрик и журналов для API WebSocket.
Узнайте ограничения API WebSocket.

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

Существующий экземпляр управления API. Создайте его, если у вас его нет.
WebSocket API
Azure CLI (Интерфейс командной строки для Azure)

Транзитный сокет WebSocket

Управление API поддерживает транзитный сокет WebSocket.

Наглядная иллюстрация транзитного потока WebSocket

Во время сквозной передачи WebSocket клиентское приложение устанавливает подключение WebSocket к шлюзу Управления API, который затем устанавливает соединение с соответствующими службами бэкэнда. Управление API выступает как прокси-сервер для сообщений между клиентом и сервером WebSocket.

Клиентское приложение отправляет шлюзу запрос на установление соединения WebSocket, вызывая операцию onHandshake.
Шлюз Управления API применяет настроенные политики и отправляет запросы подтверждения WebSocket к соответствующему серверному сервису.
Серверная служба обновляет соединение до WebSocket.
Шлюз обновляет соответствующее подключение к WebSocket.
После установки пары подключений API Management обеспечивает двустороннюю передачу сообщений между клиентским приложением и серверной частью системы.
Клиентское приложение отправляет сообщение шлюзу.
Шлюз перенаправляет сообщение в серверную службу.
Серверная служба отправляет сообщение шлюзу.
Шлюз перенаправит сообщение клиентскому приложению.
При отключении обеих сторон Управление API завершает соответствующее подключение.

Примечание.

Для подключений на стороне клиента и сервера используется сопоставление типа "один-к-одному".

Операция «onHandshake»

Согласно протоколу WebSocket, когда клиентское приложение пытается установить подключение WebSocket с серверной службой, оно сначала отправляет запрос рукопожатия для открытия. Каждый API WebSocket в Управлении API поддерживает операцию onHandshake. onHandshake — это неизменяемая, неудаляемая, автоматически созданная системная операция. Операция onHandshake позволяет издателям API перехватывать упомянутые запросы на подтверждение и применять к ним политики Управления API.

Пример экрана onHandshake

Добавьте API WebSocket

Портал

1. На портале Azure перейдите в ваш экземпляр Управления API.
В меню слева выберите API>+ Добавить API.
В разделе "Определение нового API" выберите WebSocket.

В открывшемся диалоговом окне выберите Полный и заполните обязательные поля формы.

Поле	Описание:
Показать имя	Имя, под которым отображается ваш API WebSocket.
Имя.	Имя API WebSocket в необработанном виде. Оно заполняется автоматически при вводе отображаемого имени.
WebSocket адрес	Базовый URL с именем вашего WebSocket. Например: ws://example.com/имя_вашего_сокета
Схема URL-адреса	Примите значение по умолчанию
Суффикс URL-адреса API	Добавьте суффикс URL-адреса для идентификации этого API в данном экземпляре Управления API. Он должен быть уникальным в данной системе управления API.
Продукты	Сопоставьте API WebSocket с определенным продуктом, чтобы опубликовать его.
Шлюзы	Сопоставьте API WebSocket с существующими шлюзами.

Нажмите кнопку Создать.

Тестирование API WebSocket

Перейдите к API WebSocket.
В API WebSocket выберите операцию onHandshake.
Откройте вкладку Тестирование, чтобы перейти к консоли тестирования.
При необходимости укажите параметры строки запроса, необходимые для рукопожатия WebSocket.
Щелкните Подключить.
Просмотрите состояние подключения в разделе Вывод.
Введите значение в Payload.
Нажмите Отправить.
Просмотрите полученные сообщения в разделе Вывод.
Повторите предыдущие шаги, чтобы проверить различные нагрузки.
После завершения тестирования щелкните Отключиться.

Просмотр метрик и журналов

Используйте стандартные функции Управления API и Azure Monitor для мониторинга интерфейсов API WebSocket.

Просмотр метрик API в Azure Monitor
При необходимости включите параметры диагностики для сбора и просмотра журналов шлюза управления API, включая операции API WebSocket или журналы подключений WebSocket.

Например, на следующем снимке экрана показаны последние ответы API WebSocket с кодом 101 из таблицы ApiManagementGatewayLogs. Эти результаты указывают на успешное переключение запросов с протокола TCP на протокол WebSocket.

Журналы запросов API WebSocket

Ограничения

Ниже приведены текущие ограничения в поддержке WebSocket в управлении API.

API WebSocket пока не поддерживаются на уровне потребления.
API WebSocket поддерживают следующие допустимые типы буферов для сообщений: Close, BinaryFragment, BinaryMessage, UTF8Fragment и UTF8Message.
В настоящее время политика установки заголовков не поддерживает изменение некоторых известных заголовков, включая заголовки Host, в запросах onHandshake.
Во время выполнения рукопожатия TLS с серверной частью WebSocket, служба управления API проверяет, что сертификат сервера является доверенным и его субъектное имя соответствует имени хоста. В интерфейсах API HTTP служба Управление API проверяет, является ли сертификат доверенным, но не проверяет, что имя узла и имя субъекта совпадают.

Для ограничения подключений WebSocket см. ограничения управления API.

Неподдерживаемые политики

Следующие политики не поддерживаются и не могут применяться к операции onHandshake:

Макет ответа
Получение из кэша
Сохранение в кэше
Разрешение кросс-доменных вызовов
CORS (Совместное использование ресурсов разных источников)
JSONP
Установка метода запроса
Установить содержание
Преобразование XML в JSON
Преобразование JSON в XML
Преобразование XML с помощью XSLT
Проверка содержимого
Проверка параметров
Проверка заголовков
Проверка кода состояния

Примечание.

Если вы применили политики на более высоких уровнях (например, глобальном или уровне продукта) и они наследуются API WebSocket через эту политику, то при выполнении они обходятся.