Импорт WebSocket API

ОБЛАСТЬ ПРИМЕНЕНИЯ: Разработчик | Базовый | Базовая версия 2 | Стандартный | Standard v2 | Премия

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

Примечание.

В настоящее время эта функция недоступна в рабочих областях.

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

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

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

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

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

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

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

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

1. Клиентское приложение отправляет запрос на подтверждение WebSocket на шлюз Управления API, активируя операцию onHandshake.
2. Шлюз Управления API отправляет запрос на подтверждение WebSocket соответствующей серверной службе.
3. Серверная служба передает подключение к WebSocket.
4. Шлюз Управления API передает соответствующее подключение к WebSocket.
5. Как только пара подключений будет установлена, Управление API начнет передавать сообщения между клиентским приложением и серверной службой.
6. Клиентское приложение отправляет сообщение на шлюз Управления API.
7. Шлюз Управления API передает сообщения серверной службе.
8. Серверная служба отправляет сообщение на шлюз Управления API.
9. Шлюз Управления API предает сообщение клиентскому приложению.
10. Когда любая из сторон отключится, Управление API закроет соответствующее подключение.

Примечание.

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

Операция onHandshake

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

Добавление API WebSocket

Портал

1. 1. Перейдите к экземпляру Управления API на портале Azure.

2. В меню слева выберите API>+ Добавить API.

3. В разделе "Определение нового API" выберите WebSocket.

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

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

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

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

1. Перейдите к API WebSocket.

2. В API WebSocket выберите операцию onHandshake.

3. Откройте вкладку Тестирование, чтобы перейти к консоли тестирования.

4. При необходимости укажите параметры строки запроса, необходимые для подтверждения WebSocket.

   

5. Щелкните Подключить.

6. Просмотрите состояние подключения в разделе Вывод.

7. Введите значение в поле Полезные данные.

8. Нажмите Отправить.

9. Просмотрите полученные сообщения в разделе Вывод.

10. Повторите предыдущие шаги, чтобы проверить различные полезные данные.

11. После завершения тестирования щелкните Отключиться.

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

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

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

Например, на следующем снимке экрана показаны последние ответы API WebSocket с кодом 101 из таблицы ApiManagementGatewayLogs. Эти результаты указывают на успешное переключение запросов с протокола TCP на протокол 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 через политику, они будут пропущены во время выполнения.

См. также

• Ограничения импорта API
• Импорт спецификации OpenAPI
• Импорт SOAP API
• Импорт SOAP API и его преобразование в REST
• Импорт API Службы приложений
• Импорт API контейнерного приложения
• Импорт API WebSocket
• Импорт API GraphQL
• Импорт схемы GraphQL и настройка сопоставителей полей
• Импорт приложения-функции Azure
• Импорт приложения логики Azure
• Импорт службы Service Fabric
• Импорт API OpenAI Azure
• Импорт API OData
• Импорт метаданных SAP OData
• Импорт API gRPC
• Изменение API

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

Преобразование и защита опубликованного API