Интеграционные хранилища и операции (API v2)

В платформе Пересвет есть базовая поддержка исторических данных (historian) и иерархической модели (LDAP). Для интеграции со “внешними” реляционными данными (справочники, планы, календари и т.п.) добавлен механизм интеграционных хранилищ и операций.

Ключевая идея: значения “интеграционного” тега берутся/пишутся не в автоматически создаваемую таблицу historian, а через параметризованный запрос, описанный в LDAP как операция.

Включение/выключение v2

Функциональность v2 является опциональной и может не запускаться в некоторых сборках/конфигурациях.

  • Для монолитного приложения one_app используется переменная окружения:

    • PRS_ENABLE_V2=1 (или true/yes/on) — включить v2 API и v2 model_crud.

    • если переменная не задана — работает только v1.

  • Для MCP сервера mcp_peresvet:

    • MCP_PERESVET_ENABLE_V2=1 включает MCP-инструменты для /v2.

    • если не задано — берётся значение PRS_ENABLE_V2.

Тип хранилища integrational

Для prsDataStorage тип хранилища задаётся атрибутом:

  • prsEntityTypeCode = 2 — integrational (PostgreSQL).

Операции в LDAP

Под узлом конкретного хранилища данных (<dataStorage>) в LDAP хранится:

  • cn=system.

  • Внутри cn=system узел cn=operations со списком операций.

  • Для каждой операции есть узел cn=<operationCn> (objectClass=prsDatastorageOperation) с атрибутами:

    • prsEntityTypeCode: 0 (GET) или 1 (SET).

    • prsJsonConfigString с JSON-свойствами операции:

      • query — текст запроса (строго параметризованный, :param).

      • prsTimeOutMs — таймаут выполнения/вычислений.

      • prsMaxRows — лимит строк для GET.

      • prsVersion — версия операции.

    • Дочерние узлы параметров cn=<paramName> (objectClass=prsDatastorageOperationParameter), где:

      • prsJsonConfigString — JSON с настройками параметра (например required/default/type).

Интеграционные теги

Привязка тега к хранилищу описывается узлом prsDatastorageTagData под cn=system/cn=tags.

Для интеграционного тега:

  • prsEntityTypeCode = 2

  • в prsJsonConfigString указываются ссылки на операции и маппинг параметров:

{
  "get": {
    "operationCn": "oee.downtimeReasons.interval.v1",
    "params": {
      "start": "$.start",
      "finish": "$.finish"
    }
  },
  "set": {
    "operationCn": "oee.downtimeReasons.set.v1",
    "params": {
      "code": "$.point.y.code"
    }
  }
}

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

Контракт результата GET

GET-операция обязана возвращать колонки (или поля результата):

  • y, x, q

Сервис интеграционного хранилища преобразует результат в стандартный ответ data/get:

{
  "data": [
    {
      "tagId": "<tagId>",
      "data": [["<y1>", "<x1>", "<q1>"], ["<y2>", "<x2>", "<q2>"]]
    }
  ]
}

API v2 для dataStorages

В v2 добавлены поля для операций:

  • operations в create/update

  • getLinkedOperations в read

  • unlinkOperations в update

Эндпоинты:

  • GET /v2/dataStorages — чтение (включая операции по флагу)

  • POST /v2/dataStorages — создание (включая операции)

  • PUT /v2/dataStorages — обновление (включая операции)

Примечание про GET-параметры

Начиная с текущей версии рекомендуется передавать параметры GET-запросов как обычные query-параметры (id, base, scope, filter и т.д.), а не через q=<json>.