API коннектора¶

Аутентификация¶

Запросы из AW BI в коннектор выполняются без аутентификации.

Предупреждение

При настройке коннектора убедитесь, что он не доступен извне серверов, на которых работает AW BI.

Коды состояний¶

Код	Описание
200 - 299	Успешный запрос (OK)
202	Запрос получен, но ещё не обработан. Используется при асинхронной выгрузке данных в parquet
400 - 599	Ошибка

Обработка редиректов

Не гарантируется, что AW BI корректно обрабатывает редиректы, поэтому не возвращайте в методах коннектора статусы 300 - 399.

Операции¶

GET /health¶

Позволяет проверить, запущен ли коннектор и готов ли он к приему запросов.

Где используется /health

Данная операция обычно используется в health-checkers в Docker контейнерах и Kubernetes.

# my_connector.dockerfile
FROM ...
...
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl --fail http://127.0.0.1/health || exit 1

my-connector:
  build: ...
  ...
  healthcheck:
    test: ["CMD", "curl", "--fail", "http://127.0.0.1/health"]
    interval: 30s
    timeout: 10s
    start_period: 5s
    retries: 3

Параметры запроса¶

Нет

Пример запроса:

GET /health

Ответ¶

HTTP 200, если с коннектором всё хорошо, либо HTTP 400-599 и выше в противном случае

POST /data-source/ping¶

Проверяет, что источник данных доступен и подключение с ним устанавливается успешно.

Где используется data-source/ping

Операция data-source/ping вызывается при проверке подключения к источнику на форме редактирования параметров источника данных.

Тело запроса (JSON)¶

Параметр	Тип	Обязательно	Описание
`id`	integer		Идентификатор источника в AW BI
`type`	string	да	Тип источника
`params`	объект	да	Параметры подключения к источнику
`extra`	объект		Дополнительные параметры источника

Тело запроса операции /data-source/ping соответствует объекту DataSource за тем исключением, что идентификатор источника (id) может быть неизвестен в момент вызова операции (такое может случится для новых источников).

Пример запроса:

POST /data-source/ping
Content-Type: application/json

{
  "type": "my-data-source",
  "params": {
    "id": null,
    "db": "my data base",
    "host": "192.168.1.1",
    "port": 12345,
    "username": "aw",
    "password": "pass"
  },
  "extra": {}
}

Ответ¶

Если источник данных доступен, то необходимо вернуть HTTP 200 с любым (в т.ч., пустым) телом ответа.
При наличии ошибок подключения к источнику, необходимо вернуть HTTP со статусом 400 и выше и в теле ответа в поле detail вернуть текст сообщения, которое будет показано пользователю.

Пример ответа (200 OK):

{}

Пример ответа (400-599 ERROR):

{
  "detail": "Источник недоступен по адресу 192.168.1.1:12345"
}

POST /data-source/objects¶

Возвращает список объектов источника данных.

Где используется /data-source/objects

AW BI запрашивает список объектов при просмотре данных источника, а также при добавлении источника на странице редактирования модели.

Если пользователь в этих местах пользуется поиском, то указанное им значение передается в параметре query_string.

Тело запроса (JSON)¶

Параметр	Тип	Обязательно	Описание
`data_source`	DataSource	да	Описание источника данных
`query_string`	string	нет	Строка поиска, по которой должен быть отфильтрован список объектов
`flat`	boolean	нет	Указывает на требуемый формат предоставления ответа (плоский список объектов или вложенный). Если не указано, что считается `flat: true`

Пример запроса:

POST /data-source/objects
Content-Type: application/json

{
  "data_source": {
    "id": 10,
    "type": "my-data-source",
    "params": {
      "host": "192.168.1.1",
      "port": 12345,
      "db": "my data base",
      "username": "aw",
      "password": "pass"
    },
    "extra": {}
  },
  "query_string": "products",
  "flat": true
}

Ответ¶

При успешной обработке запроса (200 OK) возвращается:

в случае flat: true - плоский список объектов

