На прошлом уроке мы разобрались с базовой структурой спецификаций OpenAPI в сервисе API Gateway. Теперь давайте посмотрим на структуру её расширений.

Расширение x-yc-apigateway-integration:dummy возвращает фиксированное содержимое с указанным кодом ответа и необходимыми заголовками без участия стороннего сервиса.

Структура этого расширения выглядит следующим образом:

x-yc-apigateway-integration:
  type: dummy
  http_code: <HTTP-код ответа>
  http_headers:
    <Список заголовков ответа>
  content:
    <Содержимое тела ответа>

Вот пример скрипта, который возвращает ответ в формате JSON с кодом 302:

x-yc-apigateway-integration:
  type: dummy
  http_code: 302
  http_headers:
    Location: "/some/location"
  content:
    "application/json": "{ \"message\": \"You've been redirected.\" }"

Вы можете использовать широкий спектр параметров и механик спецификации OpenAPI и делать сложные конструкции для статических ответов. Например, следующий скрипт меняет ответ в зависимости от параметров запроса:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Test API
paths:
  /hello:
    get:
      summary: Say hello
      operationId: hello
      parameters:
        - name: user
          in: query
          description: User name to appear in greetings
          required: false
          schema:
            type: string
            default: 'world'
      responses:
        '200':
          description: Greeting
          content:
            'text/plain':
               schema:
                 type: "string"
      x-yc-apigateway-integration:
        type: dummy
        http_code: 200
        http_headers:
          'Content-Type': "text/plain"
        content:
          'text/plain': "Hello, {user}!\n"

Подробнее о том, как использовать расширение, рассказывается в документации.

Расширение x-yc-apigateway-integration:cloud_functions вызывает указанную облачную функцию. В качестве входных данных функция получает информацию об HTTP-запросе и значения параметров, указанных в спецификации. На выходе клиенту возвращается результат выполнения функции.

Информация о запросе передается в том же формате, что и в текущей версии HTTP-интеграции при вызове функции с указанием параметра строки запроса integration=raw, который по большей части совместим с форматом AWS API Gateway. Значения параметров, указанных в спецификации, передаются в поле params параметра data.

Вот общая структура расширения:

x-yc-apigateway-integration:
  type: cloud-functions
  function_id: <идентификатор функции>
  tag: <Тег функции>
  service_account: <идентификатор сервисного аккаунта>

Давайте посмотрим на параметры:

Вот пример скрипта для этого расширения:

x-yc-apigateway-integration:
  type: cloud-functions
  function_id: b095c95icnvbuf4v755l
  tag: stable
  service_account: ajehfe41hhliq4n93q1g

Подробнее о том, как использовать расширение, читайте в документации.

Расширение x-yc-apigateway-integration:http перенаправляет запрос в указанный URL. Вот его структура:

x-yc-apigateway-integration:
  type: http
  url: <URL для вызова>
  method: <Метод вызова>
  headers:
     <Массив заголовков вызова>
  timeouts:
     <Таймаут вызова>

Обязательными параметрами здесь являются url и headers. Если method не указан, то система будет использовать метод запроса к Yandex API Gateway. При отсутствии timeouts будут использованы значения по умолчанию.

Пример скрипта для данного расширения:

x-yc-apigateway-integration:
  type: http
  url: https://example.com/backend1
  method: POST
  headers:
    Authorization: Basic ZjTqBB3f$IF9gdYAGlMrs2fuINjHsz
  timeouts:
    connect: 0.5
    read: 5

Подробнее о том, как использовать расширение, читайте в документации.

Расширение x-yc-apigateway-integration:object_storage передает управление обработки запроса в Object Storage с целью раздачи статических файлов. Оно позволяет управлять ключом для доступа к объекту и реализует возможность раздавать статические данные напрямую из Object Storage, используя перенаправление на подписанный URL.

Структура расширения такова:

x-yc-apigateway-integration:
        type: object-storage
        bucket: <Имя бакета>
        object: <Имя объекта>
        presigned_redirect: <Генерация пре-подписанного url>
        service_account: <идентификатор сервисного аккаунта, от имени которого идет обращение к Yandex Object Storage>

