На прошлом уроке мы разобрались с базовой структурой спецификаций 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.