[
  {
    "schema": "public", 
    "name": "products", 
    "type": "table"
  },
  {
    "schema": "public", 
    "name": "product_sales", 
    "type": "table"
  },
  {
    "schema": "work", 
    "name": "staff", 
    "type": "table"
  }
]

в случае flat: false - словарь, ключами которого являются названия схемы, а значениями - список названий входящих в схему объектов
```
{
  "public": ["products", "product_sales"],
  "work": ["staff"]
}
```

Пример ответа (400-599 ERROR):

{
  "detail": "Источник недоступен по адресу 192.168.1.1:12345"
}

POST /data-source/object-meta¶

Возвращает метаданные объекта источника.

Где используется data-source/object-meta

AW BI запрашивает метаданные объекта при просмотре источника

gри добавлении объектов из источника в редактируемую модель и обновлении структуры модели

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

Тело запроса (JSON)¶

Параметр	Тип	Обязательно	Описание
`data_source`	DataSource	да	Описание источника данных
`object_name`	string	да	Полное название объекта источника (с указанием схемы)

Пример запроса:

POST /data-source/object-meta
Content-Type: application/json

{
  "data_source": {
    "id": 10,
    "type": "my-data-source",
    "params": {
      "host": "192.168.1.1",
      "port": 12345,
      "db": "my data base",
      "username": "aw",
      "password": "pass"
    },
    "extra": {}
  },
  "object_name": "public.products",
}

Ответ¶

Возвращается объект ObjectMeta.

Пример ответа (200 OK):

{
  "columns": [
    {
      "name": "id",
      "type": "DECIMAL",
      "simple_type": "number",
      "comment": null,
    },
    {
      "name": "name",
      "type": "VARCHAR",
      "simple_type": "string",
      "comment": null,
    }
  ],
  "foreign_keys": [
    {
      "column_name": "id",
      "foreign_table_schema": "public",
      "foreign_table_name": "table1",
      "foreign_column_name": "id"
    }
  ]
}

Пример ответа (400-599 ERROR):

{
  "detail": "Источник недоступен по адресу 192.168.1.1:12345"
}

POST /data-source/object-data¶

Возвращает данные объекта источника для предпросмотра.

Где используется /data-source/object-data

AW BI запрашивает /data-source/object-data при открытии формы просмотра источника

Тело запроса (JSON)¶

Параметр	Тип	Обязательно	Описание
`data_source`	DataSource	да	Описание источника данных
`object_name`	string	да	Полное название объекта источника (с указанием схемы)
`page`	integer	нет по умолчанию, 1	Индекс страницы с данными (нумерация начинается с 1)
`page_size`	integer	нет по умолчанию, 20	Количество записей на странице

Пример запроса:

POST /data-source/object-data
Content-Type: application/json

{
  "data_source": {
    "id": 10,
    "type": "my-data-source",
    "params": {
      "host": "192.168.1.1",
      "port": 12345,
      "db": "my data base",
      "username": "aw",
      "password": "pass"
    },
    "extra": {}
  },
  "object_name": "public.products",
  "page": 1,
  "page_size": 20
}

Ответ¶

В ответе возвращается список строк c данными.

Пример ответа (200 OK):

[
  {"id": 1, "name": "Название 1", "date": "2025-08-01", "active": true},
  {"id": 2, "name": "Название 2", "date": "2025-08-02", "active": false},
  {"id": 3, "name": "Название 3", "date": null, "active": true}
]

Пример ответа (400-599 ERROR):

{
  "detail": "Источник недоступен по адресу 192.168.1.1:12345"
}

POST /data-source/sql-meta¶

Возвращает метаданные для SQL-объекта.

Где используется /data-source/sql-meta

Получение метаданных SQL-объекта происходит при добавлении SQL в модель данных

Тело запроса (JSON)¶

Параметр	Тип	Обязательно	Описание
`data_source`	DataSource	да	Описание источника данных
`sql_text`	string	да	Текст SQL запроса для выполнения в источнике.

Пример запроса:

POST /data-source/object-meta
Content-Type: application/json