Параметр service_account является единственным необязательным. Он работает так же, как и в функциях. Если он отсутствует, то будет использовано значение для всего скрипта в параметре верхнего уровня. Если параметр верхнего уровня не указан, то обращение будет выполнено без авторизации. При этом бакет должен быть публичным.

Если значение параметра presigned_redirect задано как true, то для запроса будет сгенерирован специальный тип URL, который содержит все данные для авторизации. Любой клиент сможет скачать этот файл вне зависимости от наличия у него данных для авторизации.

Вот пример скрипта для этого расширения:

/static/{file}:
    get:
      summary: Serve static file from Yandex Cloud Object Storage
      parameters:
        - name: file
          in: path
          required: true
          schema:
            type: string
      x-yc-apigateway-integration:
        type: object-storage
        bucket: my-example-bucket
        object: 'my-object'
        presigned_redirect: true
        service_account: ajehfe41hhliq4n93q1g

Подробнее о том, как использовать расширение, читайте в документации.

Предположим, что все JS и CSS файлы вашего сайта должны быть доступны по URL с одинаковым префиксом /static/js/ и /static/CSS/соответственно. Чтобы не перечислять в спецификации каждый файл по отдельности и не писать для него дублирующиеся интеграции, вы может использовать так называемые жадные параметры.

Чтобы описать все файлы, доступные по URL с префиксом /static на любом уровне вложенности, добавьте знак плюс после имени параметра. Вот пример спецификации:

/static/{file+}:
    get:
      summary: Serve static file from Yandex Cloud Object Storage
      parameters:
        - name: file
          in: path
          required: true
          schema:
            type: string
      x-yc-apigateway-integration:
        type: object_storage
        bucket: my-example-bucket
        object: '{file}'
        error_object: error.html

Если вам необходимо все ваши вызовы по одному URL для всех HTTP-методов  направить в соответствии с одной и той же интеграцией, например в одну функцию, вы можете использовать расширение x-yc-apigateway-any-method. Оно позволяет избежать дублирования одинаковых интеграций в спецификации для каждого HTTP-метода, делает спецификацию короче и понятнее.

Вот пример спецификации, где применяется это расширение:

/example/{ID}:
    x-yc-apigateway-any-method:
      summary: Operating with examples
      operationId: example
      tags:
        - example
      parameters:
        - name: ID
          in: path
          description: Return ID
          required: true
          schema:
            type: string
      x-yc-apigateway-integration:
        type: cloud_functions
        function_id: b095c95icnvbuf4v755l
        tag: "$latest"
        service_account_id: ajehfe41hhliq4n93q1g

Всё взаимодействие с сервисами в Yandex Cloud должно происходить от имени какого-либо аккаунта. В случае с Yandex API Gateway сервисный аккаунт используется для работы с функциями и Yandex Object Storage. Его можно указать как для конкретного расширения, так и для всех расширений разом. Для этого используется параметр верхнего уровня:

x-yc-apigateway:
  service_account: <идентификатор сервисного аккаунта>

Он используется следующим образом:

openapi: 3.0.0
info:
  title: Test API
  version: 1.0.0
x-yc-apigateway:
  service_account: <идентификатор сервисного аккаунта>

Теперь вы знакомы с возможными вариантами настройки сервиса. На следующем занятии закрепим пройденный материал на практике и создадим HTTP API с помощью Cloud Functions и 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: <Тип расширения>

Где:

При этом расширение 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.

Представим, что вы разрабатываете интернет-магазин с микросервисной архитектурой. Клиент открывает сайт или приложение вашего магазина и переходит на страницу товара — делает один запрос. Чтобы сформировать ту же карточку товара с набором корректных данных, системе нужно сделать несколько запросов, например:

Каждый из этих запросов выполняет отдельный микросервис со своим API. Если же вы хотите после оформления заказа и получения оплаты передавать клиенту трекинг почтового отправления, то вам придётся передать всем логистическим компаниям — партнёрам единый API для работы с вашей информационной системой.

