Обзор Trino OpenAPI connector

Константин Алпашкин

Trino OpenAPI-коннектор позволяет взаимодействовать с REST API, отвечающим стандартам OpenAPI. OpenAPI — это стандарт описания функционала REST API, с помощью которого указываются доступные эндпойнты, поддерживаемые HTTP-методы, типы ответов, параметры запросов и так далее. Коннектор анализирует OpenAPI-cхему (JSON/YAML) и представляет REST-эндпойнты сервера в виде отдельных таблиц. Затем коннектор преобразует запросы SQL в HTTP-запросы, обрабатывает ответы и возвращает результаты пользователю Trino.

ПРИМЕЧАНИЕ
Настоятельно рекомендуется использовать коннектор только для чтения. Операции вставки и обновления реализованы в экспериментальном режиме.

Trino OpenAPI-коннектор поставляется с ADH и готов к использованию "из коробки". Чтобы приступить к работе с коннектором, смотрите статью Пример использования OpenAPI connector. Подробности настройки коннектора описаны в статье Настройка OpenAPI connector.

Анализ схемы OpenAPI

Анализируя схему OpenAPI, коннектор создает SQL-сущности (таблицы, столбцы, запросы) по следующим правилам:

  • REST-эндпойнты представляются в виде отдельных таблиц. Например, эндпойнт [BaseURL]/transactions представлен для Trino-клиента в виде таблицы transactions. Регистр fooBar преобразуется в foo_bar, а специальные символы, такие как /, преобразуются в _.

  • Операции SQL преобразуются в HTTP-запросы следующим образом:

    • SELECT ⇒ GET или POST (если GET недоступен);

    • INSERT ⇒ POST/PUT;

    • UPDATE ⇒ PATCH/POST;

    • DELETE ⇒ DELETE.

  • Параметры запросов преобразуются в столбцы, включая параметры в пути (path), query-параметры и заголовки.

  • Поля в ответах HTTP OK (200) преобразуются в столбцы таблиц.

  • Сгенерированные столбцы уникальны:

    • Если ответ сервера содержит поля с одинаковыми именами, но разными типами данных, такому полю добавляется постфикс _2, _3 и так далее.

    • Если в запросе к серверу присутствует поле, у которого есть такое же наименование в ответе, к имени поля из тела запроса добавляется постфикс _req.

Расширения OpenAPI

OpenAPI поддерживает пользовательские расширения, которые указываются в схеме с помощью блоков с префиксом x-. Расширения OpenAPI могут использоваться для тонкой настройки или для реализации дополнительных возможностей коннектора (например, x-unwrap, x-pagination).

РЕКОМЕНДАЦИЯ
Если схема OpenAPI, возвращаемая REST-сервером, не может быть изменена для включения расширений x-, можно сохранить файл схемы локально и изменить его при необходимости.

Сообщения об ошибках

Когда коннектор обращается к API и получает ошибку, клиенту Trino возвращается ошибка SQL. Обычно такие ошибки содержат только код HTTP-ответа, а сообщение ошибки не отображается (сообщение может быть нечитаемым или содержать конфиденциальные данные).

Для отображения информативных сообщений об ошибках, используйте свойство errorPath в блоке x-trino OpenAPI-схемы. Например:

paths:
  /records:
    get:
      responses:
        # ...
      x-trino:
       errorPath: "$response.body#/message"

Дополнительные возможности и ограничения

Реализация коннектора, поставляемая с ADH, включает некоторые улучшения и дополнительные возможности, а именно:

  • Распаковка массивов. При анализе HTTP-ответа коннектор может автоматически "распаковать" содержимое полей с массивами.

  • Пагинация (pagination) для сдвига LIMIT. Позволяет получать от REST API разбитые на страницы (page) ответы.

Ограничения

Коннектор имеет следующие ограничения:

  • Ограниченная поддержка операций INSERT/DELETE/UPDATE. Коннектор рекомендуется использовать только для операций чтения.

  • Ограниченная поддержка pushdown-предикатов. Pushdown-предикаты корректно работают только с API, которые поддерживают фильтрацию параметров запроса и полностью описаны в OpenAPI-схеме. Могут наблюдаться проблемы с производительностью на больших объемах данных, поскольку из-за отсутствия pushdown-предикатов коннектор сначала загружает весь набор данных в память и только затем выполняет фильтрацию.

Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней