Версия: Графиня 2025H2

Документация по разработке плагинов

Эта документация описывает, как создать плагин-источник данных для Графини по публичному контракту. Плагин предоставляет HTTP API, а Графиня обращается к нему через backend.

Полезные файлы

OpenAPI: swagger.json
Postman: collection.json

Базовый URL

Плагин должен быть доступен по базовому URL, который уже включает /api/v1:

Пример: http://plugin-domain/api/v1

Все эндпоинты ниже указаны относительно этого базового URL.

Локализация

Для эндпоинтов, возвращающих метаданные полей, Графиня передает заголовок Accept-Language.

Заголовок: Accept-Language: ru-RU (или другой локаль)
Используйте его для локализации name, description, placeholder, label и т.п.

Общий порядок работы

Метаданные плагина
- GET /well-known
- Графиня читает имя, версию, заголовок, описание.
Проверка соединения
- POST /datasource/health-check
- Проверяет валидность и доступность соединения по указанным параметрам.
Конструктор полей источника
- POST /datasource/constructor-fields
- Возвращает поля, зависящие от уже введенных значений.
Конструктор полей запроса
- POST /query/constructor-fields
- Возвращает поля для построения запросов.
Выполнение запросов
- POST /query/get-result
- Возвращает данные по запросу. Поддерживаются два контракта ответа (timestamp и regular).
Переменные
- POST /variable/constructor-fields
- POST /variable/values
- Используется для построения запросов переменных и возврата значений.

Эндпоинты

GET /well-known

Возвращает метаданные плагина.

Ответ (пример):

{
  "name": "prometheus",
  "title": [
    { "lang": "ru-RU", "value": "Prometheus" },
    { "lang": "en-US", "value": "Prometheus" }
  ],
  "version": "1.2.0",
  "description": [
    { "lang": "ru-RU", "value": "Плагин для метрик" },
    { "lang": "en-US", "value": "Metrics plugin" }
  ],
  "queryHelp": [
    { "lang": "ru-RU", "value": "Поддерживаются метрики PromQL" },
    { "lang": "en-US", "value": "PromQL metrics are supported" }
  ],
  "baseUrl": "http://plugin-domain/api/v1"
}

POST /datasource/health-check

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

к сведению

Если в конфиге есть чувствительные поля (например, пароли), рекомендуется зашифровать их на стороне плагина в ответе на /datasource/health-check. Далее используйте и возвращайте эти значения только в зашифрованном виде.

Запрос (пример):

{
  "fields": [
    {
      "code": "url",
      "name": "URL",
      "description": "Путь к источнику данных",
      "placeholder": "Введите валидный URL",
      "validationRule": "^https?:\\/\\/",
      "validationMessage": "Значение должно быть валидным URL",
      "required": true,
      "value": "http://prometheus"
    }
  ]
}

Ответ (пример):

{
  "status": true,
  "datasourceConfig": {
    "fields": [
      {
        "code": "url",
        "name": "URL",
        "description": "Путь к источнику данных",
        "placeholder": "Введите валидный URL",
        "validationRule": "^https?:\\/\\/",
        "validationMessage": "Значение должно быть валидным URL",
        "required": true,
        "value": "http://prometheus"
      }
    ]
  }
}

POST /datasource/constructor-fields

Возвращает поля конструктора конфигурации источника.

Заголовки:

Accept-Language

Запрос (пример):

{
  "pluginContext": {
    "orgID": 0,
    "pluginID": "pult1",
    "dataSourceInstanceSettings": {
      "fields": []
    }
  },
  "filter": {
    "from": 1729848300,
    "to": 1729870200,
    "fields": []
  },
  "variables": {}
}

Ответ (пример):

[
  {
    "code": "url",
    "name": "URL",
    "type": "text",
    "description": "Путь к источнику данных",
    "placeholder": "Введите валидный URL",
    "validationRule": "^https?:\\/\\/",
    "validationMessage": "Значение должно быть валидным URL",
    "required": true
  }
]

POST /query/constructor-fields

Возвращает поля конструктора запроса.

Графиня поддерживает три режима построения запросов: Код, JSON, Конструктор.

Режим "Код" включается при двух условиях:

В конфиге источника данных должны быть заданы codeMode: "true" и codeLang (они приходят в dataSource.configFields). Без codeLang вкладка/переключатель "Код" не показывается.
Пользователь должен вручную переключить вид запроса на "Код" (radio-переключатель queryType).

Если codeLang отсутствует, опция "Код" скрывается, и режим автоматически возвращается в fields.

Заголовки:

Accept-Language

Запрос (пример):

{
  "pluginContext": {
    "orgID": 0,
    "pluginID": "pult1",
    "dataSourceInstanceSettings": {
      "fields": []
    }
  },
  "filter": {
    "from": 1729848300,
    "to": 1729870200,
    "fields": []
  },
  "variables": {}
}

Ответ (пример):

[
  {
    "code": "type",
    "name": "Тип",
    "description": "Тип файла",
    "type": "select",
    "props": {
      "options": [
        { "value": "json", "label": "JSON" }
      ]
    }
  }
]

POST /query/get-result

Выполняет запрос(ы) данных. Можно передать несколько запросов в dataQuery.

Запрос (пример):

{
  "pluginContext": {
    "orgID": 0,
    "pluginID": "pult1",
    "dataSourceInstanceSettings": {
      "fields": [
        {
          "code": "url",
          "name": "URL",
          "description": "Путь к источнику данных",
          "placeholder": "Введите валидный URL",
          "validationRule": "^https?:\\/\\/",
          "validationMessage": "Значение должно быть валидным URL",
          "required": true,
          "value": "http://prometheus"
        }
      ]
    }
  },
  "dataQuery": [
    {
      "refID": "id1",
      "maxDataPoints": 1000,
      "timeRange": {
        "from": 1729848300,
        "to": 1729870200
      },
      "json": "{\"metricName\":\"jvm_threads_daemon_threads\",\"serieName\":\"Потоки\",\"selectors\":{\"application\":\"prometheus-plugin-data\"}}"
    }
  ],
  "variables": {}
}

Ответ (timestamp контракт, пример):

{
  "status": 200,
  "frames": [
    {
      "refID": "id1",
      "fields": [
        {
          "name": "Потоки",
          "refID": "id1",
          "values": [
            { "1730298165": "10" },
            { "1730298180": "13" }
          ]
        }
      ]
    }
  ]
}

Ответ (regular контракт, пример):

{
  "status": 200,
  "frames": [
    {
      "refID": "id1",
      "fields": [
        {
          "name": "Row",
          "refID": "id1",
          "values": [
            { "label": "A", "value": 10 },
            { "label": "B", "value": 20 }
          ]
        }
      ]
    }
  ]
}

POST /variable/constructor-fields

Возвращает поля конструктора запроса переменных.

Заголовки:

Accept-Language

Запрос (пример):

{
  "pluginContext": {
    "orgID": 0,
    "pluginID": "pult1",
    "dataSourceInstanceSettings": {
      "fields": []
    }
  },
  "filter": {
    "from": 1729848300,
    "to": 1729870200,
    "fields": []
  },
  "variables": {}
}

Ответ (пример):

[
  {
    "code": "url",
    "name": "URL",
    "type": "text",
    "description": "Путь к источнику данных",
    "placeholder": "Введите валидный URL",
    "validationRule": "^https?:\\/\\/",
    "validationMessage": "Значение должно быть валидным URL",
    "required": true
  }
]

POST /variable/values

Возвращает значения переменных.

Запрос (пример):

{
  "pluginContext": {
    "orgID": 0,
    "pluginID": "pult1",
    "dataSourceInstanceSettings": {
      "fields": []
    }
  },
  "json": "{}",
  "variables": {}
}

Ответ (пример):

[
  { "label": "CPU", "value": "cpu" },
  { "label": "RAM", "value": "ram" }
]

Контракты данных

Графиня поддерживает два типа контракта ответа для POST /query/get-result:

Timestamp
- Каждое значение поля — объект, где ключ — timestamp.
Regular
- Каждое значение поля — объект с произвольными ключами.

Поля конструктора