Такое решение можно построить с нуля на базе веб-сервера NGINX или с помощью специализированных решений, которые, как правило, ориентированы на определенные стеки технологий и среды выполнения. В дальнейшем вам придется самостоятельно администрировать всю инфраструктуру: настраивать маршрутизатор и балансировку запросов по виртуальным машинам, обеспечивать горизонтальное масштабирование при росте посещаемости и т. д.

Вместо этого вы можете воспользоваться сервисом Yandex API Gateway, который работает по модели PaaS. Сервис предоставит:

Давайте разберёмся с базовыми концепциями сервиса.

В основе этого сервиса лежит классический паттерн программирования: внутреннее представление отделено от способа взаимодействовать с ним через прокси. Мы не афишируем нашу реализацию и отдаём наружу некий контракт.

Yandex API Gateway — важная часть serverless-экосистемы в Yandex Cloud. Он позволяет интегрировать компоненты микросервисного приложения и разрозненные API.

По своей сути Yandex API Gateway является управляемым RESTful API. Он находится между внешним пользователем и сервисами, которые обрабатывают запросы этого пользователя. Его основное преимущество — возможность свести в единую точку взаимодействие пользователей с ресурсами, которые расположены как в Yandex Cloud, так и на других серверах. Допустим, у вас есть три сущности:

API Gateway позволит организовать взаимодействие со всеми тремя ресурсами через обращение к одному домену с единым API. Без него вам бы пришлось самостоятельно разворачивать шлюз или обратный прокси-сервер и администрировать его.

Поскольку API Gateway работает по модели PaaS, он гарантирует доступность вашего API в соответствии с SLA. А ещё HTTP/HTTPS-запросы ваших пользователей будут выполнены вне зависимости от их количества.

Сервис принимает запросы по HTTPS через служебный поддомен apigw.yandexcloud.net или через подключение к вашему домену через Certificate Manager, разбирает эти запросы и определяет их путь и параметры. Кроме того, он использует механизм сервисных аккаунтов для подключения к другим сервисам Yandex Cloud.

Созданный API-шлюз может обрабатывать запросы пятью разными способами:

Общая схема работы сервиса выглядит следующим образом:

Запрос пользователя попадает в API-шлюз, который в соответствии с правилами в спецификации перенаправляет его по другим путям, таким как выполнение облачной функции, получение файла из Object Storage и т. д.

Например, на запрос https://<домен>/GetFileList может быть дан статический ответ со списком файлов, а на запрос https://<домен>/static/<file> — возвращён файл из Yandex Object Storage.

Модель тарификации для этого сервиса — 120 рублей за 1 млн запросов в месяц.* Работает free tier: первые 100 000 запросов в месяц не тарифицируются.

Давайте посчитаем стоимость использования API-шлюза с количеством запросов из примера выше:

$120\times ((2000000–100000)/1000000)=228$ ₽ в месяц

Для сравнения создадим виртуальную машину (ВМ) с самыми скромными возможностями, чтобы запустить на ней NGINX для терминирования TLS и проксирования запросов. Пусть это будет Ubuntu 20.04 c HDD объёмом 13 ГБ, Intel Ice Lake, 2 vCPU с гарантированной долей 20% и RAM 1 ГБ. Ежемесячная стоимость ВМ с такой конфигурацией составит 1 045,96 ₽.

Обратите внимание: функционально сравнение этих двух решений не будет корректным. Отказоустойчивость API-шлюза, работающего на базе NGINX в ВМ, будет предельно низкой, и у вас уйдёт заметно больше времени на настройку маршрутов.

Более подробную информацию вы найдёте в документации.

На следующем уроке мы разберём основы конфигурации Yandex API Gateway.

 

На этом практическом занятии вы создадите функцию для проверки доступности сайта ya.ru, которая будет измерять время ответа. Результаты работы функции будут передаваться в базу данных сервиса Yandex Managed Service for PostgreSQL с использованием подключения к управляемой БД из функции. Также вы запустите триггер-таймер, который будет регулярно производить опрос сайта ya.ru.

В предыдущих практических работах вы создали сервисный аккаунт с именем service-account-for-cf, назначили ему роли editor и  storage.editor и создали ключ доступа. Чтобы подключаться к управляемым БД из функции, нужно добавить сервисному аккаунту роль serverless.mdbProxies.user.

Для этого выполните следующую команду:

yc resource-manager folder add-access-binding $FOLDER_ID \
  --role serverless.mdbProxies.user \
  --subject serviceAccount:$SERVICE_ACCOUNT_ID

Конечно, кластер PostgreSQL можно создать с помощью консоли управления, но в этой практической работе мы используем CLI. Прежде всего, давайте определим подсеть, в которой будет расположен кластер. Разместим кластер в зоне ru-central1-c и с помощью следующей команды узнаем идентификатор(ID) соответствующей подсети:

yc vpc subnet list

Создадим кластер версии PostgreSQL 15 с именем my-pg-database. Установим тип хоста burstable c3-c2-m4 — это самый дешёвый и простой вариант хоста. Из-за невысокой производительности он подходит только для тестовых целей. Используем для хоста жёсткий диск (HDD) размером 10 ГБ.

Сразу создадим пользователя с именем user1 и паролем user1user1, а также базу данных db1. Для удобства администрирования откроем доступ из консоли управления. Используйте опцию websql-access — это позволит выполнять SQL-запросы прямо в консоли управления. Чтобы открыть возможность подключения к PostgreSQL из функции, необходимо подключить опцию serverless-access.

Следующая команда за несколько минут создаст кластер PostgreSQL (не забудьте подставить идентификатор вашей подсети):

yc managed-postgresql cluster create \
  --name my-pg-database \
  --description 'For Serverless' \
  --postgresql-version 15 \
  --environment production \
  --network-name default \
  --resource-preset c3-c2-m4 \
  --host zone-id=ru-central1-c,subnet-id=<идентификатор_подсети> \
  --disk-type network-hdd \
  --disk-size 10 \
  --user name=user1,password=user1user1 \
  --database name=db1,owner=user1 \
  --websql-access \
  --serverless-access

После успешного создания кластера проверьте результат:

yc managed-postgresql cluster list
yc managed-postgresql cluster get <имя или идентификатор кластера>

При создании кластера мы использовали опцию websql-access, что открывает нам возможности по исполнению SQL-команд в консоли управления. Воспользуемся этим и сделаем таблицу в созданной нами базе данных. В эту таблицу мы будем складывать результаты выполнения функции. В консоли управления перейдите в каталог, в котором создан кластер PostgreSQL. Откройте сервис Managed Service for PostgreSQL и перейдите в кластер my-pg-database.

В боковом меню перейдите на вкладку SQL. Для базы данных db1введите имя user1 и пароль user1user1, нажмите кнопку Подключиться.

В открывшемся окне введите SQL-запрос и исполните его:

CREATE TABLE measurements (
    result integer,
    time float
);

Успешное выполнение команды создаст таблицу, куда мы будем складывать результаты.

В консоли управления перейдите в каталог, в котором хотите создать подключение. Откройте сервис Cloud Functions. В боковом меню перейдите на вкладку Подключения к БД. Нажмите кнопку Создать подключение.

Выберите созданное подключение. На вкладке Обзор скопируйте параметры Идентификатор и Точка входа. Они будут использованы в функции на следующем шаге.

Перед созданием функции определите переменные для инициации подключения: CONNECTION_ID — идентификатор подключения, DB_USER — имя пользователя БД, DB_HOST — точка входа. Используйте следующие команды:

echo "export CONNECTION_ID=<CONNECTION_ID>" >> ~/.bashrc && . ~/.bashrc
echo "export DB_USER=<DB_USER>" >> ~/.bashrc && . ~/.bashrc
echo "export DB_HOST=<DB_HOST>" >> ~/.bashrc && . ~/.bashrc

Они будут использованы в функции function-for-postgresql.py. Код функции:

import datetime
import logging
import requests
import os

#Эти библиотеки нужны для работы с PostgreSQL
import psycopg2
import psycopg2.errors

CONNECTION_ID = os.getenv("CONNECTION_ID")
DB_USER = os.getenv("DB_USER")
DB_HOST = os.getenv("DB_HOST")

# Настраиваем функцию для записи информации в журнал функции
# Получаем стандартный логер языка Python
logger = logging.getLogger()
logger.setLevel(logging.INFO)
# Вычитываем переменную VERBOSE_LOG, которую мы указываем в переменных окружения 
verboseLogging = eval(os.environ['VERBOSE_LOG'])  ## Convert to bool