{
  "data_source": {
    "id": 10,
    "type": "my-data-source",
    "params": {
      "host": "192.168.1.1",
      "port": 12345,
      "db": "my data base",
      "username": "aw",
      "password": "pass"
    },
    "extra": {}
  },
  "sql_text": "select * from products",
}

Ответ¶

Возвращается объект ObjectMeta.

Пример ответа (200 OK):

{
  "columns": [
    {
      "name": "id",
      "type": "DECIMAL",
      "simple_type": "number",
      "comment": null,
    },
    {
      "name": "name",
      "type": "VARCHAR",
      "simple_type": "string",
      "comment": null,
    }
  ],
  "foreign_keys": []
}

Пример ответа (400-599 ERROR):

{
  "detail": "Источник недоступен по адресу 192.168.1.1:12345"
}

POST /data-source/sql-object-data¶

Получение данных SQL-объекта.

Где используется /data-source/sql-object-data

Получение данных SQL-объекта происходит при добавлении SQL в модель данных (кнопка "Выполнить").

Тело запроса (JSON)¶

Параметр	Тип	Обязательно	Описание
`data_source`	DataSource	да	Описание источника данных
`object_name`	string	да	Полное название объекта источника (с указанием схемы)
`page`	integer	нет по умолчанию, 1	Индекс страницы с данными (нумерация начинается с 1)
`page_size`	integer	нет по умолчанию, 20	Количество записей на странице

Пример запроса:

POST /data-source/object-data
Content-Type: application/json

{
  "data_source": {
    "id": 10,
    "type": "my-data-source",
    "params": {
      "host": "192.168.1.1",
      "port": 12345,
      "db": "my data base",
      "username": "aw",
      "password": "pass"
    },
    "extra": {}
  },
  "sql_text": "select * from products",
  "page": 1,
  "page_size": 20
}

Ответ¶

В ответе возвращается список строк c данными.

Пример ответа (200 OK):

[
  {"id": 1, "name": "Название 1", "date": "2025-08-01", "active": true},
  {"id": 2, "name": "Название 2", "date": "2025-08-02", "active": false},
  {"id": 3, "name": "Название 3", "date": null, "active": true}
]

Пример ответа (400-599 ERROR):

{
  "detail": "Источник недоступен по адресу 192.168.1.1:12345"
}

POST /data-source/parquet¶

Выгружает данные источника в S3 хранилище в виде parquet файлов.

Где используется выгрузка в parquet

При предпросмотре данных модели, а также при загрузке её данных.

Тело запроса (JSON)

Параметр	Тип	Обязательно	Описание
`object`	ParquetObject	да	Описание объекта, данные которого нужно выгрузить в Parquet.
`folder`	string	да	Путь к S3 папке, в которую нужно выгрузить данные. Путь начинается с `s3://` и далее следует путь в специально выделенном для ETL процессов бакете. Пример значения: `s3://runs/2025-08-21_01-02-03-preview-68d9/products.parquet`.
`filters`	ParquetFilterExpr[ ]	нет	Список условий, которые нужно применить к выборке данных. Условия соединяются через AND.
`limit`	integer	нет	Ограничение на количество записей, которые нужно выгрузить в parquet.

Пример запроса

POST /data-source/parquet (асинхронная версия)¶

AW BI поддерживает асинхронную версию запроса на выгрузку данных в parquet.

Схема работы асинхронной версии:

AW BI отправляет в коннектор запрос POST /data-source/parquet с обычными для операции параметрами;
Коннектор запускает своими внутренними средствами задачу на выгрузку данных в parquet и, не дожидаясь окончания задачи, отправляет ответ со статусом HTTP 202 и пустым телом ответа. При этом, в заголовках ответа коннектор указывает значения:
- Location: URL, по которому AW BI должен сделать запрос позже;
- Retry-After: количество секунд, через которое AW BI должен сделать GET запрос по URL из Location;
Через указанное в Retry-After количество секунд AW BI делает GET запрос по URL из Location;
Если коннектор отвечает HTTP 200, то выгрузка готова. Если HTTP 202, то в заголовках ответа опять указываются значения Location и Retry-After и переходим на шаг 3.

Пример:

