Настройка OpenAPI connector

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

Для настройки коннектора используются параметры, описанные в данной статье. Эти параметры можно указать при создании нового Trino-каталога с помощью ADCM или внутри предложения WITH, например:

CREATE CATALOG "openapi-catalog" USING openapi
WITH (
    "spec-location" = ...,
    "base-uri" = ...,
    ...
);
Параметр Описание

spec-location

URL или имя файла, содержащего схему OpenAPI (JSON/YAML)

base-uri

Базовый URL REST API

authentication.type

Тип аутентификации по умолчанию, который будет использоваться, если таковой не указан в схеме OpenAPI. Возможные значения: none, http, api_key, oauth

authentication.scheme

Схема аутентификации для типа аутентификации http. Возможные значения: basic, bearer

authentication.client-id

OAuth Client ID

authentication.client-secret

OAuth Client secret

authentication.username

Имя пользователя для типов аутентификации http и oauth

authentication.password

Пароль для типов аутентификации http и oauth

authentication.bearer-token

Bearer-токен для аутентификации http

authentication.api-key-name

Имя ключа API

authentication.api-key-value

Значение ключа API

max-requests-per-second

Максимальное количество HTTP-запросов в секунду, которые могут быть отправлены с одного узла Trino

max-splits-per-second

Максимальное количество сплитов (split) в секунду, генерируемых при выполнении запроса

Под капотом коннектор использует Airlift HTTP client, который поддерживает свой собственный набор параметров, например:

openApi.http-client.log.enabled=true
openApi.http-client.log.path=logs

Подробная информация о настройке клиента доступна на Github-странице проекта.

Распаковка массивов

При анализе HTTP-ответов от API коннектор может автоматически "распаковывать" поля с массивами. Например, коннектор получает следующий HTTP-ответ:

{
    "transactions_count": 10,
    "items":
    [
        {
            "txn_id": 1,
            "acc_id": 1002,
            "txn_value": 184.0,
            "txn_type": "withdrawal"
        },
        {
            "txn_id": 2,
            "acc_id": 1000,
            "txn_value": 282.95,
            "txn_type": "spb"
        },
        {
            "txn_id": 3,
            "acc_id": 1001,
            "txn_value": 100.00,
            "txn_type": "deposit"
        }
    ]
}

По умолчанию Trino преобразует поле items в одну строку таблицы, содержащую все элементы массива:

total_count|                                        items|
-----------+---------------------------------------------+
         10|[{"txn_id": 1, ...}, {"txn_id": 1, ...}, ...]|

Чтобы Trino "развернул" такой массив и представил его содержимое клиенту в виде отдельной таблицы, укажите блок x-unwrap в OpenAPI-схеме. Например, для вышеуказанного HTTP-ответа блок x-unwrap выглядит следующим образом:

 /transactions_batch:
    get:
      summary: Get Transactions Batch
      operationId: get_transactions_batch_transactions_batch_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionBatch'
      x-unwrap:
        resultParam: $response.body#/items (1)
        includeRoot: 'false' (2)
1 Поле HTTP-ответа, содержащее массив, который необходимо развернуть и отобразить в виде отдельной таблицы.
2 Указывает, следует ли включать дублирующиеся поля (transactions_count).

При такой конфигурации x-unwrap коннектор преобразует содержимое поля items в отдельную таблицу:

txn_id|acc_id|txn_value|txn_type  |
------+------+---------+----------+
     1|  1002|184.00   |withdrawal|
     2|  1000|282.95   |spb       |
     3|  1001|100.00   |deposit   |

Пагинация

Коннектор поддерживает пагинацию для pushdown-предиката LIMIT. Чтобы активировать пагинацию, укажите блок x-pagination на нужном эндпойнте в схеме OpenAPI:

x-pagination:
  pageParam: "page"
  limitParam: "size"
  resultsPath: "$response.body#/elements"
  totalResultsPath: "$response.body#/totalCount"

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

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