#Функция log, которая запишет текст в журнал выполнения функции, если в переменной окружения VERBOSE_LOG будет значение True
def log(logString):
    if verboseLogging:
        logger.info(logString)

#Запись в базу данных
def save(result, time, context):
    connection = psycopg2.connect(
        database=CONNECTION_ID, # Идентификатор подключения
        user=DB_USER, # Пользователь БД
        password=context.token["access_token"],
        host=DB_HOST, # Точка входа
        port=6432,
        sslmode="require")

    cursor = connection.cursor()    
    postgres_insert_query = """INSERT INTO measurements (result, time) VALUES (%s,%s)"""
    record_to_insert = (result, time)
    cursor.execute(postgres_insert_query, record_to_insert)
    connection.commit()

# Это обработчик. Он будет вызван первым при запуске функции
def entry(event, context):

    #Выводим в журнал значения входных параметров event и context
    log(event)
    log(context)

    # Тут мы запоминаем текущее время, отправляем запрос к ya.ru и вычисляем время выполнения запроса
    try:
        now = datetime.datetime.now()
        #здесь указано два таймаута: 1c для установки связи с сервисом и 3 секунды на получение ответа
        response = requests.get('https://ya.ru', timeout=(1.0000, 3.0000))
        timediff = datetime.datetime.now() - now
        #сохраняем результат запроса
        result = response.status_code
    #если в процессе запроса сработали таймауты, то в результат записываем соответствующие коды
    except requests.exceptions.ReadTimeout:
        result = 601
    except requests.exceptions.ConnectTimeout:
        result = 602
    except requests.exceptions.Timeout:
        result = 603
    log(f'Result: {result} Time: {timediff.total_seconds()}')    
    save(result, timediff.total_seconds(), context)

    #возвращаем результат запроса
    return {
        'statusCode': result,
        'headers': {
            'Content-Type': 'text/plain'
        },
        'isBase64Encoded': False
    }

Перейдем в директорию с кодом функции и создадим нашу функцию function-for-postgresql. При этом сразу зададим все необходимые переменные и сервисный аккаунт:

yc serverless function create \
  --name  function-for-postgresql \
  --description "function for postgresql"

yc serverless function version create \
  --function-name=function-for-postgresql \
  --memory=256m \
  --execution-timeout=5s \
  --runtime=python37 \
  --entrypoint=function-for-postgresql.entry \
  --service-account-id $SERVICE_ACCOUNT_ID \
  --environment VERBOSE_LOG=True \
  --environment CONNECTION_ID=$CONNECTION_ID \
  --environment DB_USER=$DB_USER \
  --environment DB_HOST=$DB_HOST \
  --source-path function-for-postgresql.py

Проверим работоспособность функции:

yc serverless function version list --function-name function-for-postgresql
yc serverless function invoke --name function-for-postgresql

Успешный вызов функции приведёт к измерению времени ответа сайта и формированию записи в базе данных.

Проверять доступность сайта лучше в автоматическом режиме через равные промежутки времени. Для этой задачи создайте триггер-таймер. Он будет использовать cron-выражения:

yc serverless trigger create timer \
  --name trigger-for-postgresql \
  --invoke-function-name function-for-postgresql \
  --invoke-function-service-account-id $SERVICE_ACCOUNT_ID \
  --cron-expression '* * * * ? *'

Cron-выражение * * * * ? * означает вызов функции function-for-postgresql один раз в минуту. Успешное выполнение функции раз в минуту будет создавать запись в базе данных, в чём вы можете убедиться, просмотрев записи в таблице.

Убедились? Поздравляем: вы успешно создали функцию, которая через заданный промежуток времени выполняется по триггеру, чтобы проверить доступность ya.ru и записать результат проверки в базу данных.

После завершения практической работы не забудьте удалить созданный триггер trigger-for-postgresql, иначе он будет продолжать работать:

yc serverless trigger delete trigger-for-postgresql

Не удаляйте созданный кластер PostgreSQL, он понадобится для следующей практической работы.