Поля конструктора используются в ответах /datasource/constructor-fields, /query/constructor-fields и /variable/constructor-fields. Они описывают, какие элементы интерфейса нужно показать пользователю.

Схема работы конструкторов

Ниже общая логика для конструкторов /datasource/constructor-fields, /query/constructor-fields, /variable/constructor-fields:

Первичный запрос из UI
- Если форма создается с нуля, в filter.fields отправляется пустой список [].
- Если форма открывается с сохраненным конфигом, в первом запросе передаются значения всех полей.
Повторные запросы по триггерам
- Поле считается триггерным, если у него задано isTrigger: true.
- При изменении значения любого триггерного поля UI отправляет повторный запрос и передает значения всех триггерных полей в filter.fields в формате { "key": "<code>", "value": "<value>" }.

Базовые поля

Поддерживаемые типы (type):

Тип	Что отображается	Скриншот
`text`	Однострочный текст
`password`	Пароль
`number`	Число
`textarea`	Многострочный текст
`select`	Выпадающий список
`radio`	Радиокнопки
`checkbox`	Чекбокс
`file`	Загрузка файла
`array`	Аккордион с вложенными полями

Общие поля (чаще всего используются):

code — ключ поля, используется в запросах.
name — отображаемое название.
description — подсказка/описание.
placeholder — плейсхолдер.
required — обязательность.
validationRule и validationMessage — валидация на клиенте.
readOnly — запрет редактирования.
value — предустановленное значение.
inline и size — управление расположением и шириной.
denyVariables — запрет подстановки переменных.

Вложенные поля (children)

Тип array отображает аккордион с наборами вложенных полей. Каждый элемент аккордиона — это отдельная группа (например, фильтр). В ответе нужно передать вложенные поля в props.fields. На фронте это преобразуется в children, а пользователю доступно добавление нескольких групп.

Пример:

{
  "code": "filters",
  "name": "Фильтры",
  "type": "array",
  "props": {
    "fields": [
      { "code": "key", "name": "Ключ", "type": "text" },
      { "code": "value", "name": "Значение", "type": "text" }
    ]
  }
}

Триггеры

Если поле помечено isTrigger: true, то при изменении значения Графиня повторно вызовет конструктор, чтобы получить обновленный набор полей. Это удобно, когда набор полей зависит от выбора пользователя.

Размеры и расположение

Для управления шириной поля используйте size:

xs — ~16.66%
sm — ~33.33%
md — ~50%
lg — ~66.64%
xl — ~83.3%
xxl — 100%

field_sizes

подсказка

Чтобы разместить несколько полей в одной строке, установите inline: true.

props в зависимости от типа

Ниже перечислены самые используемые props.

select / radio

props.options — массив { label, value }
props.allowHandwriting — разрешить ввод своего значения (select)
props.allowMultiSelect — разрешить множественный выбор (select)

number

props.min, props.max

file

props.maxFileSize — максимальный размер файла
props.acceptFile — допустимые расширения (например, .csv)

array

props.fields — массив вложенных ConstructorField

подсказка

ConstructorField.props.options всегда массив объектов { label, value }.
Для валидации используйте validationRule (regex) и validationMessage. Пример опции:

{ "label": "JSON", "value": "json" }

Полезные файлы​

Базовый URL​

Локализация​

Общий порядок работы​

Эндпоинты​

GET /well-known​

POST /datasource/health-check​

POST /datasource/constructor-fields​

POST /query/constructor-fields​

POST /query/get-result​

POST /variable/constructor-fields​

POST /variable/values​

Контракты данных​

Поля конструктора​

Схема работы конструкторов​

Базовые поля​

Вложенные поля (children)​

Триггеры​

Размеры и расположение​

props в зависимости от типа​

Полезные файлы

Базовый URL

Локализация

Общий порядок работы

Эндпоинты

GET /well-known

POST /datasource/health-check

POST /datasource/constructor-fields

POST /query/constructor-fields

POST /query/get-result

POST /variable/constructor-fields

POST /variable/values

Контракты данных

Поля конструктора

Схема работы конструкторов

Базовые поля

Вложенные поля (children)

Триггеры

Размеры и расположение

props в зависимости от типа