API MasterSCADA 4D > Подключение к исполнительной системе по JSON > HTTP API MasterPLC > Установка значений и вызов функциональных блоков

Вызывает программу или функциональный блок в указанной Lua-задаче, предварительно записав входные параметры. При запросе выходных параметров метод ждёт завершения вызова и возвращает их значения.

HTTP: POST /Methods/CallPOU

Запрос

{
  "sessionId": 123456789,
  "recs": [
    {
      "taskId": 0,
      "itemId": 30818,
      "path": "",
      "params": [
        {
          "name": "_x",
          "value": 2
        }
      ],
      "outParams": [
        {
          "name": "_y",
          "type": "LREAL"
        }
      ]
    }
  ]
}

Поля запроса

Поле	Тип	Обязательное	По умолчанию	Описание
sessionId	integer	условно	—	Нужен, если сессия не передана заголовком Session-Id
recs	array	да	—	Массив вызовов POU
recs[].taskId	integer	нет	0	Индекс локальной Lua-задачи, в которой выполняется POU
recs[].itemId	integer	да	0	Идентификатор программы, ФБ или содержащей его переменной из VMInfo
recs[].path	string	нет	""	Путь к вложенному POU внутри узла itemId
recs[].params	array	нет	пустой массив	Входные параметры, записываемые перед вызовом
recs[].params[].name	string	да	""	Имя входного параметра POU
recs[].params[].value	любое JSON-значение	да	—	Значение параметра; допускается также объект с вложенным полем value
recs[].outParams	array	нет	пустой массив	Запрашиваемые выходные параметры; непустой массив включает ожидание результата
recs[].outParams[].name	string	да	""	Имя выходного параметра POU
recs[].outParams[].type	string	нет	""	ST-тип, к которому сервер пытается привести значение ответа
recs[].callType	integer	нет	—	Устаревшее поле: текущая реализация его не читает
recs[].typeHash	integer	нет	0	Сохраняется в CallPOURec, но при выполнении не используется
recs[].params[].typeHash	integer	нет	—	Устаревшее поле: текущая реализация его не читает
recs[].outParams[].typeHash	integer	нет	—	Устаревшее поле: текущая реализация его не читает

Поле callType не управляет режимом вызова. Фактическое поведение определяется только outParams:

•нет выходных параметров — метод возвращает ответ сразу после постановки вызова в очередь;

•есть хотя бы один выходной параметр — метод ждёт выполнения POU.

Ответ с выходными параметрами

{
  "recs": [
    {
      "statusCode": 0,
      "outParams": [
        3.0
      ]
    }
  ],
  "serverTime": 1710000000123,
  "code": 0
}

Без outParams обычный ответ имеет вид:

{
  "recs": [
    {
      "statusCode": 0
    }
  ],
  "serverTime": 1710000000123,
  "code": 0
}

Поля ответа

Поле	Тип	Условие	Описание
recs	array	обычный ответ	Результаты принятых вызовов; важное исключение для отказа в правах описано ниже
recs[].statusCode	integer	всегда в возвращённой записи	Результат вызова либо предварительное значение для асинхронного режима
recs[].outParams	array	в запросе были outParams	Значения в том же порядке, что описания outParams в запросе; имена не повторяются
serverTime	integer	обычный ответ	Время сервера после завершения ожидания, Unix time в миллисекундах
code	integer	всегда	Общий результат метода

Поведение и ограничения

•При пустом outParams вызов выполняется асинхронно в следующем цикле задачи. Возвращаемый statusCode: 0 подтверждает постановку в очередь, но не результат будущего выполнения POU.

•При непустом outParams HTTP-обработчик ждёт завершения каждого такого вызова. Тайм-аут в текущей реализации отсутствует; если задача не обработает очередь, запрос может ожидать неограниченно долго.

•Если taskId не соответствует зарегистрированному DataSource, весь метод завершается корневой ошибкой OpcUa_BadNodeIdUnknown; подготовленные вызовы из того же пакета не ставятся в очередь.

•itemId: 0 с полным путём здесь не поддержан: LuaTask::CallPOUs разрешает адрес через VMInfo. В режиме с outParams невозможность построить Lua-путь возвращается как OpcUa_BadInvalidArgument; в асинхронном режиме эта поздняя ошибка в HTTP-ответ не попадает.

•Для явно указанной локальной задачи проверяется право Execute. В текущей реализации вызов без права молча исключается из recs ответа, а корневой code остаётся равным 0; поэтому длина массива ответа может оказаться меньше длины массива запроса. Это ограничение текущего C++-обработчика, а не рекомендуемый контракт клиента.

•Из-за разных значений по умолчанию в двух чтениях taskId его отсутствие приводит к выполнению в задаче 0, но пропускает проверку права Execute. Клиенту следует всегда передавать taskId явно.

•Неизвестный входной параметр не создаёт отдельную ошибку на этапе разбора: значение читается без типа, в коде оставлен TODO на возврат ошибки.

•Если среди выходных параметров есть Error со строкой "No permission to invoke the FB" или "Нет прав на вызов ФБ", statusCode заменяется на OpcUa_BadUserAccessDenied.

•При резервном состоянии контроллера корневой code равен OpcUa_BadShutdown.