Время	Запрос в коннектор	Ответ	Что произошло
13:00:00	`POST /data-source/parquet`	HTTP 202 `Location: /data-source/parquet/queue/3f84b012` `Retry-After: 15`	Коннектор запустил задачу на выгрузку данных в parquet с task_id=3f84b012
13:00:15	`GET /data-source/parquet/queue/3f84b012`	HTTP 202 `Location: /data-source/parquet/queue/3f84b012` `Retry-After: 15`	Выгрузка ещё не завершена
13:00:30	`GET /data-source/parquet/queue/3f84b012`	HTTP 202 `Location: /data-source/parquet/queue/3f84b012` `Retry-After: 15`	Выгрузка ещё не завершена
13:00:45	`GET /data-source/parquet/queue/3f84b012`	HTTP 200	Выгрузка завершена

Синхронную и асинхронную версии запроса /data-source/parquet можно совмещать:

Если в запросе /data-source/parquet указывается параметр limit, то это означает что AW BI в данный момент подготавливает данные модели для их предпросмотра пользователем. В этом случае из-за ограниченности объема выгружаемых данных можно запустить использовать синхронную версию обработки запроса, чтобы пользователь получил ответ как можно раньше;
Если параметр limit не указан, то это означает, что выполняется полная загрузка данных модели, и можно использовать асинхронную версию запроса для оптимизации затрачиваемых ресурсов.

Типы данных¶

SimpleType¶

Перечисление типов полей AW BI.

Тип	Описание
`string`	Строка
`number`	Целое число
`float`	Число с плавающей точкой
`date`	Дата и Дата+Время
`bool`	Логическое

DataSource¶

Описывает параметры подключения к источнику данных.

Параметр	Тип	Обязательно	Описание
`id`	integer	нет	Идентификатор источника данных в AW BI
`type`	string	нет	Тип источника
`params`	dict	нет	Словарь с параметрами подключения к источнику
`extra`	dict	да	Дополнительные параметры источника

Пример:

{
  "id": 10,
  "type": "my-connector",
  "params": {
    "host": "192.168.1.1",
    "port": 12345,
    "db": "my data base",
    "username": "aw",
    "password": "pass",
    "use_ssh": false,
    "use_ssl": false,
    "ssh_host": null,
    "ssh_port": 0,
    "ssh_username": null,
    "ssh_password": null
  },
  "extra": {}
}

Параметры подключения к источнику (params)¶

Параметры подключения к источнику (значения словаря params) указываются на основе значений, которые пользователь вводит на странице создания источника данных.

Обязательные параметры:

Параметр	Тип	Поле с формы настройки источника
`host`	string	"Имя хоста"
`port`	integer	"Порт"
`db`	string	"Имя базы данных"
`username`	string	"Логин"
`password`	string	"Пароль"

Обязательность полей

Система требует заполнения всех обязательных полей с формы настройки источника. Если для конкретного источника какой-нибудь из параметров не является обязательным, то при создании источника в соответствующее поле можно ввести любое значение, а при обработке в кастомном коннекторе просто игнорировать это значение.

Параметры защищенного соединения (доступны для ввода при выборе типа соединения "Защищенное")

Параметр	Тип	Поле с формы настройки источника
`use_ssh`	boolean	true, если пользователь включает "SSH - соединение"
`ssh_host`	string	"Имя хоста" с панели "SSH - соединение"
`ssh_port`	integer	"Порт" с панели "SSH - соединение"
`ssh_username`	string	"Логин" с панели "SSH - соединение"
`ssh_password`	string	"Пароль" с панели "SSH - соединение"
`use_ssl`	boolean	true, если пользователь включает "SSL - соединение"

Дополнительные параметры источника (extra)¶

В дополнительных параметрах источника (словарь extra) указываются значения, которые пользователь заполняет на вкладке "Параметры".

В этом случае, в extra будут указаны следующие значения:

{
  ...,
  "extra": {
    "Таймаут": "1000",
    "ПостраничныйВывод": "Да"
  }
}

DataSourceObject¶

Объект источника данных

