Как настроить Yandex API Gateway
Кратко:
- Настройка Yandex API Gateway требует написания спецификации и создания экземпляра API-шлюза.
- Спецификация должна соответствовать требованиям OpenAPI и учитывать специфику сервиса.
- Работа с сервисом возможна через консоль управления или Yandex Cloud REST API.
- Базовая спецификация включает информацию о названии и версии API, а также пути и методе вызова.
- Расширения x-yc-apigateway-integration позволяют интегрировать API-шлюз с другими сервисами.
- В спецификации можно указать несколько путей и методов для каждого пути.
- Сервис автоматически добавляет параметр servers для формирования адреса служебного домена.
- Ведение журнала и мониторинг позволяют проверять правильность настройки и работу сервиса.
Как настроить Yandex API Gateway
На прошлом уроке вы узнали, что такое Yandex API Gateway и как он работает, а сейчас научитесь настраивать этот сервис.
API Gateway использует спецификацию OpenAPI 3.0 для конфигурации вызовов и ответов. Чтобы настроить сервис, нужно написать спецификацию и создать экземпляр API-шлюза. Эта спецификация должна соответствовать требованиям OpenAPI и описанию расширений, а также учитывать специфику сервиса. Все детали взаимодействия с сервисом можно уточнить в документации, а мы сосредоточимся только на самых важных аспектах.
С сервисом можно работать через консоль управления или с помощью Yandex Cloud REST API. Первый способ проще, но Yandex Cloud REST API имеет чуть больше функций и позволяет настраивать сервис из стороннего программного обеспечения. Мы будем использовать консоль управления.
Чтобы создать новый API-шлюз, перейдите на главную страницу каталога, справа вверху нажмите кнопку Создать ресурс и в раскрывшемся списке выберите API-шлюз.
На открывшейся странице вы можете ввести имя и описание шлюза, а затем вставить в поле Спецификация текст спецификации, который указывает сервису, что нужно сделать в том или ином запросе.
Детально изучить спецификацию OpenAPI 3.0 вы можете в репозитории проекта на GitHub. Здесь же мы рассмотрим минимально необходимый набор параметров и тегов для работы с API Gateway на примере кода спецификации, который формируется для нового API-шлюза по умолчанию.
Базовая спецификация выглядит следующим образом:
openapi: 3.0.0
info:
title: <Название API>
version: <Версия API>
paths:
<Путь>:
<Метод>:
x-yc-apigateway-integration:
type: <Тип расширения>Где:
Путь— путь строки вызова после домена.Метод— метод вызова (например GET).Тип расширения— один из четырех типов расширений, который указывает на действия при вызове по данному пути:dummy— статический ответ.cloud-functions— вызов функции сервиса Yandex Cloud Functions.http— отправка HTTP-запроса.object-storage— обращение к сервису Yandex Object Storage.
При этом расширение
x-yc-apigateway-integration является точкой входа для интеграции API-шлюза с другими сервисами.Статический ответ может выглядеть так:
openapi: 3.0.0
info:
title: Test API
version: 1.0.0
paths:
/hello:
get:
x-yc-apigateway-integration:
type: dummy
http_code: 200
http_headers:
Content-Type: text/plain
content:
text/plain: |
Hello, World!В примере выше при вызове метода
GET для служебного домена API-шлюз сначала подключает общее расширение x-yc-apigateway-integration, а затем расширение dummy, которое в ответ на обращение выдает статический ответ с заранее определённой текстовой строкой Hello, World!.У расширения
x-yc-apigateway-integration есть дополнительные параметры (http_code, http_headers и т. д.). Их наличие зависит от типа расширения.В примере выше всего один путь (
hello), но вы можете создавать сколько угодно путей. Шаблон спецификации с двумя путями будет выглядеть так:
openapi: 3.0.0
info:
title: <Название API>
version: <Версия API>
paths:
<Путь 1>:
<Метод>:
x-yc-apigateway-integration:
type: <Тип расширения>
<Путь 2>:
<Метод>:
x-yc-apigateway-integration:
type: <Тип расширения>Адрес служебного домена в примере выше формируется после того, как вы вставили текст спецификации в одноимённое поле и сохранили изменения. При этом сервис автоматически добавляет в спецификацию параметр
servers по следующему шаблону:
servers:
- url: https://<идентификатор вашего APIGateway>.apigw.yandexcloud.net
Значением URI будет домен, который нужно использовать при обращении к вашему API.
Например, если вы используете простой тестовый пример спецификации, добавляемый по умолчанию, то для проверки ответа можете использовать HTTP-клиент cURL или просто открыть этот адрес в браузере.
В спецификации вы также можете указать и свой домен, но на него нужно заранее подтвердить права в Certificate Manager. Эта функция находится на стадии Preview, доступ к ней необходимо запросить в службе техподдержки. Подробно об использовании собственных доменов с API-шлюзами можно прочитать в документации.
Журналы и мониторинг
Чтобы вы могли проверять правильность настройки и лучше понять работу сервиса, разработчики добавили две функции: ведение журнала и мониторинг.
На странице Логи вы можете увидеть информацию о запросах к путям, которые вы указали в спецификации.
На странице Мониторинг размещён график с количеством обращений к сервису и информация об ошибках.
На следующем занятии вы познакомитесь с расширениями OpenAPI, которые позволяют работать с другими сервисами Yandex Cloud.