Взаимосвязь ресурсов в API Gateway
API-шлюз — это интерфейс взаимодействия с сервисами внутри Yandex Cloud или в интернете.
API-шлюз задается декларативно при помощи спецификации. Спецификация — это файл в формате JSON или YAML с описанием API-шлюза по стандарту OpenAPI 3.0. В сервисе API Gateway спецификация дополнена расширениями, которые вы можете использовать для интеграции с другими облачными платформами.
Доступные расширения:
- Статический ответ
- Обращение по HTTP
- Интеграция с Cloud Functions
- Интеграция с Serverless Containers
- Интеграция с Smart Web Security
- Интеграция с Object Storage
- Интеграция с DataSphere
- Интеграция с Data Streams
- Интеграция с Message Queue
- Интеграция с YDB
- Жадные параметры
- Обобщенный HTTP-метод
- Авторизация с помощью функции Cloud Functions
- Авторизация с помощью JWT
- Поддержка протокола WebSocket
- Валидация данных
- Поддержка CORS
- Параметризация спецификации
- Канареечный релиз
- Ограничение скорости обработки запросов
- Замена кода ответа
- Преобразование тела ответа и запроса
Алгоритм поиска обработчика в OpenAPI-спецификации
При поиске обработчика API Gateway:
-
Выбирает в OpenAPI-спецификации маршруты, которые соответствуют обрабатываемому запросу.
-
Сортирует выбранные маршруты по приоритетам:
- Наивысший приоритет имеют фиксированные маршруты — маршруты, которые не содержат параметры пути и жадные параметры. Например:
/simple/path. - Средний приоритет имеют маршруты, которые содержат параметры пути, но не содержат жадные параметры. Например:
/{param}/path. - Наименьший приоритет имеют маршруты с жадными параметрами. Например:
/{greedy_param+}.
Если у двух маршрутов одинаковый приоритет:
- Два маршрута со средним приоритетом последовательно сравниваются по сегментам URL. Сегменты бывают двух видов — фиксированные (например,
simple) и параметризованные (например,{param}). Фиксированный сегмент является более приоритетным, чем параметризованный. Если у всех сегментов маршрутов одинаковый приоритет, выбирается тот маршрут, длина которого больше. - Между двумя маршрутами с наименьшим приоритетом выбирается тот, длина которого больше.
- Наивысший приоритет имеют фиксированные маршруты — маршруты, которые не содержат параметры пути и жадные параметры. Например:
Примеры сравнения маршрутов
/a/{param1}/b и /a/{param2}/{param3}
Оба маршрута имеют средний приоритет, потому что содержат параметры пути, но не содержат жадные параметры, поэтому последовательно сравниваются по сегментам URL.
- Сегменты
aиa— оба фиксированные и имеют одинаковый приоритет. - Сегменты
{param1}и{param2}— оба параметризованные и имеют одинаковый приоритет. - Сегмент
b— фиксированный, а{param3}— параметризованный, поэтому выбирается сегментb.
Выбранный обработчик — /a/{param1}/b.
/a/b/{param1} и /a/{param2}/d
Оба маршрута содержат параметры пути, но не содержат жадные параметры, поэтому имеют средний приоритет и последовательно сравниваются по сегментам URL.
- Сегменты
aиa— оба фиксированные и имеют одинаковый приоритет. - Сегмент
b— фиксированный, а{param2}— параметризованный, поэтому выбирается сегментb.
Выбранный обработчик — /a/b/{param1}.
/a/b/{param+} и /a/{param2}/d
Маршрут /a/b/{param+} содержит жадный параметр, поэтому имеет наименьший приоритет. Маршрут /a/{param2}/d содержит параметр пути, но не жадный параметр, поэтому имеет средний приоритет. Между маршрутом со средним и наименьшим приоритетом выбирается маршрут со средним приоритетом.
Выбранный обработчик — /a/{param2}/d.
/a/{param} и /a/{prm}
Оба маршрута содержат параметры пути, но не содержат жадные параметры, поэтому имеют средний приоритет и последовательно сравниваются по сегментам URL.
- Сегменты
aиa— оба фиксированные и имеют одинаковый приоритет. - Сегменты
{param}и{prm}— оба параметризованные и имеют одинаковый приоритет.
Так как нельзя выбрать между всеми сегментами, сравниваются длины маршрутов. Маршрут /a/{param} длиннее маршрута /a/{prm}.
Выбранный обработчик — /a/{param}.
/a/{param1}/{param+} и /a/{param2}/{prm+}
Оба маршрута содержат жадные параметры, поэтому имеют наименьший приоритет и сравниваются по длине. Маршрут /a/{param1}/{param+} длиннее маршрута /a/{param2}/{prm+}.
Выбранный обработчик — /a/{param1}/{param+}.
Использование доменов
Сервис API Gateway позволяет подключить собственный домен для обращения к API-шлюзу. Для организации TLS-соединения можно использовать сертификаты, добавленные в сервисе Certificate Manager.
Подробнее о подключении собственного домена к API-шлюзу см. раздел Подключить домен.
Подробнее о добавлении сертификатов см. раздел Добавить сертификат от Let's Encrypt®.
Авторизация
API Gateway позволяет реализовать стандартные механизмы аутентификации и авторизации, которые предусмотрены спецификацией OpenAPI 3.0. На данный момент доступна авторизация с помощью функции и авторизация с помощью JWT.
WebSocket
Примечание
Эта функциональность находится на стадии Preview.
Для организации асинхронного двунаправленного взаимодействия между клиентами и API-шлюзом сервис API Gateway поддерживает протокол WebSocket. Клиенты могут отправлять сообщения в API-шлюз, который в свою очередь может независимо отправлять сообщения клиентским приложениям. Такая возможность позволяет клиентам получать данные без необходимости делать HTTP-запрос. Веб-сокеты часто используются в приложениях, требующих обновления данных в режиме реального времени, таких как мессенджеры и онлайн-чаты, многопользовательские игры, платформы для совместной работы, а также приложения финансового рынка и спортивные онлайн-площадки.
Чтобы подключиться к API-шлюзу по протоколу WebSocket, можно использовать служебный домен, выделяемый при создании API-шлюза, или любой другой, добавленный к API-шлюзу.
Доступны интеграции на следующие события:
- открытие соединения;
- отправка сообщений через веб-сокет;
- закрытие соединения.
Для настройки интеграций предусмотрены специальные расширения OpenAPI-спецификации.
Управлять веб-сокетами можно с помощью API, который позволяет получить информацию о соединении, отправить данные на клиентскую сторону и закрыть соединение.
Ограничения, связанные с поддержкой протокола WebSocket, описаны в разделе Квоты и лимиты.
Пример serverless-приложения с использованием протокола WebSocket.