Параметр	Тип	Обязательно	Описание
`schema`	string	да	Название схемы, в которой находится объект. Аналог `public` в названиях таблиц PostgreSQL
`name`	string	да	Название объекта
`type`	string	да	Тип объекта. Рекомендуется всегда указывать `table`

ObjectMeta¶

Метаданные объекта источника данных

Параметр	Тип	Обязательно	Описание
`columns`	ObjectColumnMeta[ ]	да	Список столбцов объекта
`foreign_keys`	ForeignKeyMeta[ ]	да	Список связей (внешних ключей) объекта

Использование связей объекта

Заполнение foreign_keys не является обязательным для работы AW BI. Однако если они будут указаны, то при создании моделей данных связи между объектами будут настроены автоматически.

ObjectColumnMeta¶

Описание столбца в источнике данных.

Параметр	Тип	Обязательно	Описание
`name`	string	да	Название столбца
`type`	string	да	Название типа данных, как оно принято в источнике. Например, `VARCHAR(10)`
`simple_type`	string of SimpleType	да	Тип столбца для использования в AW BI.
`comment`	string	нет	Комментарий. Может содержать русскоязычное название столбца

ForeignKeyMeta¶

Описание связи объекта с другими объектами источника.

Параметр	Тип	Обязательно	Описание
`column_name`	string	да	Название столбца текущего объекта
`foreign_table_schema`	string	да	Название схемы связанного объекта
`foreign_table_name`	string	да	Название связанного объекта
`foreign_column_name`	string	нет	Название столбца связанного объекта

ParquetObject¶

Описывает объект при выгрузке данных в parquet.

Параметр	Тип	Обязательно	Описание
`data_source`	DataSource	да	Описание источника данных
`type`	string	да	Тип объекта: `sql` или значение, полученное
`name`	string	да	Если `type: sql`, то тут указывается любое значение. Иначе, полное название объекта источника (вместе со схемой)
`query_text`	string	да, если `type: sql`	Текст SQL запроса для получения данных
`fields`	ParquetObjectFields[ ]	нет	Список столбцов объекта, которые нужно выгрузить в parquet. Если значение не указано, то выгружаются все столбцы объекта источника (SQL-объекта).

ParquetObjectField¶

Описывает поле (столбец) объекта выгрузки в parquet.

Параметр	Тип	Обязательно	Описание
`name`	string	да	Название поля
`type`	string of SimpleType	да	Тип поля AW BI

ParquetFilterExpr¶

Описывание условие фильтрации данных при выгрузке данных в parquet

Параметр	Тип	Обязательно	Описание
`field_name`	string	нет	Название поля
`operator`	string	нет	Оператор условия
`value`	string	да	Значение

Условие интерпретируется коннектором следующим образом:

Если заполнены field_name и operator, то условием фильтрации будет {field_name} {operator} {value}
Иначе, условием фильтрации будет {value}

Примеры:

{
  "field_name": "id",
  "operator": ">",
  "value": "1"
}

// Условие: id > 1

{
  "field_name": "name",
  "operator": "IN",
  "value": "('name 1', 'name 2')"
}

// Условие: name IN ('name 1', 'name 2')

{
  "value": "id < 4"
}

// Условие: id < 4

Пример коннектора¶

С полным примером реализации API коннектора на языке Python с использованием FastAPI можно ознакомиться в репозитории aw_connector_example.

Подробная инструкция по запуску коннектора и просмотра Swagger документации по API приведена в README.md проекта.

Если коротко, то для просмотра Swagger документации коннектора нужно:

Убедиться, что установлен Docker;
Cклонировать репозиторий;
Скопировать файл .env.dist в .env. Заменить в .env файле значение CONNECTOR_PORT на, скажем CONNECTOR_PORT=9911;
Запустить коннектор docker compose build && docker compose up -d;
Перейти в браузере по адресу http://127.0.0.1:9911/docs.

Тестирование API коннектора¶

В репозитории aw_connector_tester есть специальный тестер, который прогоняет тесты API коннектора без его подключения к AW BI.

Клонируйте репозиторий на ской компьтер и следуйте документации тестера для настройки сценариев тестирования вашего коннектора.